Content Generation API (Video / Image / Audio / Music)

Generate video, image, audio (TTS) and music with Onysoft AI Gateway. Use generation models such as Veo, Runway, Kling, Wan, Hailuo, Seedream, Flux, GPT Image, Imagen, Nano Banana, Ideogram, Grok Imagine, ElevenLabs and Suno through a single asynchronous backend.

bolt

5 endpoints, 1 shared backend

There are 5 endpoint names for the generation flow, and they all connect to the same backend. Which one you use is purely semantic — it is meant to make your code more readable. The returned task_id is queried the same way for all of them.

Endpoint Names (Aliases)

The 5 endpoints below are fully equivalent. Whichever you send, the same backend runs and the same task_id format is returned. For semantic clarity, prefer the one that fits your model type.

EndpointRecommended UseExample Models
POST /v1/video/generate Video generation veo 3.1, kling, runway, wan, hailuo, grok-imagine
POST /v1/image/generate Image generation seedream, flux, imagen, nano-banana, ideogram, grok-imagine, gpt-image
POST /v1/audio/generate Audio generation (general) elevenlabs/text-to-speech-multilingual-v2, elevenlabs/text-to-speech-turbo-2-5
POST /v1/voice/generate Speech generation (TTS) elevenlabs/text-to-speech-multilingual-v2, turbo-2-5
POST /v1/music/generate Music generation ai-music-api/generate, mashup, extend, sounds
info

Status Lookup Endpoints

Whichever alias you used for generation, you can use the same alias for status lookup (or any of them — the task_id is global).

  • GET /v1/video/status/{task_id}
  • GET /v1/image/status/{task_id}
  • GET /v1/audio/status/{task_id}
  • GET /v1/voice/status/{task_id}
  • GET /v1/music/status/{task_id}
info

Asynchronous Design

All of these endpoints work asynchronously. When you send a request you receive a task_id (HTTP 202). You use this ID to query the generation status and check whether your content is ready. Typical duration: image 10-30s, video 30-180s, TTS 5-15s, music 30-90s.

bolt

Text/Chat Exception

For text/chat models, use /v1/chat/completions (synchronous, streaming-capable — see Chat Completions). Special case: Google Gemini image models (gemini-*-image) are called through the chat completions endpoint (multimodal response).

Generate Video

POST /v1/video/generate

Starts a new video, image or music generation task.

Parameters

model string required

The video model. Example: google-veo-3.1-text-to-video-fast-720p, kling/v2-5-turbo-text-to-video-pro-5s, grok-imagine/text-to-video-480p. Current list: GET /v1/models

prompt string required

Video description (English recommended). Detailed and descriptive prompts produce better results.

aspect_ratio string optional

Aspect ratio: "16:9", "9:16", "1:1". Default: "16:9"

duration integer optional

Video duration (seconds). For models priced per second the charge is multiplied by this value. If omitted, the model default is used (5 on most models, 6 on some). The accepted range varies by model (for example 4–12, 3–15 or 6–30 seconds); a value outside the range is rejected with a 400 error that states the valid range. On flat per-generation models the duration is tied to the model id and this field is ignored.

image_url string required for i2v/i2i

Source image. Required for image-to-video and image-to-image models. Can be a public HTTP URL or a base64 data URI.

image string optional

Alternative to image_url. A base64-encoded image. The system automatically saves it to a temp file and produces a public URL.

resolution string optional

Resolution. Supports different values per model: "720p", "1080p" (video), "1K", "2K", "4K" (image). The backend selects the correct value automatically.

quality string optional

Quality level. "high", "standard", "low". Used only with the gpt-image and seedream models.

negative_prompt string optional

Unwanted elements. Specify which object/style/color you do not want generated.

Example Requests

Video Generation (Text-to-Video)

cURL
curl -X POST https://api.onysoft.com/v1/video/generate \
  -H "Authorization: Bearer sk-ony-YOUR-KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google-veo-3.1-text-to-video-fast-720p",
    "prompt": "A golden retriever running through a field of sunflowers at sunset",
    "aspect_ratio": "16:9",
    "duration": 5
  }'

Image Generation (Text-to-Image)

cURL
curl -X POST https://api.onysoft.com/v1/video/generate \
  -H "Authorization: Bearer sk-ony-YOUR-KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/imagen4-fast-t2i",
    "prompt": "A beautiful sunset over mountains, photorealistic, 4K",
    "aspect_ratio": "16:9"
  }'

Image Editing (Image-to-Image)

cURL
curl -X POST https://api.onysoft.com/v1/video/generate \
  -H "Authorization: Bearer sk-ony-YOUR-KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream/4.5-edit-i2i",
    "prompt": "Change background to a futuristic city",
    "image_url": "https://example.com/input.jpg",
    "aspect_ratio": "1:1"
  }'

Music Generation

cURL
curl -X POST https://api.onysoft.com/v1/video/generate \
  -H "Authorization: Bearer sk-ony-YOUR-KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ai-music-api/generate",
    "prompt": "Upbeat electronic dance music with catchy female vocals about summer"
  }'

Example Response

JSON Response
{
  "success": true,
  "data": {
    "task_id": "vtask_abc123...",
    "status": "pending",
    "model": "google-veo-3.1-text-to-video-fast-720p",
    "estimated_cost": {
      "amount_usd": 0.45,
      "amount_try": 22.07,
      "currency": "USD",
      "billed_units": 1,
      "unit": "uretim"
    }
  }
}
payments

Charges are per unit

estimated_cost gives the estimated amount in USD and TRY (the amounts in the example are illustrative). billed_units is the number of billed units and unit is the unit: total = unit price × billed_units. Video models are priced per second or per generation, depending on the model; for per-second models billed_units is the request's duration, so a 10-second video costs 10 times the per-second price. On flat per-generation models billed_units is 1 and the duration does not change the price. Each model's unit is given in the pricing.unit field of the GET /v1/models response and next to the price on the models page. The charge is deducted from your balance once the generation completes successfully; failed generations are not charged. The final amount is in the cost field of the status response once the task completes; the TRY amount uses the exchange rate at the time of charging.

Status Lookup

GET /v1/video/status/{task_id}

Queries the video generation status.

Status Values

StatusDescription
pendingRequest received, queued
processingVideo generation in progress
completedVideo ready, URL available
failedGeneration failed

Example Request

cURL
curl https://api.onysoft.com/v1/video/status/vtask_abc123 \
  -H "Authorization: Bearer sk-ony-YOUR-KEY"

Example Response (Completed)

JSON Response
{
  "success": true,
  "data": {
    "task_id": "vtask_abc123...",
    "status": "completed",
    "video_url": "https://...",
    "thumbnail_url": "https://...",
    "duration": 5,
    "model": "google-veo-3.1-text-to-video-fast-720p"
  }
}
schedule

Links are temporary: download your output

The video_url and thumbnail_url links are not permanent; they remain valid for about 14 days after generation. Download the file to your own storage once the task completes. After that period the link stops working.

Video List

GET /v1/video/list

Returns a list of generated videos.

Query Parameters

page integer optional

Page number. Default: 1

per_page integer optional

Records per page. Default: 20, Maximum: 100

Supported Models

The platform provides access to a wide range of video, image and music models. The model list is dynamic and updated continuously. For the current model list and prices, use the Models page or the GET /v1/models endpoint.

Video Models (Featured)

ModelProviderTypeDescription
google-veo-3.1-text-to-video-quality-1080pGoogleVideoVeo 3.1 - Highest quality (t2v/i2v)
google-veo-3.1-text-to-video-fast-720pGoogleVideoVeo 3.1 Fast - Fast generation
runway-text-to-video-5.0s-1080p-5s-1080pRunwayVideoGen-4 Turbo
kling/v2-5-turbo-text-to-video-pro-5sKlingVideoKling 2.5 Turbo Pro — speed/quality balance, 5s clips (flat price per generation)
kling-3.0-video-without-audio-720p-720p-silentKlingVideoKling 3.0 — priced per second, 3–15 s; multi-shot (multi_shots) support
wan/2-7-r2v-720pAlibabaVideoWan 2.7 — reference-to-video (r2v), 720p
hailuo/2-3-image-to-video-pro-6s-768pHailuoVideoHailuo 2.3 Pro (i2v)
grok-imagine/text-to-video-480pxAIVideoGrok Imagine Video

Image Models (Featured)

ModelProviderTypeDescription
grok-imagine/text-to-image-qualityxAIt2iGrok Imagine (most compatible)
google/imagen4-fast-t2iGooglet2iImagen 4 Fast
google/imagen4-ultra-t2iGooglet2iImagen 4 Ultra - Highest quality
google-nano-banana-2-1kGooglet2iNano Banana 2 (1K/2K/4K)
ideogram/v3-edit-quality-i2iIdeogrami2iIdeogram V3 Edit
flux-2/pro-text-to-imageFluxt2iFlux 2 Pro
flux-2/flex-text-to-imageFluxt2iFlux 2 Flex
seedream/4.5-text-to-imageByteDancet2iSeedream 4.5 (text-to-image)
seedream/4.5-edit-i2iByteDancei2iSeedream 4.5 Edit (image-to-image)
gpt-image-2-text-to-imageOpenAIt2iGPT Image 2 (text-to-image)
wan/2-7-image-proAlibabat2iWan 2.7 Image Pro

Audio Models (TTS / Sound Effect / Speech)

Audio generation via the ElevenLabs provider. Recommended endpoint: POST /v1/audio/generate or POST /v1/voice/generate.

ModelTypeDescriptionPrice (USD)
elevenlabs/text-to-speech-multilingual-v2TTSMultilingual TTS (29 languages including Turkish).$0.090
elevenlabs/text-to-speech-turbo-2-5TTSLow-latency TTS (English-weighted).$0.045

TTS Parameters

ParameterTypeDefaultDescription
promptstring—The text to voice (required)
voicestring"Rachel"Voice identifier. A value from the list below (case-sensitive).
stabilityfloat0.5Voice consistency (0.0 - 1.0). High = monotone, low = expressive.
similarity_boostfloat0.75Voice similarity (0.0 - 1.0).
stylefloat0.0Style intensity (0.0 - 1.0). Higher = more characterful.

Supported Voice List (ElevenLabs)

In the ElevenLabs TTS integration, only the following 20 voices are available. The values are case-sensitive — the first letter must be capitalized. If you send a voice outside the list, the API returns the error "This voice is not within the range of allowed options".

FemaleMale
Rachel (default), Alice, Aria, Charlotte, Jessica, Laura, Lily, Matilda, Sarah Brian, Bill, Callum, Charlie, Chris, Daniel, Eric, George, Liam, Roger, Will
info

For Turkish TTS

For Turkish text-to-speech you can use the synchronous POST /v1/audio/speech endpoint with the ema/ema-lightning model (free beta; details: Audio / Voice API). On the asynchronous path, elevenlabs/text-to-speech-multilingual-v2 supports 29 languages including Turkish; turbo-2-5 is English-weighted. ElevenLabs models may have temporary errors on the generation service side; failed generations are not charged.

TTS Example (Turkish, multilingual-v2)

cURL
curl -X POST https://api.onysoft.com/v1/voice/generate \
  -H "Authorization: Bearer sk-ony-YOUR-KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "elevenlabs/text-to-speech-multilingual-v2",
    "prompt": "Merhaba, ben Rachel. Onysoft AI üzerinden konuşuyorum.",
    "voice": "Rachel",
    "stability": 0.6,
    "similarity_boost": 0.8,
    "style": 0.1
  }'

Music Models

Suno-based models for song/music generation. Recommended endpoint: POST /v1/music/generate.

ModelProviderDescription
ai-music-api/generateSunoSuno V4 — Song generation (instrumental/vocal, multiple genres)
ai-music-api/generateOnysoftCreate a new song (Suno behind the scenes)
ai-music-api/extendOnysoftExtend an existing song
ai-music-api/mashupOnysoftCombine 2 songs
ai-music-api/soundsOnysoftSound effects
ai-music-api/upload-and-cover-audioOnysoftGenerate a cover from existing audio
ai-music-api/separate-vocalsOnysoftVocal/instrument separation
ai-music-api/create-music-videoOnysoftGenerate a visual video for music
ai-music-api/add-instrumentalOnysoftAdd instrumentals to existing vocals
ai-music-api/convert-to-wav-formatOnysoftMP3 → WAV conversion
suno-add-vocalsOnysoftAdd vocals to an instrumental
suno-extend-musicOnysoftExtend a Suno track
suno-generate-lyricsOnysoftLyrics generation
attach_money

Current Prices

Prices are updated dynamically and reflect the pricing applied to your project. Prices are per unit (a second, an image, 1,000 characters or a generation, depending on the model); for per-second video the total is the per-second price multiplied by the duration. For current pricing and units: call GET /v1/models (pricing.unit) or see the models page.

Per-Model Required Parameters

Each provider requires different parameters. The table below shows the parameters required for each model family. These parameters are filled in automatically on the backend — you only need to send prompt and, optionally, aspect_ratio.

ProviderModel FamilyAuto-Filled Parameters
Googleimagen4 / imagen4-fast / imagen4-ultraprompt (only)
xAIgrok-imagine/*aspect_ratio
Ideogramideogram/v3-edit-*-i2i, v3-remix-*-i2iprompt + image_url (i2i)
Ideogramideogram/character-*-i2ireference_image_urls (i2i)
Fluxflux-2/*aspect_ratio, resolution (1K/2K)
ByteDanceseedream/*quality, n, response_format, size, resolution (2K), aspect_ratio, background
OpenAIgpt-image-2-*quality, n, response_format, size, resolution, aspect_ratio, background
Alibabawan/2-7-image-*aspect_ratio, resolution (2K/4K)
Alibabawan video modelsduration, resolution (720p/1080p)
Googlenano-banana-edit-i2iimage_urls (i2i - image required)
lightbulb

i2i / i2v (image-to-image / image-to-video) Models

When sending a source image for image or video generation, follow this rule:

  • Single image: send image_url (string)
  • Multiple images (reference): send image_urls (array)
  • The backend automatically converts to the actual parameter name each provider expects (imageUrl, input_urls, first_frame_url, image_input, etc.)
  • As a value, use a public HTTP URL (https://...) or a base64 data URI (data:image/jpeg;base64,...) — if base64, the system automatically converts it to a public URL
  • Maximum total request size: 10 MB

Provider Parameter Mapping Matrix

The table below shows, for advanced use, the internal parameter names each provider expects. You do not need to know this detail in normal use — sending image_url or image_urls is enough; the backend converts automatically.

Model FamilyExpected ParameterTypeNote
seedream/4.5-edit-i2iimage_urlsarraySupports multiple references
flux-2/*-image-to-imageinput_urlsarraySupports resolution 1K/2K
gpt-image-2-image-to-imageinput_urlsarrayaspect_ratio + resolution required
google/nano-banana-edit-i2iimage_urlsarrayoutput_format (png/jpg) + image_size
google-nano-banana-2-1k / proimage_inputarrayAn empty array can also be sent (t2i mode)
ideogram/v3-edit-quality-i2i / remiximage_urlstring+ mask_url (optional)
ideogram/character-*-i2ireference_image_urlsarrayFor character reference
grok-imagine/image-to-imageimage_urlsarraynsfw_checker support
grok-imagine/image-to-video-720pimage_urlsarray+ duration, resolution, mode
kling-3.0 / kling-2.6 image-to-videoimage_urlsarrayKling 3.0: up to 2 images (first and last frame); others a single image. image_url / image are also accepted
hailuo/*-image-to-videoimage_urlstring+ duration (6/10)
wan/2-7-image-to-video-720pfirst_frame_urlstring+ last_frame_url (optional closing frame)
runway-image-to-video-*image_urlstringImage-to-video ids only; duration and resolution come from the model id
veo3* reference-to-videoimageUrlsarray (camelCase)+ generationType="REFERENCE_2_VIDEO"

Fields and rules by model family

The properties that set the price (resolution, audio, and the duration on flat-price models) come from the model id. If you also send the same property in the request it must match the id; otherwise the request is rejected with a 400 error that tells you which id to choose (nothing is generated at the wrong price). The fields below are in addition to the common ones (prompt, duration, aspect_ratio, image_url / image).

FamilyExtra fieldsRules
Kling 3.0
kling-3.0-video-*
image_urls, multi_shots, multi_prompt, mode, soundDuration 3–15 s (billed per second). aspect_ratio: 16:9, 9:16, 1:1. image_urls: up to 2 images (first and last frame). Multi-shot: multi_shots: true + multi_prompt (1–5 shots; each with a prompt of at most 500 characters and a duration of 1–12 s); the shot durations must add up to duration, multi-shot is available on the audio ids only and takes at most 1 image (first frame). mode (std / pro / 4K) and sound, if sent, must match the id.
Kling 3.0 Turbo
kling-3.0-turbo-*
image_urlsDuration 3–15 s (billed per second). Text-to-video: aspect_ratio 16:9, 9:16, 1:1. Image-to-video: one image is required.
Kling 2.6
kling-2.6/*
image_urls, soundDuration and audio come from the model id (flat price per generation). Image-to-video: one image is required. prompt up to 1000 characters.
Kling 2.5 Turbo Pro
kling/v2-5-turbo-*
negative_prompt, cfg_scale, tail_image_urlDuration comes from the model id (flat price per generation). cfg_scale 0–1. Image-to-video: an image is required, tail_image_url is an optional last frame.
Seedance 1.5 Pro
bytedance/seedance-1.5-pro-*
image_urls, generate_audio, fixed_lensDuration 4–12 s (billed per second). aspect_ratio: 1:1, 4:3, 3:4, 16:9, 9:16, 21:9 (1:1 if omitted). image_urls: up to 2 images (first and last frame). Audio is chosen by the model id (with-audio / without-audio); generate_audio, if sent, must match the id. fixed_lens: locked camera.
Seedance 2 / 2.5
bytedance/seedance-2-*
—Duration 4–15 s (Seedance 2.5: 4–30 s; billed per second). An image, if given, is used as the first frame.
Runway Gen-4 Turbo
runway-*
—Duration (5 or 10 s) and resolution come from the model id (flat price per generation). prompt up to 1800 characters. Text-to-video: aspect_ratio 16:9, 4:3, 1:1, 3:4, 9:16. On image-to-video ids an image is required and the ratio is taken from the image.
Grok Imagine video
grok-imagine/*-to-video-*
—Duration 6–30 s (billed per second). prompt up to 5000 characters.

Kling 3.0 multi-shot example

cURL
curl -X POST https://api.onysoft.com/v1/video/generate \
  -H "Authorization: Bearer sk-ony-YOUR-KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0-video-with-audio-720p-720p-audio",
    "aspect_ratio": "9:16",
    "duration": 6,
    "multi_shots": true,
    "multi_prompt": [
      {"prompt": "A cat jumps onto a wooden table", "duration": 3},
      {"prompt": "The cat looks straight at the camera", "duration": 3}
    ]
  }'

Cost and error fields

Once a task has finished, the GET /v1/video/status/{task_id} response includes a cost object: charged (whether you were charged), amount_usd, amount_try. For a failed generation charged is false and the amounts are 0. Rows of GET /v1/video/list carry the same information in charged, cost_usd and cost_try. A failed task returns error (Turkish), error_en (English) and, when the problem is an input field, error_param. If a generation request is rejected, the error object in the response contains message, message_en and, when applicable, param (the field to fix); rejected requests are not charged.

Note: prices depend on the key type. Personal keys use the list price; for project keys the price is set per project, and for partner customers the price is set by the partner.

Full Python Example (Polling)

Python
import time
import requests

API_KEY = "sk-ony-YOUR-KEY"
BASE = "https://api.onysoft.com/v1"

# 1. Video oluştur
resp = requests.post(f"{BASE}/video/generate",
    headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"},
    json={"model": "google-veo-3.1-text-to-video-fast-720p", "prompt": "A cat playing piano", "duration": 5}
)
task = resp.json()["data"]
task_id = task["task_id"]
print(f"Task: {task_id}, Status: {task['status']}")

# 2. Durum sorgula (polling)
while True:
    resp = requests.get(f"{BASE}/video/status/{task_id}",
        headers={"Authorization": f"Bearer {API_KEY}"})
    data = resp.json()["data"]
    print(f"Status: {data['status']}")
    if data["status"] == "completed":
        print(f"Video URL: {data['video_url']}")
        break
    elif data["status"] == "failed":
        print(f"Hata: {data.get('error')}")
        break
    time.sleep(10)  # 10 saniye bekle
Want help finding the right model?