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.
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.
| Endpoint | Recommended Use | Example 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 |
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}
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.
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
/v1/video/generate
Starts a new video, image or music generation task.
Parameters
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
Video description (English recommended). Detailed and descriptive prompts produce better results.
Aspect ratio: "16:9", "9:16", "1:1". Default: "16:9"
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.
Source image. Required for image-to-video and image-to-image models. Can be a public HTTP URL or a base64 data URI.
Alternative to image_url. A base64-encoded image. The system automatically saves it to a temp file and produces a public URL.
Resolution. Supports different values per model: "720p", "1080p" (video), "1K", "2K", "4K" (image). The backend selects the correct value automatically.
Quality level. "high", "standard", "low". Used only with the gpt-image and seedream models.
Unwanted elements. Specify which object/style/color you do not want generated.
Example Requests
Video Generation (Text-to-Video)
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 -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 -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 -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
{
"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"
}
}
}
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
/v1/video/status/{task_id}
Queries the video generation status.
Status Values
| Status | Description |
|---|---|
pending | Request received, queued |
processing | Video generation in progress |
completed | Video ready, URL available |
failed | Generation failed |
Example Request
curl https://api.onysoft.com/v1/video/status/vtask_abc123 \
-H "Authorization: Bearer sk-ony-YOUR-KEY"
Example Response (Completed)
{
"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"
}
}
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
/v1/video/list
Returns a list of generated videos.
Query Parameters
Page number. Default: 1
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)
| Model | Provider | Type | Description |
|---|---|---|---|
google-veo-3.1-text-to-video-quality-1080p | Video | Veo 3.1 - Highest quality (t2v/i2v) | |
google-veo-3.1-text-to-video-fast-720p | Video | Veo 3.1 Fast - Fast generation | |
runway-text-to-video-5.0s-1080p-5s-1080p | Runway | Video | Gen-4 Turbo |
kling/v2-5-turbo-text-to-video-pro-5s | Kling | Video | Kling 2.5 Turbo Pro — speed/quality balance, 5s clips (flat price per generation) |
kling-3.0-video-without-audio-720p-720p-silent | Kling | Video | Kling 3.0 — priced per second, 3–15 s; multi-shot (multi_shots) support |
wan/2-7-r2v-720p | Alibaba | Video | Wan 2.7 — reference-to-video (r2v), 720p |
hailuo/2-3-image-to-video-pro-6s-768p | Hailuo | Video | Hailuo 2.3 Pro (i2v) |
grok-imagine/text-to-video-480p | xAI | Video | Grok Imagine Video |
Image Models (Featured)
| Model | Provider | Type | Description |
|---|---|---|---|
grok-imagine/text-to-image-quality | xAI | t2i | Grok Imagine (most compatible) |
google/imagen4-fast-t2i | t2i | Imagen 4 Fast | |
google/imagen4-ultra-t2i | t2i | Imagen 4 Ultra - Highest quality | |
google-nano-banana-2-1k | t2i | Nano Banana 2 (1K/2K/4K) | |
ideogram/v3-edit-quality-i2i | Ideogram | i2i | Ideogram V3 Edit |
flux-2/pro-text-to-image | Flux | t2i | Flux 2 Pro |
flux-2/flex-text-to-image | Flux | t2i | Flux 2 Flex |
seedream/4.5-text-to-image | ByteDance | t2i | Seedream 4.5 (text-to-image) |
seedream/4.5-edit-i2i | ByteDance | i2i | Seedream 4.5 Edit (image-to-image) |
gpt-image-2-text-to-image | OpenAI | t2i | GPT Image 2 (text-to-image) |
wan/2-7-image-pro | Alibaba | t2i | Wan 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.
| Model | Type | Description | Price (USD) |
|---|---|---|---|
elevenlabs/text-to-speech-multilingual-v2 | TTS | Multilingual TTS (29 languages including Turkish). | $0.090 |
elevenlabs/text-to-speech-turbo-2-5 | TTS | Low-latency TTS (English-weighted). | $0.045 |
TTS Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
prompt | string | — | The text to voice (required) |
voice | string | "Rachel" | Voice identifier. A value from the list below (case-sensitive). |
stability | float | 0.5 | Voice consistency (0.0 - 1.0). High = monotone, low = expressive. |
similarity_boost | float | 0.75 | Voice similarity (0.0 - 1.0). |
style | float | 0.0 | Style 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".
| Female | Male |
|---|---|
Rachel (default), Alice, Aria, Charlotte, Jessica, Laura, Lily, Matilda, Sarah |
Brian, Bill, Callum, Charlie, Chris, Daniel, Eric, George, Liam, Roger, Will |
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 -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.
| Model | Provider | Description |
|---|---|---|
ai-music-api/generate | Suno | Suno V4 — Song generation (instrumental/vocal, multiple genres) |
ai-music-api/generate | Onysoft | Create a new song (Suno behind the scenes) |
ai-music-api/extend | Onysoft | Extend an existing song |
ai-music-api/mashup | Onysoft | Combine 2 songs |
ai-music-api/sounds | Onysoft | Sound effects |
ai-music-api/upload-and-cover-audio | Onysoft | Generate a cover from existing audio |
ai-music-api/separate-vocals | Onysoft | Vocal/instrument separation |
ai-music-api/create-music-video | Onysoft | Generate a visual video for music |
ai-music-api/add-instrumental | Onysoft | Add instrumentals to existing vocals |
ai-music-api/convert-to-wav-format | Onysoft | MP3 → WAV conversion |
suno-add-vocals | Onysoft | Add vocals to an instrumental |
suno-extend-music | Onysoft | Extend a Suno track |
suno-generate-lyrics | Onysoft | Lyrics generation |
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.
| Provider | Model Family | Auto-Filled Parameters |
|---|---|---|
| imagen4 / imagen4-fast / imagen4-ultra | prompt (only) | |
| xAI | grok-imagine/* | aspect_ratio |
| Ideogram | ideogram/v3-edit-*-i2i, v3-remix-*-i2i | prompt + image_url (i2i) |
| Ideogram | ideogram/character-*-i2i | reference_image_urls (i2i) |
| Flux | flux-2/* | aspect_ratio, resolution (1K/2K) |
| ByteDance | seedream/* | quality, n, response_format, size, resolution (2K), aspect_ratio, background |
| OpenAI | gpt-image-2-* | quality, n, response_format, size, resolution, aspect_ratio, background |
| Alibaba | wan/2-7-image-* | aspect_ratio, resolution (2K/4K) |
| Alibaba | wan video models | duration, resolution (720p/1080p) |
| nano-banana-edit-i2i | image_urls (i2i - image required) |
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 Family | Expected Parameter | Type | Note |
|---|---|---|---|
seedream/4.5-edit-i2i | image_urls | array | Supports multiple references |
flux-2/*-image-to-image | input_urls | array | Supports resolution 1K/2K |
gpt-image-2-image-to-image | input_urls | array | aspect_ratio + resolution required |
google/nano-banana-edit-i2i | image_urls | array | output_format (png/jpg) + image_size |
google-nano-banana-2-1k / pro | image_input | array | An empty array can also be sent (t2i mode) |
ideogram/v3-edit-quality-i2i / remix | image_url | string | + mask_url (optional) |
ideogram/character-*-i2i | reference_image_urls | array | For character reference |
grok-imagine/image-to-image | image_urls | array | nsfw_checker support |
grok-imagine/image-to-video-720p | image_urls | array | + duration, resolution, mode |
kling-3.0 / kling-2.6 image-to-video | image_urls | array | Kling 3.0: up to 2 images (first and last frame); others a single image. image_url / image are also accepted |
hailuo/*-image-to-video | image_url | string | + duration (6/10) |
wan/2-7-image-to-video-720p | first_frame_url | string | + last_frame_url (optional closing frame) |
runway-image-to-video-* | image_url | string | Image-to-video ids only; duration and resolution come from the model id |
veo3* reference-to-video | imageUrls | array (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).
| Family | Extra fields | Rules |
|---|---|---|
Kling 3.0kling-3.0-video-* | image_urls, multi_shots, multi_prompt, mode, sound | Duration 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 Turbokling-3.0-turbo-* | image_urls | Duration 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.6kling-2.6/* | image_urls, sound | Duration 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 Prokling/v2-5-turbo-* | negative_prompt, cfg_scale, tail_image_url | Duration 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 Probytedance/seedance-1.5-pro-* | image_urls, generate_audio, fixed_lens | Duration 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.5bytedance/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 Turborunway-* | — | 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 videogrok-imagine/*-to-video-* | — | Duration 6–30 s (billed per second). prompt up to 5000 characters. |
Kling 3.0 multi-shot example
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)
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