Generations API — every async image, video and audio route
One document for every generation route on api.sociaro.com. All of them work the same way: you
submit a job, you get an id back immediately, and you poll for the result. Nothing here holds a
connection open while a model renders.
This page is the /v1 family, except where a row says /v2. /v2/jobs shares that
submit-and-poll shape and nothing else: its own envelope, its own statuses, its own result field. For
how to call it, read Jobs API.
- Base URL:
https://api.sociaro.com - Auth:
Authorization: Bearer <your-api-key>on submit and on poll. POST /v1/videosserves no model in this document and answers404witherror.code: "wrong_endpoint", whose message names the route you actually want. It is the single most common wrong turn here — an OpenAI-style video route is what an agent guesses first. Use the table below.- Likewise, if you are guessing from
mode: video_generationon/model/info: that field says what a model produces, not where to send it./v1/modelsreturns only the OpenAI shape (id,object,created,owned_by), carries no routing information at all, and itsowned_byis always the literalopenaino matter who made the model — do not read a vendor out of it.
Which endpoint for which model
Generated from the live routing tables — if a model is in /v1/models, it is in this list.
| model id | where you send it |
|---|---|
alibaba/happyhorse-1-1-video |
submit POST /v1/alibaba/generations · poll GET /v1/alibaba/generations/{job_id} |
alibaba/happyhorse-1-1-video-i2v |
⤴ same as above |
alibaba/happyhorse-1-1-video-ref |
⤴ same as above |
alibaba/happyhorse-video-edit |
⤴ same as above |
alibaba/wan-3-video |
⤴ same as above |
alibaba/qwen-image-3 |
⤴ same as above |
alibaba/qwen-image-3-pro |
⤴ same as above |
alibaba/wan-2-7-image |
⤴ same as above |
alibaba/wan-2-7-image-pro |
⤴ same as above |
alibaba/wan-3-video-prime |
⤴ same as above |
alibaba/wan-2-7-t2v |
⤴ same as above |
alibaba/wan-2-7-i2v |
⤴ same as above |
alibaba/wan-2-7-r2v |
⤴ same as above |
alibaba/wan-2-7-videoedit |
⤴ same as above |
alibaba/wan-2-6-i2v-flash |
⤴ same as above |
alibaba/qwen-image-2-1-pro |
⤴ same as above |
alibaba/wan-2-6-image |
⤴ same as above |
ideogram/ideogram-4 |
submit POST /v1/ideogram/generations · poll GET /v1/ideogram/generations/{job_id} · or POST /v2/jobs |
ideogram/ideogram-4-transparent |
⤴ same as above |
ideogram/ideogram-3 |
⤴ same as above |
ideogram/ideogram-3-transparent |
⤴ same as above |
ideogram/ideogram-4-remix |
⤴ same as above |
ideogram/ideogram-3-remix |
⤴ same as above |
ideogram/ideogram-3-inpaint |
⤴ same as above |
ideogram/ideogram-3-reframe |
⤴ same as above |
ideogram/ideogram-3-replace-background |
⤴ same as above |
ideogram/ideogram-remove-background |
⤴ same as above |
ideogram/ideogram-vector |
⤴ same as above |
ideogram/ideogram-vectorize |
⤴ same as above |
ideogram/ideogram-4-5 |
⤴ same as above |
ideogram/ideogram-4-5-precise-edit |
⤴ same as above |
ideogram/ideogram-4-6 |
⤴ same as above |
ideogram/ideogram-4-6-precise-edit |
⤴ same as above |
recraft/recraft-v4-1-flash-v2 |
submit POST /v1/recraft/generations · poll GET /v1/recraft/generations/{job_id} · or POST /v2/jobs |
recraft/recraft-v4-1 |
⤴ same as above |
recraft/recraft-v4-1-vector |
⤴ same as above |
recraft/recraft-v4-1-pro |
⤴ same as above |
recraft/recraft-v4-1-pro-vector |
⤴ same as above |
recraft/recraft-vectorize |
⤴ same as above |
recraft/recraft-remove-background |
⤴ same as above |
recraft/recraft-crisp-upscale |
⤴ same as above |
recraft/recraft-creative-upscale |
⤴ same as above |
kling/kling-3.0-t2v |
submit POST /v1/kling/generations · poll GET /v1/kling/generations/{job_id} |
kling/kling-3.0-i2v |
⤴ same as above |
kling/kling-3.0-turbo-t2v |
⤴ same as above |
kling/kling-3.0-turbo-i2v |
⤴ same as above |
kling/kling-2.6-t2v |
⤴ same as above |
kling/kling-2.6-i2v |
⤴ same as above |
kling/kling-3.0-omni |
⤴ same as above |
kling/kling-v3 |
⤴ same as above |
kling/kling-v3-omni |
⤴ same as above |
kling/kling-4.0-t2v |
⤴ same as above |
kling/kling-4.0-i2v |
⤴ same as above |
kling/kling-4.0-omni |
⤴ same as above |
kling/kling-4.0-flash-t2v |
⤴ same as above |
kling/kling-4.0-flash-i2v |
⤴ same as above |
kling/kling-4.0-flash-omni |
⤴ same as above |
kling/kling-4.0-image |
submit POST /v1/kling/generations · poll GET /v1/kling/generations/{job_id}; or submit POST /v2/jobs · poll GET /v2/jobs/{id}, see Jobs API |
minimax/h3 |
submit POST /v2/jobs · poll GET /v2/jobs/{id} — /v2 only, see Jobs API |
minimax/h3-max |
⤴ same as above |
minimax/h3-highspeed |
⤴ same as above |
minimax/h3-lite |
⤴ same as above |
minimax/h3-regeneration |
⤴ same as above |
pixverse/v6 |
submit POST /v1/pixverse/generations · poll GET /v1/pixverse/generations/{job_id} |
pixverse/c1 |
⤴ same as above |
pixverse/video-expand |
⤴ same as above |
pruna/p-image |
submit POST /v1/pruna/generations · poll GET /v1/pruna/generations/{job_id} · or POST /v2/jobs |
pruna/p-image-edit |
⤴ same as above |
pruna/p-video |
⤴ same as above |
pruna/p-video-2-pro-reference |
⤴ same as above |
pruna/p-video-2-pro-avatar |
⤴ same as above |
pruna/p-video-upscale |
⤴ same as above |
pruna/p-video-2-pro-replace |
⤴ same as above |
sonilo/video-to-music |
submit POST /v1/sonilo/generations · poll GET /v1/sonilo/generations/{job_id} |
sonilo/video-to-sfx |
⤴ same as above |
bytedance/seedance-2.0 |
submit POST /v1/byteplus/contents/generations/tasks · poll GET .../tasks/{id} |
bytedance/seedance-2.0-fast |
⤴ same as above |
bytedance/seedance-2.0-mini |
⤴ same as above |
bytedance/seedance-2.5 |
⤴ same as above |
bytedance/seedance-2.5-flash |
⤴ same as above |
dreamina-seedance-2-0-260128 |
⤴ same as above — the vendor's own id for bytedance/seedance-2.0; either spelling works |
dreamina-seedance-2-5-260628 |
⤴ same as above — the vendor's own id for bytedance/seedance-2.5; either spelling works |
dreamina-seedance-2-5-flash-261115 |
⤴ same as above — the vendor's own id for bytedance/seedance-2.5-flash; either spelling works |
bytedance/seedream-4-0 |
submit POST /v1/byteplus/images/async · poll GET .../images/async/{job_id} (or sync POST /v1/byteplus/images/generations) — same route as its native id seedream-4-0-250828 below; either spelling works |
bytedance/seedream-4-5 |
⤴ same as above |
bytedance/seedream-5-lite |
⤴ same as above |
bytedance/seedream-5-pro |
⤴ same as above |
dola-seedream-5-0-pro-260628 |
⤴ same as above |
seedream-4-0-250828 |
⤴ same as above |
seedream-4-5-251128 |
⤴ same as above |
seedream-5-0-260128 |
⤴ same as above |
seedream-5-0-lite-260128 |
⤴ same as above |
bytedance/seedream-5-5 |
submit POST /v1/byteplus/images/async · poll GET .../images/async/{job_id} — async only (the synchronous route refuses it); same route as its native id dola-seedream-5-5-261028 |
dola-seedream-5-5-261028 |
⤴ same as above |
bytedance/seedance-2.0, -2.0-fast, -2.0-mini, -2.5 with reference images, clips or voices |
submit POST /v1/generations/refs · poll GET /v1/generations/{job_id} — see Reference images and videos |
The capability is in the MODEL ID, not in the request
This is the single thing that costs integrators the most time. Sibling ids are different models with
different accepted fields, and the shortest, most obvious-looking name in a family is usually the
text-only one. Sending an image field to it is rejected as unknown field(s) — and no amount of guessing
at field names will help, because the field does not belong to that model.
HappyHorse is the clearest example. Four ids, one family:
| model id | what it does | the input field |
|---|---|---|
alibaba/happyhorse-1-1-video |
text → video | none — this is the text-only one |
alibaba/happyhorse-1-1-video-i2v |
photo → video (this is "animate") | first_frame_url — one public https url |
alibaba/happyhorse-1-1-video-ref |
up to 9 reference images → video | reference_image_urls — array of urls |
alibaba/happyhorse-video-edit |
existing clip → edited clip | video_url (one clip) plus up to 5 reference_image_urls |
So for photo-to-video you want -i2v with first_frame_url. Reaching for alibaba/happyhorse-1-1-video
and looking for an image parameter is a dead end by design: it has none, and image, image_url,
first_frame, content, input_reference and every other spelling all come back unknown field(s)
because that model takes text only.
No HappyHorse model takes a last frame, and each takes exactly ONE kind of input:
| model | the only media type it accepts |
|---|---|
-i2v |
first_frame — a last_frame is rejected: Input should be 'first_frame' |
-ref |
reference_image — video is rejected: Input should be 'reference_image' |
-video-edit |
video (exactly one) plus up to 5 reference_image — reference_video is refused |
base -video |
none — it silently ignores any media you send (see below) |
The vendor's own API reference lists first_frame, last_frame, reference_image, reference_video
and reference_audio together, which reads as if every HappyHorse model took all of them. Those types
are real — but they span the vendor's whole video-generation API, not one model. On HappyHorse each
validator allows exactly one, as above; last_frame in particular belongs to wan2.7-i2v, a different
model. Every line in the table is from probing the live endpoint, and note that this vendor's submit
returns 200 regardless — the rejection only ever appears on the poll, so a 200 from it proves
nothing at all.
If you need a start AND an end frame, use alibaba/wan-2-7-i2v or alibaba/wan-3-video, which take
first_frame_url and last_frame_url.
Two things about these models that are easy to miss
-video-edit is meant to take a clip AND images together. Its headline use is "put the sweater from
this image onto the character in this video" — one video_url plus up to five reference_image_urls.
Sending only the clip works and edits it from the prompt alone, so the pairing is easy to overlook.
(reference_video_urls still works as the old name for the clip; video_url is the one to use.)
On -ref, the ORDER of reference_image_urls is part of the prompt. The Nth url is what your prompt
means by [Image N], up to 9 of them. From the vendor's own example:
{ "model": "alibaba/happyhorse-1-1-video-ref",
"prompt": "A woman in the red qipao from [Image 1] unfolds the fan from [Image 2] while the tassel earrings from [Image 3] sway",
"reference_image_urls": ["https://…/girl.jpg", "https://…/fan.jpg", "https://…/earrings.jpg"],
"resolution": "720p", "aspect_ratio": "16:9", "duration": 5 }
Re-order that array and the subjects swap. Nothing in the gateway sorts or de-duplicates it — the order you send is the order the model reads.
Why the base -video model is the dangerous one. Send it a first_frame and the vendor answers
SUCCEEDED — with a clip rendered from your prompt alone, your image ignored, and the job billed. It does
not even fetch the url. This gateway does not let that happen: the base model declares no url fields, so
we reject the request instead of letting you pay for a clip that ignored your input.
How to discover a model's accepted fields, without guessing
curl -sS https://api.sociaro.com/model/info -H "Authorization: Bearer $KEY" \
| jq -r '.data[] | select(.model_name=="alibaba/happyhorse-1-1-video-i2v")
| .model_info.supported_openai_params'
# -> ["prompt","first_frame_url","resolution","aspect_ratio","duration",
# "negative_prompt","seed","prompt_extend","watermark","audio_url"]
supported_openai_params is the authoritative list of field names this gateway accepts for that
model, and the routes that check field names reject anything outside it with unknown field(s): [...]
naming the offender. Read it before writing a request. On /v1 the six alibaba/* image ids do no such check — see the exceptions under the table below — so there the
list is what we support rather than what we enforce. (/v2 is the other way round: it checks every model's input
against the model's published input_schema, which is closed, so an unknown field is a 400 invalid_input at submit.) One exception on the Seedance models: frames and camera_fixed
are not listed, because the generator refuses both on every Seedance model we serve (measured
2026-10-05; the vendor documents camera_fixed for Seedance 1.x only), yet both still pass our
field-name check, so they reach the generator, which answers with its own message instead of
unknown field(s). Note
what the list does NOT tell you: types, ranges, defaults or which fields are required — those are on
each model's own page under Models.
Every model, every field
The same lists, in one place, so you do not have to call /model/info to start. Anything outside a
model's row comes back 400 unknown field(s): [...] — with two exceptions on /v1, of different
kinds. On Seedance, frames and camera_fixed pass our check and are refused by the GENERATOR, in its
own words (see above) — still a refusal, just not ours. The second is not a refusal at all:
the six alibaba/* image ids have no field allowlist — that includes the two added on 2026-10-08, alibaba/qwen-image-2-1-pro and alibaba/wan-2-6-image — so everything
you send other than prompt and the reference-image urls is forwarded to the generator untouched,
deliberately, so a parameter we have never heard of is the generator's to accept or refuse rather
than ours to guess at. Their rows are what we have measured and will support — a field outside one
may still work, it is simply not something we promise. enable_sequential on
alibaba/wan-2-7-image and alibaba/wan-2-7-image-pro is the known case, and it changes how many images you pay for.
On /v2 the rule is the reverse: minimax/h3, minimax/h3-max, minimax/h3-highspeed and
minimax/h3-lite take a closed input, checked in full at submit against the model's published input_schema, so a
field outside their row, a value outside its range and a content part of the wrong shape are each a 400 invalid_input
and no job. So are a resolution the model does not offer, a callback_url inside input, an mm_file:// url, and
model or resolution in another letter case (Jobs API has the details). What only the generator can judge (the
length of a clip or sound, a picture's size and format) it still refuses before anything is billed (the job then ends
failed with provider_rejected, uncharged). The fifth MiniMax id, minimax/h3-regeneration (/v2 only), is
closed too and narrower: a field outside its row is a 400 invalid_input and no job (resolution may also be sent,
as 2K, the only one it renders).
What this table does NOT give you is types, ranges,
defaults and which fields are REQUIRED — for the ByteDance and MiniMax H3 models those are in each model's own page
under Models, for the Wan and Qwen image models in Wan image models and Qwen image models below the table; for the rest, send the field and read the 400, which names the problem.
| model id | makes | every field it accepts |
|---|---|---|
alibaba/happyhorse-1-1-video |
video | prompt, resolution, aspect_ratio, duration, negative_prompt, seed, prompt_extend, watermark, audio_url |
alibaba/happyhorse-1-1-video-i2v |
video | prompt, first_frame_url, resolution, aspect_ratio, duration, negative_prompt, seed, prompt_extend, watermark, audio_url |
alibaba/happyhorse-1-1-video-ref |
video | prompt, reference_image_urls, resolution, aspect_ratio, duration, negative_prompt, seed, prompt_extend, watermark, audio_url |
alibaba/happyhorse-video-edit |
video | prompt, video_url, reference_image_urls, reference_video_urls, resolution, aspect_ratio, duration, negative_prompt, seed, prompt_extend, watermark, audio_url |
alibaba/qwen-image-3 |
image | prompt, size, n, watermark, negative_prompt, seed, prompt_extend, prompt_extend_mode, enable_thinking, image_urls |
alibaba/qwen-image-3-pro |
image | prompt, size, n, watermark, negative_prompt, seed, prompt_extend, prompt_extend_mode, enable_thinking, image_urls |
alibaba/wan-2-7-image |
image | prompt, size, n, watermark, thinking_mode, enable_sequential, seed, color_palette |
alibaba/wan-2-7-image-pro |
image | prompt, size, n, watermark, thinking_mode, enable_sequential, seed, color_palette |
alibaba/wan-3-video |
video | prompt, first_frame_url, last_frame_url, reference_image_urls, reference_video_urls, reference_audio_urls, resolution, aspect_ratio, duration, negative_prompt, seed, prompt_extend, watermark, audio |
alibaba/wan-3-video-prime |
video | prompt, first_frame_url, last_frame_url, reference_image_urls, reference_video_urls, reference_audio_urls, resolution, aspect_ratio, duration, negative_prompt, seed, prompt_extend, watermark, audio |
alibaba/wan-2-7-t2v |
video | prompt, resolution, aspect_ratio, duration, negative_prompt, seed, prompt_extend, watermark, audio_url |
alibaba/wan-2-7-i2v |
video | prompt, first_frame_url, last_frame_url, driving_audio_url, first_clip_url, resolution, duration, negative_prompt, seed, prompt_extend, watermark |
alibaba/wan-2-7-r2v |
video | prompt, reference_image_urls, reference_video_urls, first_frame_url, resolution, aspect_ratio, duration, negative_prompt, seed, prompt_extend, watermark |
alibaba/wan-2-7-videoedit |
video | prompt, video_url, reference_image_urls, resolution, aspect_ratio, duration, audio_setting, negative_prompt, seed, prompt_extend, watermark |
alibaba/wan-2-6-i2v-flash |
video | prompt, first_frame_url, audio_url, resolution, duration, negative_prompt, seed, prompt_extend, watermark, shot_type, audio |
alibaba/qwen-image-2-1-pro |
image | prompt, image_urls, size, n, watermark, seed, prompt_extend, prompt_extend_mode, enable_thinking |
alibaba/wan-2-6-image |
image | prompt, image_urls, size, n, watermark, negative_prompt, seed, prompt_extend, enable_interleave, max_images |
kling/kling-3.0-t2v |
video | prompt, settings.resolution, settings.duration, settings.aspect_ratio, settings.audio, settings.multi_shot, options.watermark_info |
kling/kling-3.0-i2v |
video | contents, settings.resolution, settings.duration, settings.audio, settings.multi_shot, options.watermark_info |
kling/kling-3.0-turbo-t2v |
video | prompt, settings.resolution, settings.duration, settings.aspect_ratio, options.watermark_info |
kling/kling-3.0-turbo-i2v |
video | contents, settings.resolution, settings.duration, options.watermark_info |
kling/kling-2.6-t2v |
video | prompt, settings.resolution, settings.duration, settings.aspect_ratio, settings.audio, options.watermark_info |
kling/kling-2.6-i2v |
video | contents, settings.resolution, settings.duration, settings.audio, options.watermark_info |
kling/kling-3.0-omni |
video | contents, settings.resolution, settings.duration, settings.aspect_ratio, settings.audio, settings.multi_shot, options.watermark_info |
kling/kling-v3 |
image | prompt, negative_prompt, image, image_reference, resolution, n, aspect_ratio, watermark_info |
kling/kling-v3-omni |
image | prompt, image_list, resolution, result_type, n, series_amount, aspect_ratio, watermark_info |
kling/kling-4.0-image |
image | contents, settings.result_type, settings.n, settings.series_amount, settings.resolution, settings.aspect_ratio, options.watermark_info |
kling/kling-4.0-t2v |
video | prompt, settings.resolution, settings.duration, settings.aspect_ratio, options.watermark_info |
kling/kling-4.0-i2v |
video | contents, settings.resolution, settings.duration, options.watermark_info |
kling/kling-4.0-omni |
video | contents, settings.resolution, settings.duration, settings.aspect_ratio, options.watermark_info |
kling/kling-4.0-flash-t2v |
video | prompt, settings.resolution, settings.duration, settings.aspect_ratio, options.watermark_info |
kling/kling-4.0-flash-i2v |
video | contents, settings.resolution, settings.duration, options.watermark_info |
kling/kling-4.0-flash-omni |
video | contents, settings.resolution, settings.duration, settings.aspect_ratio, settings.audio, options.watermark_info |
minimax/h3 |
video | content, resolution, duration, ratio |
minimax/h3-max |
video | content, resolution, duration, ratio, extra.prompt_expansion_mode |
minimax/h3-highspeed |
video | content, resolution, duration, ratio |
minimax/h3-lite |
video | content, resolution, duration, ratio |
minimax/h3-regeneration |
video | source_job, resolution, aigc_watermark |
pixverse/v6 |
video | prompt, quality, duration, aspect_ratio, seed, generate_audio_switch, generate_multi_clip_switch, image_url, first_frame_url, last_frame_url |
pixverse/c1 |
video | prompt, quality, duration, aspect_ratio, seed, generate_audio_switch, image_url, first_frame_url, last_frame_url |
pixverse/video-expand |
video | video_url, aspect_ratio, quality |
pruna/p-image |
image | input.prompt, input.aspect_ratio, input.width, input.height, input.seed, input.prompt_upsampling, input.lora_weights, input.lora_scale, input.hf_api_token, input.enable_copyright_filter |
pruna/p-image-edit |
image | input.prompt, input.images, input.aspect_ratio, input.turbo, input.seed, input.enable_copyright_filter |
pruna/p-video |
video | input.prompt, input.image, input.last_frame_image, input.duration, input.resolution, input.draft, input.fps, input.aspect_ratio, input.seed, input.save_audio, input.prompt_upsampling |
pruna/p-video-2-pro-reference |
video | input.prompt, input.image, input.video, input.audio, input.keep_audio, input.first_frame_image, input.last_frame_image, input.duration, input.resolution, input.mode, input.aspect_ratio, input.prompt_upsampler, input.seed, input.enable_safety_filter |
pruna/p-video-2-pro-avatar |
video | input.image, input.audio, input.voice_script, input.voice, input.voice_prompt, input.voice_language, input.prompt, input.prompt_upsampling, input.resolution, input.seed, input.enable_safety_filter |
pruna/p-video-upscale |
video | input.video, input.target, input.fps, input.turbo |
pruna/p-video-2-pro-replace |
video | input.video, input.images, input.instruction_prompt, input.resolution, input.save_audio, input.ignore_audio, input.seed |
ideogram/ideogram-4 |
image | input.prompt, input.magic_prompt, input.seed, input.num_images, input.resolution, input.rendering_speed |
ideogram/ideogram-4-transparent |
image | input.prompt, input.magic_prompt, input.seed, input.num_images, input.aspect_ratio, input.output_resolution, input.rendering_speed |
ideogram/ideogram-3 |
image | input.prompt, input.negative_prompt, input.seed, input.resolution, input.aspect_ratio, input.rendering_speed, input.magic_prompt, input.num_images, input.color_palette, input.style_type, input.style_preset, input.style_codes, input.style_reference_images |
ideogram/ideogram-3-transparent |
image | input.prompt, input.negative_prompt, input.seed, input.upscale_factor, input.aspect_ratio, input.rendering_speed, input.magic_prompt, input.num_images |
ideogram/ideogram-4-remix |
image | input.prompt, input.image_weight, input.num_images, input.resolution, input.rendering_speed, input.image |
ideogram/ideogram-3-remix |
image | input.prompt, input.image_weight, input.negative_prompt, input.seed, input.resolution, input.aspect_ratio, input.rendering_speed, input.magic_prompt, input.num_images, input.color_palette, input.style_type, input.style_preset, input.style_codes, input.image, input.style_reference_images |
ideogram/ideogram-3-inpaint |
image | input.prompt, input.magic_prompt, input.num_images, input.seed, input.rendering_speed, input.style_type, input.style_preset, input.style_codes, input.image, input.mask, input.style_reference_images |
ideogram/ideogram-3-reframe |
image | input.resolution, input.num_images, input.seed, input.rendering_speed, input.style_preset, input.color_palette, input.style_codes, input.image, input.style_reference_images |
ideogram/ideogram-3-replace-background |
image | input.prompt, input.rendering_speed, input.num_images, input.private, input.image |
ideogram/ideogram-remove-background |
image | input.private, input.image |
ideogram/ideogram-vector |
image | input.prompt, input.aspect_ratio, input.quality, input.num_images, input.seed, input.private, input.images |
ideogram/ideogram-vectorize |
image | input.mode, input.private, input.image |
ideogram/ideogram-4-5 |
image | input.prompt, input.magic_prompt, input.images, input.mask, input.size, input.background, input.quality, input.seed, input.num_images |
ideogram/ideogram-4-5-precise-edit |
image | input.prompt, input.image, input.reference_images, input.mask, input.context_window, input.quality, input.seed, input.num_images |
ideogram/ideogram-4-6 |
image | input.prompt, input.magic_prompt, input.images, input.mask, input.size, input.background, input.quality, input.seed, input.num_images |
ideogram/ideogram-4-6-precise-edit |
image | input.prompt, input.image, input.reference_images, input.mask, input.context_window, input.quality, input.seed, input.num_images |
recraft/recraft-v4-1-flash-v2 |
image | input.prompt, input.n, input.size, input.image_format, input.random_seed, input.controls, input.zdr |
recraft/recraft-v4-1 |
image | input.prompt, input.n, input.size, input.image_format, input.random_seed, input.controls, input.style_id, input.style_reference_urls, input.style_match, input.zdr |
recraft/recraft-v4-1-vector |
image | input.prompt, input.n, input.size, input.image_format, input.random_seed, input.controls, input.style_id, input.style_reference_urls, input.style_match, input.zdr |
recraft/recraft-v4-1-pro |
image | input.prompt, input.n, input.size, input.image_format, input.random_seed, input.controls, input.style_id, input.style_reference_urls, input.style_match, input.zdr |
recraft/recraft-v4-1-pro-vector |
image | input.prompt, input.n, input.size, input.image_format, input.random_seed, input.controls, input.style_id, input.style_reference_urls, input.style_match, input.zdr |
recraft/recraft-vectorize |
image | input.image_url, input.version, input.shape_stacking, input.color_reduction, input.limit_num_shapes, input.max_num_colors, input.max_num_shapes, input.return_gradients, input.small_shape_filter, input.strict_color_palette, input.svg_compression, input.zdr |
recraft/recraft-remove-background |
image | input.image_url, input.image_format, input.zdr |
recraft/recraft-crisp-upscale |
image | input.image_url, input.image_format, input.zdr |
recraft/recraft-creative-upscale |
image | input.image_url, input.image_format, input.zdr |
sonilo/video-to-music |
audio | video_url, prompt, segments, output_format, preserve_speech, ducking, prompt_influence, variants_num, stems |
sonilo/video-to-sfx |
audio | video_url, prompt, segments, audio_format |
bytedance/seedance-2.0 |
video | content, ratio, duration, resolution, output_format, generate_audio, watermark, seed, bitrate_mode, return_last_frame, execution_expires_after, safety_identifier |
bytedance/seedance-2.0-fast |
video | content, ratio, duration, resolution, output_format, generate_audio, watermark, seed, bitrate_mode, return_last_frame, execution_expires_after, safety_identifier |
bytedance/seedance-2.0-mini |
video | content, ratio, duration, resolution, output_format, generate_audio, watermark, seed, bitrate_mode, return_last_frame, execution_expires_after, safety_identifier |
bytedance/seedance-2.5 |
video | content, ratio, duration, resolution, output_format, generate_audio, watermark, seed, bitrate_mode, return_last_frame, omni_reference_task_type, draft, execution_expires_after, safety_identifier |
bytedance/seedance-2.5-flash |
video | content, ratio, duration, resolution, output_format, generate_audio, watermark, seed, bitrate_mode, return_last_frame, omni_reference_task_type, execution_expires_after, safety_identifier |
bytedance/seedream-4-0 |
image | prompt, image, size, output_format, response_format, watermark, seed, sequential_image_generation, sequential_image_generation_options |
bytedance/seedream-4-5 |
image | prompt, image, size, output_format, response_format, watermark, seed, sequential_image_generation, sequential_image_generation_options |
bytedance/seedream-5-lite |
image | prompt, image, size, output_format, response_format, watermark, seed, sequential_image_generation, sequential_image_generation_options |
bytedance/seedream-5-pro |
image | prompt, image, size, output_format, response_format, watermark, seed, layer_decomposition, background |
bytedance/seedream-5-5 |
image | prompt, image, size, layer_decomposition, layer_decomposition_options, background, output_format, optimize_prompt_options, response_format, watermark, safety_identifier |
dola-seedream-5-0-pro-260628 (vendor-native id; same model as bytedance/seedream-5-pro) |
image | prompt, image, size, output_format, response_format, watermark, seed, layer_decomposition, background |
dola-seedream-5-5-261028 (vendor-native id; same model as bytedance/seedream-5-5) |
image | prompt, image, size, layer_decomposition, layer_decomposition_options, background, output_format, optimize_prompt_options, response_format, watermark, safety_identifier |
seedream-4-0-250828 (vendor-native id; same model as bytedance/seedream-4-0) |
image | prompt, image, size, output_format, response_format, watermark, seed, sequential_image_generation, sequential_image_generation_options |
seedream-4-5-251128 (vendor-native id; same model as bytedance/seedream-4-5) |
image | prompt, image, size, output_format, response_format, watermark, seed, sequential_image_generation, sequential_image_generation_options |
seedream-5-0-260128 (vendor-native id; same model as bytedance/seedream-5-lite) |
image | prompt, image, size, output_format, response_format, watermark, seed, sequential_image_generation, sequential_image_generation_options |
seedream-5-0-lite-260128 (vendor-native id; same model as bytedance/seedream-5-lite) |
image | prompt, image, size, output_format, response_format, watermark, seed, sequential_image_generation, sequential_image_generation_options |
91 models. Generated from each model's supported_openai_params — the same list /model/info serves, so this table and the gateway cannot disagree.
Two fields are accepted everywhere on /v1 and are the gateway's own: model, and user (your
end-user id, recorded against the job's spend and stripped before the request reaches the generator).
user must be a string of at most 128 characters with no control characters, and valid UTF-8; anything
else is a 400 before anything is sent or charged: user must be a string, user must be at most 128
characters, user must not contain control characters or user must be valid UTF-8. The two BytePlus task routes
(/v1/byteplus/… and /v1/modelark/…) answer it as Gateway.InvalidRequest; the two BytePlus image routes
(/v1/byteplus/images/generations and /v1/byteplus/images/async) with the plain {"error": {"message": …}}.
On /v2 neither is one of these: model is a top-level envelope field rather than something you put
in input, and user is not accepted at all.
Wan image models
alibaba/wan-2-7-image, alibaba/wan-2-7-image-pro and alibaba/wan-2-6-image. The ranges and defaults below are the generator's own. Every image the
generator makes is charged, so read the fields that set the count first.
alibaba/wan-2-7-image and alibaba/wan-2-7-image-pro
n: 1–4, default 1.enable_sequential(default false) switches to image-set mode. Therenbecomes a maximum of 1–12 and defaults to 12. The generator decides how many images to make, and each one is charged. Sendnwith it to cap the count. On/v2,nandenable_sequential: trueare refused with400 invalid_input(enable_sequential: falseis fine);output.countsets the number there.size:1K(1024×1024 pixels in total) or2K(2048×2048, default), orwidth*heightwith total pixels from 768×768 to 2048×2048 and an aspect ratio from 1:8 to 8:1.alibaba/wan-2-7-image-proalso takes4K, andwidth*heightup to 4096×4096 in total, except in image-set mode, where the limit is 2K (1Kor2K, orwidth*heightup to 2048×2048).alibaba/wan-2-7-imagehas no 4K.thinking_mode: default true. It has no effect in image-set mode.seed: the same seed with the same request gives similar results; the generator does not guarantee identical ones.color_palette: a colour theme, 3 to 10 objects like{"hex": "#C2D1E6", "ratio": "23.51%"}, each ratio written to two decimals and the ratios adding up to 100.00%. Only without image-set mode (enable_sequentialfalse).prompt: the generator reads up to 5,000 characters and cuts off anything longer.- The generator does not support
negative_promptorprompt_extendon these two models. Say what to leave out inprompt.
alibaba/wan-2-6-image
- Editing mode is the default. It needs 1–4 images in
image_urls; a prompt without an image is refused. enable_interleave: trueswitches to text-and-image mode, which takes 0 or 1 image. Use it for text-to-image.n: 1–4, default 4 in editing mode, and each image is charged. Withenable_interleave,nmust be 1 or left out; the generator refuses any other value.max_images(only withenable_interleave): 1–5, default 5. It is an upper bound: the generator may make fewer, and each image it makes is charged.size: in editing mode1K(default) or2K, which keep the aspect ratio of the last input image. Orwidth*height, with total pixels from 768×768 to 2048×2048 (up to 1280×1280 withenable_interleave) and an aspect ratio from 1:4 to 4:1.prompt_extend: default true. It works in editing mode only.seed: 0–2147483647.prompt: the generator reads up to 2,000 characters, andnegative_promptup to 500. It cuts off anything longer.- Each input image: JPEG, JPG, PNG (no alpha channel), BMP or WEBP, 240–8,000 pixels on each side, at most 10 MB.
Qwen image models
alibaba/qwen-image-3, alibaba/qwen-image-3-pro and alibaba/qwen-image-2-1-pro. The ranges and defaults below are the generator's own.
prompt: long prompts are fine; the generator's recommended maximum is about 4,500 tokens.image_urlsturns the request into an edit: 1–3 images on the 3.0 models, 1–10 onalibaba/qwen-image-2-1-pro. Each image: JPG, JPEG, PNG, BMP, TIFF, WEBP or GIF, at most 10 MB; 384–2048 pixels per side gives the best results.size:width*height. The generator's documented range is a total pixel area between512*512and2048*2048and an aspect ratio between 1:8 and 8:1. Left out, the generator picks a size from the prompt. Results are PNG.n: 1–6, default 1. Each image the generator makes is charged.prompt_extend: default true; the generator rewrites your prompt. Sendfalseto keep your wording.prompt_extend_mode:direct(default) oragent.agentis text-to-image only: withimage_urlsthe generator returns400.enable_thinking: default true. It needsprompt_extendtrue, and it is not supported for an edit withagent.seed: 0–2147483647.watermark: default false.negative_prompt: the 3.0 models only.- Price: on the 3.0 models the generator bills each image as 1K when the output's width × height is at most 2,250,000
pixels, and as 2K above that. On
alibaba/qwen-image-3-proa 2K image costs nearly twice a 1K one; onalibaba/qwen-image-3the two cost the same. Each input image on the 3.0 models is a small separate charge, the same at both tiers.alibaba/qwen-image-2-1-procosts the same at every size and does not charge for input images. alibaba/qwen-image-2-1-prodecides from your prompt whether to return an ordinary image or one with a transparent background.
The shape every /v1 route shares
Everything from here on is /v1, except the rows that say /v2. /v2/jobs answers with id rather than job_id, has six statuses
(queued, running, succeeded, failed, canceled, expired) rather than the three below,
returns outputs[].url rather than media_url, and its links do not expire in an hour. Read
Jobs API for it; do not generalise the examples below to it.
# 1. submit
curl -sS https://api.sociaro.com/v1/alibaba/generations \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{ "model": "alibaba/wan-2-7-image", "prompt": "neon-lit rooftop at night, rain" }'
# -> { "job_id": "<id>", "status": "submitted" }
# 2. poll every 3-5 s for images, 5-10 s for video
curl -sS https://api.sociaro.com/v1/alibaba/generations/<id> -H "Authorization: Bearer $KEY"
# -> { "job_id": "...", "status": "processing" }
# -> { "job_id": "...", "status": "completed", "model": "...", "media_url": "https://api.sociaro.com/v1/media/<media_id>" }
# -> { "job_id": "...", "status": "failed", "model": "...", "error": { "code": "...", "message": "...", "provider_code": "..." } }
# 3. download inside the hour — the opaque id IS the credential, no Authorization header
curl -sSL "https://api.sociaro.com/v1/media/<media_id>" -o out.mp4
Gate on the JSON status, never on the poll's HTTP code. A rejected or moderated generation comes
back as HTTP 200 with status: "failed". On /v1, processing and completed/failed are the only states;
completed always carries media_url, failed always carries error with both code and message.
The error object below is /v1/alibaba/*'s, and a failed /v2 job carries the same one (since
2026-10-30; code from /v2's own fixed set, see Jobs API; a /v2 job's error also has a type and, where the
generator gave a reason, a provider_message, and every other /v2 error answer has the envelope on the Errors page). The other two doors do not share
it: /v1/byteplus/* hands back the generator's own envelope untouched, so its error.code is the
vendor's rather than one of ours and there is no provider_code; and the webhook /v1/images/async
posts on a failure carries job_id, status and model with no error object at all — treat
status: "failed" there as the whole message.
Match on error.code, read error.message. code is ours and comes from a small fixed set
(provider_failed, invalid_request, …). message is the generator's own sentence and
provider_code its own code, present when it gave one — that is what separates a moderation refusal
from a renderer fault. The names of the services and hosts that actually run the job are substituted
out of that text before it is sent, and links and e-mail addresses become [link] and [email]; the halves of
the model id you called (alibaba, bytedance,
wan, qwen, seedance, seedream, happyhorse) are deliberately left alone, or a message like
Model alibaba/wan-2-7-image not found would come back garbled. The text can quote your own request
back, so show it rather than store it.
A busy generator. A /v2 job whose LAST retry the generator still answered busy (429) ends provider_failed
with that sentence and provider_code, else the generator is at capacity, retry shortly; a /v2 job that runs out of
retries for any other reason (a 408 on the last one, or an internal error after the busy answer) ends internal.
message is variable text, up to 400 characters — do not match on it. It used to be one fixed
43-character sentence, so anything comparing it by equality or storing it in a narrower column needs
changing. code is the stable thing to branch on, and provider_code the finer-grained one; both are
short tokens.
The submit response's job_id is the value you put in the poll URL. Some routes name it id instead
(see the per-route notes) — it is the same value either way.
Where the routes differ
| Route | Body shape | Result field | Notes |
|---|---|---|---|
/v1/alibaba/generations |
prompt + resolution/duration/aspect_ratio… |
media_url; image models also media_urls |
HappyHorse and Wan video, and the Wan 2.7 / Qwen Image 3.0 image models, served direct from our own workspace. An image job that makes several pictures (n above 1) lists every one in media_urls (the generator's order, one link and one expiry each, media_url is the first) and is charged for the number of images the generator reports making (never more than you were given links to; if it lists extra links you get them all and pay for its count); if one cannot be delivered the job is failed and uncharged |
/v1/byteplus/contents/generations/tasks |
BytePlus's own content[] array |
content.video_url and media_url |
Pass-through: we forward the vendor's format verbatim. Submit returns id, not job_id |
/v1/byteplus/images/{async,generations} |
BytePlus's own image fields | data[].url and media_url |
Pass-through, native vendor model ids. async polls; generations answers in one call |
/v1/images/async |
model, prompt, webhook, … |
delivered TO your webhook | The one route with no poll — you give us a public https webhook and we POST the result to it. It serves no model at present (every model it carried was withdrawn on 2026-10-07), so a request to it is answered 400 — or 503 while the async service is not ready |
/v2/jobs |
{model, input, output?, callback_url?, prompt_enhance?} — the model's own fields go inside input, and the envelope is closed (a key it does not name is a 400, user included) |
outputs[].url |
The one route that is NOT /v1. Different envelope, different status codes, Idempotency-Key required on submit, and a link that does not expire in an hour — a stable cdn.sociaro.com address on a CDN deployment, else an authenticated /v1/media/… one, so read the host you were given. callback_url deliveries are signed and retried, see Webhooks. A failed job's error carries the generator's reason and code when there are any, as below. Everything else — the full field reference and the per-model input schema from GET /v2/models — is in Jobs API, not this page. The files you upload to use as inputs, and the files you own (a job's outputs too), are managed on /v2/files: see Files |
On the two BytePlus pass-through routes the vendor's own raw url (content.video_url, data[].url) is
still returned for compatibility, and media_url was added beside it. Prefer media_url: it points at
our host, hides the vendor's storage, and expires. The raw field will be removed once nobody reads it.
A Seedance video job submitted with return_last_frame gets a second asset — the closing still. On
the BytePlus pass-through it arrives as content.last_frame_url (the vendor's own raw link) with last_frame_media_url beside it, on the
same terms as the clip. It costs nothing extra.
/v2 jobs return the still too, when return_last_frame is true: it arrives as an extra output after the clip, not
counted in output.count, at no extra charge.
Treat the masked field as optional rather than guaranteed. It appears when you asked for it, the
generator returned a still, and that link passes the same delivery check the clip passed — if it
does not, we omit the field rather than hand you a link /v1/media would refuse. The clip is
unaffected either way: a still we cannot serve never costs you the video you paid for.
The Seedance task route as a ModelArk drop-in
/v1/byteplus/contents/generations/tasks answers at the same relative path as BytePlus ModelArk's own
/api/v3/contents/generations/tasks. A client written for ModelArk switches with configuration only:
| setting | value |
|---|---|
| base URL | https://api.sociaro.com/v1/byteplus |
| key | your Sociaro key, as Authorization: Bearer … |
| model | bytedance/seedance-2.0 / bytedance/seedance-2.5 / bytedance/seedance-2.5-flash, or the vendor's own dreamina-seedance-2-0-260128 / dreamina-seedance-2-5-260628 / dreamina-seedance-2-5-flash-261115 |
- Your body is forwarded as you wrote it — every field, including ones we do not know — with five
exceptions: the model id is resolved,
callback_urlis removed (you poll),priorityis removed, both in any letter case,safety_identifieris replaced, andgenerate_audiois set tofalsewhen you leave it out: sound is off unless you sendtrue. Not on a final from a draft (it keeps the draft's sound), nor when you send your own audio (reference_audio) oromni_reference_task_typeedit/extend: there the generator's default (on) applies On 2.0, where an edit or extension is asked for in the prompt without that field, the clip is silent unless you send"generate_audio": trueor send your own audio (reference_audio), with which sound is on by default. Every task runs at the default priority: one generator account serves every customer, and a priority would put one customer's tasks ahead of everyone else's. Forsafety_identifierwe send a per-organisation pseudonym of your value (64 hex characters, the same for the same value on all your organisation's keys and routes), never the value itself, and the task reports the pseudonym back; a value that is not a string of 1–64 characters (blank refused) is a400 Gateway.InvalidRequest. Nothing else about the answer changes. modelcomes back in the form you sent. Submit with the vendor's own id and both the submit and the poll answer with it, so a draft'smodelcan be sent straight back as its final'smodel.- A task stays pollable for its whole life: its
execution_expires_after(the vendor's default 172800 s when you omit it, clamped to 3600–259200 s) plus one hour; adraft: truetask for at least 7 days, so a final can be rendered from it for as long as the vendor keeps the draft. - Cancel a queued task with
DELETE /v1/byteplus/contents/generations/tasks/{id}(or/v1/modelark/…, each for the tasks submitted on it: the other route answers404, as for an unknown id). We read the task first and send the generator a cancel only while it isqueued, once; then we read it again, and only a task the generator now reportscancelledis cancelled: the answer is{"id", "status": "cancelled"}, a later poll answers the same, and a cancelled task is never charged. Arunningtask is a409("a running job cannot be cancelled"), a finished one a409too, and neither is touched — unlike the vendor's ownDELETE, ours never deletes a finished task's record, and a task that started or finished meanwhile is charged as usual when it is done. Another key's task is a403 Gateway.TaskNotOwnedand an unknown id a404, exactly as on the poll; the generator's refusals reach you as they do on the poll. In the rare case where the task finished just as the cancel reached the generator and its record is gone, the answer is502 Gateway.UpstreamOutcomeUnknown: contact us with the task id. - List your own tasks with
GET /v1/byteplus/contents/generations/tasks(or/v1/modelark/…):{"items": [{"id", "model", "created_at"}], "total"}, newest first,page_num(default 1, at most 500) andpage_size(default 20, at most 500). It is built from our records for YOUR key, never the vendor's list, which spans every customer: it carries no status (poll a task for that), takes no filters (any other query parameter is a400), and holds the tasks that can still be polled (the newest 10,000 at most). It is best-effort: it may not hold tasks submitted before this list was deployed, a task can be missing from it (polling and billing never depend on it), and only the page you ask for is checked, sototalcan count tasks whose record has expired. bytedance/seedance-2.5goes to4k(2.5 Flash stops at720p). At4kthe generator takes at most 15 requests a minute and one task at a time; past that its own429reaches you as it is on this route (on/v1/modelarkit arrives on the poll as afailedtask with itserror.code).- The generator's own refusals and failures reach you unchanged — its HTTP status, its body, its
error.code— with one exception: when the request cannot be taken right now the answer is503 Gateway.UpstreamUnavailable, and a task that failed for that reason readsstatus: "failed"with that sameerror. Only our own refusals look different, and every one of them carries a stableerror.codebeginningGateway.(below). Status codes are the ones listed under Status codes; the code tells apart refusals that share a status — notably the two429s and the two submit502s.
{"error": {"code": "Gateway.InsufficientBalance", "message": "budget exceeded for this organisation: …"}}
| HTTP | error.code |
when | retry? |
|---|---|---|---|
401 |
Gateway.AuthenticationError |
key missing or invalid | no — fix the key |
403 |
Gateway.KeyNotAllowed |
the key is blocked or may not use this route | no |
429 |
Gateway.InsufficientBalance |
the organisation's balance is spent | no, until topped up |
429 |
Gateway.RateLimitExceeded |
the key's own request-rate limit | yes, after a backoff |
502 |
Gateway.AuthUnavailable |
the key check could not complete | yes |
400 |
Gateway.InvalidRequest |
the body is not JSON, or not a JSON object, or user is not a string of at most 128 characters without control characters (the message says which: user must be a string, user must be at most 128 characters, user must not contain control characters, user must be valid UTF-8) |
no |
400 |
Gateway.ModelNotSupported |
a model id this route does not serve | no |
403 |
Gateway.ModelNotGranted |
the key is not granted the model | no |
400 |
Gateway.ResolutionNotAvailable |
a resolution we do not sell for that model (e.g. 4k on 2.5 Flash) |
no |
400 |
Gateway.InvalidDraft |
draft mode misused: off Seedance 2.5 (2.5 Flash has no draft), a draft not at 480p or a final not at 1080p or 4k, draft together with a draft_task part, not exactly one draft_task, or no id in it |
no |
400 |
Gateway.DraftUnknown |
the final names a draft we hold no record of for this key | no — render a new draft |
503 |
Gateway.StoreUnavailable |
the job store is briefly unavailable, before anything was submitted (or on a poll) | yes |
503 |
Gateway.NotConfigured |
the route is not configured | yes, later; tell us if it persists |
503 |
Gateway.UpstreamUnavailable |
the request cannot be taken right now; on a submit nothing was created and nothing is charged. On a poll it arrives inside a failed task, or as this 503 when the generator refused the poll itself |
yes, later |
502 |
Gateway.UpstreamUnreachable |
the generator could not be reached — on a submit, BEFORE anything was sent | yes |
502 / 503 |
Gateway.UpstreamOutcomeUnknown |
the connection failed AFTER the submit was sent (502), or the generator accepted the task and we could not record it (503): a task may exist and be charged |
not blindly — see below |
400 |
Gateway.InvalidTaskId |
the poll id has characters outside A-Z a-z 0-9 _ - |
no |
404 |
Gateway.TaskNotFound |
a poll id we do not know, or past its window | no |
403 |
Gateway.TaskNotOwned |
the task was submitted with another key (a poll or a cancel) | no — use that key |
409 |
Gateway.TaskNotCancellable |
a cancel of a task that is running, finished, or still being submitted | no (the last: in a few seconds) |
Outside this table, three answers carry no Gateway. code because they never reach our application:
413 (body over 25 MB — send media as URLs), a 429 on a burst of requests sent WITHOUT a key, and
Cloudflare's 524 when a request is held at the edge for about 120 s — whose outcome is unknown.
Cloudflare's own HTML 502/504 carries no code either: it replaces an error body from us. On a submit you hold
no id: resubmit only once your Logs show no job for the first attempt (rarely it was accepted, and then it is
charged); on a poll, poll again.
The ModelArk route with reference files in every media role (/v1/modelark)
/v1/modelark/contents/generations/tasks is the ModelArk drop-in above with the differences below.
| setting | value |
|---|---|
| base URL | https://api.sociaro.com/v1/modelark |
| submit / poll | POST …/contents/generations/tasks · GET …/contents/generations/tasks/{id} |
| everything else | as above: same key, same model ids, same body, same Gateway.* codes |
- The submit accepts the task and returns its id at once, with
status: "queued". The id (mk-…) is ours: poll with it, and use it asdraft_task.idwhen you render a final from a draft. Your client's submit timeout does not matter on this route — the submit does not wait for the render. - While the task is
queuedit can still fail, with the codes in the table below. A task that fails there is never charged. A refusal by the generator itself (for example a content check) also arrives on the poll rather than on the submit:status: "failed"with the generator's ownerror.codeand message, unchanged.queuednormally lasts a few seconds — as a rule no more than 20–30 s. Fifteen minutes is a safety limit, not an expected wait: a task stillqueuedafter it is failed withGateway.InputPreparationTimeout, which is an error case. - After
queuedthe poll answers the generator's statuses (running,succeeded,failed,expired,cancelled), with youridandmodelin the form you sent. A task issucceededonly when its result links are ready, sorunningfor a little longer than the generator itself needs is normal. - Results are delivered as permanent links. On
succeeded,content.video_url(andcontent.last_frame_urlwhen you asked for it) are stablehttpslinks that do not expire. The fields and the response shape are the generator's own; store the link you are given. - Images, video and audio are accepted as ordinary
httpslinks in every media role:first_frame,last_frame,reference_image,reference_videoandreference_audio. Send the links you have. The people in them must be characters, or people you have consent to show: see People in references. The links must be publichttpsand reachable from the internet; presigned links are fine. Your parts keep their order and their fields. A task that sends at least one of these links, or a final rendered from a draft that did, is priced separately from the same task on/v1/byteplus; any other task costs the same. Special rates may be available — contact your account manager. - Drafts: render the final with
draft_task.idset to the draft'smk-…id, at1080por4k. The draft must havesucceededfirst. Naming one that is stillqueued, or that failed before the generator took it, is refused on the submit withGateway.InvalidDraft; a final from a draft that is still rendering, or that the generator failed, is refused by the generator and arrives as afailedtask. - Errors that are not ours: when the generator itself refuses a submit (including
ModelOverloaded,InternalServiceErrorandRateLimitExceeded), the poll answersfailedwith that error — its code, message andprovider_code— unchanged and with no charge; a client that retries on those codes can do so with a new submit. - Limits: a key may have at most 20 tasks
queuedat once, and the gateway 200; past that the submit is refused with429 Gateway.RateLimitExceeded("too many tasks being prepared; retry shortly") and nothing is created. Retry after a short pause.
A task that fails while queued reads like this on the poll (no charge):
{"id": "mk-…", "model": "bytedance/seedance-2.5", "status": "failed",
"error": {"code": "Gateway.InputDownloadFailed", "message": "image 1: could not be downloaded …",
"provider_code": "InvalidParameter.DownloadFailed"}}
Such a task is also listed in the console's Logs as a failed request, at no charge.
| where | error.code |
when | retry? |
|---|---|---|---|
submit, 400 |
Gateway.InvalidRequest |
more media of one kind than the model takes (2.0: 9 images, 3 videos, 3 audio; 2.5: 30, 10, 10) | no |
submit, 400 |
Gateway.InvalidDraft |
as above, and: the draft named is still queued or failed before the generator took it (a final from a draft that is still rendering, or that the generator failed, is refused by the generator and arrives as a failed task) |
no |
submit and poll, 402 |
Gateway.InsufficientBalance |
the organisation's balance is spent. On this route it is 402, not 429 (the code and message are the same as elsewhere) |
no — until topped up |
submit, 429 |
Gateway.RateLimitExceeded |
too many tasks queued for the key or the gateway (a 429 also carries this code for the key's own request rate) |
yes, after a short pause |
submit, 503 |
Gateway.NotConfigured |
this route is not available right now | yes, later |
poll, failed |
Gateway.InputUrlInvalid |
a media url is not a public https link: http, a private address, a raw space, or an embedded file (base64 / data: URI) |
no — fix the URL |
poll, failed |
Gateway.InputDownloadFailed |
we could not fetch a media URL; error.provider_code is InvalidParameter.DownloadFailed |
no — the link must be reachable and not expired |
poll, failed |
Gateway.InvalidRequest |
a media file was refused as input (e.g. an audio clip too short, an unsupported format); error.message names the part and carries the provider's reason, error.provider_code its code |
no — fix the file |
poll, failed |
Gateway.InputPreparationFailed |
a media file was refused while it was prepared. error.message names it by its role and its position among the media parts we prepare, in content order, with the provider's reason when it gave one — e.g. "the reference video at position 2 could not be prepared: …"; error.provider_code is the provider's code when it gave one |
no — replace or re-encode that file; the same file fails the same way |
poll, failed |
Gateway.InputPreparationTimeout |
temporary: a media file was not ready in time (error.message names it by role and position), or the task did not leave queued within the 15-minute safety limit; the message says to retry |
yes, with a new submit |
poll, failed |
Gateway.InputPreparationBusy |
temporary: media preparation is busy or unavailable, or the provider failed on its side | yes, with a new submit |
poll, failed |
Gateway.UpstreamUnreachable |
the generator could not be reached; nothing was started | yes, with a new submit |
poll, failed |
Gateway.UpstreamOutcomeUnknown |
the connection failed after the task was sent: it may exist and be charged | not blindly — contact us |
poll, failed |
Gateway.ResultUnavailable |
the finished video could not be delivered within about a day of the render (it was charged) | contact us |
Layer decomposition — one picture in, up to 100 out
Seedream 5.0 Pro can take a finished image apart. Send layer_decomposition: true on
POST /v1/byteplus/images/async with model: "dola-seedream-5-0-pro-260628" (or
bytedance/seedream-5-pro) and exactly one image, and you get back a base image plus up to 16
layers, each a PNG with an alpha channel. A prompt is optional here: without one the model decides
what the separable elements are; with one it decomposes what you describe.
Each entry in data[] then carries three extra fields:
| Field | What it is |
|---|---|
z_index |
stacking order — 0 is the base image, layers start at 1, higher sits on top |
name, description |
what the model thinks the layer is |
bounding_box |
where it sits, as absolute [left, top, right, bottom] in base-image pixels, and normalized on a 0–1000 grid |
To rebuild the picture, place each layer at (left, top), scale it to right-left × bottom-top, and
stack in ascending z_index.
Price. Decomposition is billed per output image at half the generation rate — $0.02475 up to
2.61 Mpx, $0.0495 above — so a 2K decomposition returning a base plus 16 layers costs about $0.84, not
one flat fee. Layers in the same response can land in different pixel tiers and are each charged on
their own. size here takes 1K, 1.5K, 2K or auto (the default), which sizes each output
from its own dimensions in your input.
Two limits worth knowing before you send one: exactly one input image (more is an error), and no partial success — if any single layer fails, the whole request fails.
Seedream 5.5. bytedance/seedream-5-5 (or its native id dola-seedream-5-5-261028) decomposes the
same way, on the same route, with the same two limits, and returns a base image plus up to 99 layers.
layer_decomposition_options steers it: max_images caps how many images come back, from 2 to 100 with
the base included (default 30), and text_recognition: true (default false) adds a text_recognition
field with the recognised text to each layer of regular text. Its price is not halved: every output
image, the base and each layer, is charged at the generation rate for its own size — $0.022 up to 2.6 MP,
$0.0385 above, and a layer smaller than 1K at $0.022 — plus $0.0088 for the input image.
safety_identifier on the image routes
Every official Seedream image model accepts safety_identifier on both image routes: a fixed id for your end user,
1–64 characters, which the generator uses to spot an end user who breaks its usage policy. We never send your value:
what leaves is always a per-organisation pseudonym of it (64 hex characters, the same for the same value on all your
organisation's keys and routes). A value that is not a string of 1–64 characters (blank refused), or the field given
twice in different letter case, is a 400 before anything is sent or charged. Seedream 5.5 and 5.0 Pro use the field,
and on those the response reports the pseudonym back; the generator does not document it for the other Seedream
models, so there the pseudonym is sent and may be ignored, with no echo promised.
background — a transparent result
Also Seedream 5.0 Pro, also pass-through: background: "transparent" returns an image with a live
alpha channel instead of a filled one. It works only on image-to-image with exactly one input
image that itself has an alpha channel, and the output is PNG — asking for output_format: "jpeg"
alongside it is an error, as is feeding it a JPEG. Those refusals come from the generator in its own
words.
Seedream 5.5 (bytedance/seedream-5-5) takes background too, as auto (the default), transparent
or opaque, and goes further: it makes a transparent image from text alone or from up to 10 input
images, and the inputs need no alpha channel. transparent with output_format: "jpeg" is still an
error, and so is background together with layer_decomposition.
Reference images, clips and voices (/v1/generations/refs)
POST /v1/generations/refs takes the Seedance content array (reference_image, reference_video,
reference_audio, or first_frame with an optional last_frame) and prepares every file before submitting, so
every role accepts your files. It answers {"job_id": …, "status": "submitted"}; poll
GET /v1/generations/{job_id} for processing, completed (with media_url) or failed, as above. A job stays
pollable as long as a task on /v1/byteplus with the default execution_expires_after: 49 hours.
A job here is priced separately from the same job on /v1/byteplus.
Until your organisation has it switched on, the submit answers 403 Gateway.RealFacesNotEnabled. Drafts are not
offered on this route: draft (other than false) or a draft_task part is a 400 Gateway.InvalidRequest,
"drafts are not offered on this route", before anything is prepared or charged. A refusal of the request by the
generator itself comes back on the submit, in its own words; one after rendering arrives on the poll as failed.
| submit | error.code |
retry? |
|---|---|---|
400 |
Gateway.InputUrlInvalid, Gateway.InputDownloadFailed, Gateway.InvalidRequest |
no — fix the link, the file or the request |
422 |
Gateway.InputPreparationFailed: the message names the part by its position among your media and its role, with the reason; provider_code is the generator's code when it gave one |
no — replace or re-encode the file |
503 |
Gateway.InputPreparationBusy, Gateway.InputPreparationTimeout |
yes, after Retry-After seconds |
503 |
Gateway.UpstreamUnavailable, WITHOUT Retry-After: the generator is unavailable to us (its answer could not be read) and the outcome at the generator is unknown; no job id, no charge |
not automatically |
503 |
no code: temporarily unavailable; the message says why | yes, later |
A refusal while your files are prepared (Gateway.Input*, and Gateway.InvalidRequest for a refused file) is
also listed in the console's Logs as a failed request, at no charge. The full page, with every field and an example
per role: Reference images and videos.
Kling video and images — /v1/kling/generations (Kling's own body)
Sixteen ids on one door: thirteen video models and three image models. Each takes Kling's own body, with our model and an
optional user beside it. The three Kling 4.0 video ids and the three Kling 4.0 Flash video ids have their own rules
(below).
Video. kling/kling-3.0-t2v, kling/kling-3.0-i2v, kling/kling-3.0-turbo-t2v, kling/kling-3.0-turbo-i2v,
kling/kling-2.6-t2v, kling/kling-2.6-i2v and kling/kling-3.0-omni. The body is Kling's own — prompt on the
-t2v ids, contents[] on the -i2v ids and on Omni, plus settings{} and options{} — exactly as Kling documents it
for 3.0,
3.0 Omni,
3.0 Turbo and
2.6.
Kling's defaults apply: 720p, 5 s, audio off. 3.0 Turbo has no audio field: its clips always include sound.
kling/kling-3.0-omni is one model for text-to-video, a first frame (optionally with a last frame) and reference
images: its contents[] takes parts of type prompt, first_frame, last_frame and refer_image, and its settings
take aspect_ratio (16:9 · 9:16 · 1:1; Kling requires it when there is no first frame) and multi_shot (Kling's
default true) besides resolution, duration (3–15 s) and audio.
Refused on this gateway, each a 400 before anything is sent:
options.callback_url— poll instead (or use/v2/jobs, whose envelope takes acallback_url);options.external_task_id— the gateway sets its own;options.watermark_info.enabled: true—falseis accepted;- a
contents[]part of typeelementorvoice; - on
kling/kling-3.0-omni, reference videos: acontents[]part of typefeature_videoorbase_video, andsettings.audio: "original"(a reference video's own sound). They are not available on this gateway yet; - any field Kling does not define for that model — unknown fields are a
400, not ignored; - on 2.6,
settings.audio: "native"or alast_framewithoutsettings.resolution: "1080p". Kling renders both at 1080p only, so at the default720pthe request is refused rather than sent.
The body is capped at 1 MiB (413 past that), so images go in as URLs.
Price. Kling's list price, per second of output, by resolution and audio; billed once, on the first completed poll.
A failed job is not billed.
| model | audio | 720p | 1080p | 4k |
|---|---|---|---|---|
kling/kling-3.0-t2v, kling/kling-3.0-i2v |
off | $0.084/s | $0.112/s | $0.42/s |
kling/kling-3.0-t2v, kling/kling-3.0-i2v |
native |
$0.126/s | $0.168/s | $0.42/s |
kling/kling-3.0-omni |
off | $0.084/s | $0.112/s | $0.42/s |
kling/kling-3.0-omni |
native |
$0.112/s | $0.14/s | $0.42/s |
kling/kling-3.0-turbo-t2v, kling/kling-3.0-turbo-i2v |
always included | $0.112/s | $0.14/s | — |
kling/kling-2.6-t2v, kling/kling-2.6-i2v |
off | $0.042/s | $0.07/s | — |
kling/kling-2.6-t2v, kling/kling-2.6-i2v |
native |
refused | $0.14/s | — |
So a 5 second kling/kling-3.0-omni clip is $0.42 at 720p without audio, and $0.70 at 1080p with native audio.
Kling 4.0. kling/kling-4.0-t2v, kling/kling-4.0-i2v and kling/kling-4.0-omni are Kling
4.0: one model on Kling's three paths, as Kling documents it for text-to-video,
image-to-video and
Omni. Kling opened Kling 4.0 on 2026-10-23. The body has
3.0's shape, with 4.0's rules:
| model | input | settings.resolution |
settings.duration |
settings.aspect_ratio |
|---|---|---|---|---|
kling/kling-4.0-t2v |
prompt |
720p · 1080p (default) |
3–30 s, required | 21:9 · 16:9 (default) · 9:16 · 1:1 |
kling/kling-4.0-i2v |
contents[]: prompt, first_frame, middle_frame, last_frame |
720p · 1080p (default) |
3–30 s, required | none: the frames set it |
kling/kling-4.0-omni |
contents[]: prompt, first_frame, middle_frame, last_frame, refer_image, feature_video, base_video, element, voice |
720p · 1080p (default) |
3–30 s, required | the same four, or adaptive (the default: from the prompt, else the base_video, the key frames (the first frame first) and the other input videos, in that order, else 16:9; Kling does not list a reference image as a source) |
settings.durationis required on this gateway: left out, Kling takes the length from the prompt, and the price must be known when the job is submitted. A request without it is a400.- Kling's default resolution on 4.0 is
1080p, not720p, and it is priced as such. - Up to 10 images per request, frames and reference images together. Give an image an
idto name it in the prompt as@id; on Omni everymiddle_frameandrefer_imageneeds one when there are several. - 4.0 has no
settings.audio(describe the sound in the prompt), nosettings.multi_shotand no4k: each is a400, as is any other field Kling does not define. - Refused as on 3.0:
options.callback_url,options.external_task_id,options.watermark_info.enabled: true, and, onkling/kling-4.0-t2vandkling/kling-4.0-i2v,contents[]parts of typeelementandvoice. - Input videos, on
kling/kling-4.0-omnionly:feature_video, a feature reference video (follow its motion, its rhythm, its camera), andbase_video, the video to edit, each{"type", "url", "id"?}; name one in the prompt as@id. A public https URL only, never base64. At most 5 videos together, at most one of them abase_video(Kling allows up to 5 reference videos and onebase_video; the gateway counts thebase_videoamong the 5), and the 15 inputs in all still hold. Each video, and all of them together, must be 3 to 30 seconds long: the gateway reads each one's length from the file's own header when you submit, so send an MP4 or MOV that is not fragmented, at a URL that answers without a redirect. A video whose length cannot be read, or that is too short or too long, is a400and no job. Kling judges the rest (.mp4/.mov, at most 300 MB, 700 to 4553 px a side and at most 8,294,400 pixels in all, an aspect ratio between 2:5 and 5:2, 24 to 60 fps) when the job is submitted.settings.durationstays required with abase_video. - Elements and voices, on
kling/kling-4.0-omnionly: a part{"type": "element", "element_id", "id"}or{"type": "voice", "voice_id", "id"}; name it in the prompt as@id. At most 7 elements and 3 voices, and the 15 inputs in all still hold. Each id must be one your organisation made on this gateway (see Kling elements and voices below) or one of Kling's presets. Any other id is a404and nothing is sent, the same answer whether the id is another customer's or nobody's. An element made from a video (reference_type: video_refer, a preset included) is not available on this gateway yet: a400. Naming an element or a voice adds nothing to the price.
Price. Kling's 4.0 list price, per second, by resolution, billed once, on the first completed poll. Kling's
pricing page still labels the 4.0 price a preview (read 2026-10-23), so it may change when Kling publishes final pricing.
| model | 720p | 1080p |
|---|---|---|
kling/kling-4.0-t2v, kling/kling-4.0-i2v, kling/kling-4.0-omni, per second of output |
$0.157/s | $0.2355/s |
kling/kling-4.0-omni with input videos, per billed second |
$0.0942/s | $0.1413/s |
So a 10 second 4.0 clip is $1.57 at 720p and $2.355 at 1080p, the default. With input videos the billed seconds are
Kling's: the output's twice when the input videos together are no longer than the output, else input plus output. The
input seconds are the ones Kling reports on the finished job (usage.input_duration, two decimals), never rounded to
whole seconds, and only those: the length the gateway reads when you submit only holds each video to 3–30 s. Until
Kling reports them, the finished job answers processing; it is charged and delivered on the first poll after. A 15
second 1080p clip with an 8.03 second feature_video bills 30 s, $4.239; a 10 second 1080p edit of a 12.5 second
base_video bills 22.5 s, $3.17925. (Kling's page rounds the two with-video rates to $0.094 and $0.141.)
# Submit (Kling 4.0): settings.duration is required; 1080p by default
curl -sS https://api.sociaro.com/v1/kling/generations \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{ "model": "kling/kling-4.0-omni",
"contents": [ { "type": "prompt", "text": "the jacket from @image_1, worn on a windy pier" },
{ "type": "refer_image", "url": "https://your-cdn.example.com/jacket.png", "id": "image_1" } ],
"settings": { "duration": 10, "aspect_ratio": "9:16" } }'
# -> { "id": "<job_id>", ..., "job_id": "<job_id>", "status": "submitted", "model": "kling/kling-4.0-omni" }
# An element and a voice (Kling 4.0 Omni): yours, or Kling's presets; priced as the clip without them
curl -sS https://api.sociaro.com/v1/kling/generations \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{ "model": "kling/kling-4.0-omni",
"contents": [ { "type": "prompt", "text": "@element_1 opens the door and says hello in @voice_1" },
{ "type": "element", "element_id": "<element_id>", "id": "element_1" },
{ "type": "voice", "voice_id": "<voice_id>", "id": "voice_1" } ],
"settings": { "duration": 5 } }'
# Video editing (Kling 4.0 Omni): a base_video, by URL; 0.9 x (12.5 + 10) x $0.157 = $3.17925 at 1080p
curl -sS https://api.sociaro.com/v1/kling/generations \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{ "model": "kling/kling-4.0-omni",
"contents": [ { "type": "prompt", "text": "edit @video_1: the box opens on a sleeping cat; keep the rest" },
{ "type": "base_video", "url": "https://your-cdn.example.com/box.mp4", "id": "video_1" } ],
"settings": { "duration": 10 } }'
Kling 4.0 Flash. kling/kling-4.0-flash-t2v, kling/kling-4.0-flash-i2v and kling/kling-4.0-flash-omni are
Kling 4.0 Flash, the fast Kling 4.0 tier: one model on the same three paths, with the same body shape and its own
rules:
| model | input | settings.resolution |
settings.duration |
settings.aspect_ratio |
|---|---|---|---|---|
kling/kling-4.0-flash-t2v |
prompt |
720p only |
3–20 s, required | 21:9 · 16:9 (default) · 9:16 · 1:1 |
kling/kling-4.0-flash-i2v |
contents[]: first_frame, prompt (optional) |
720p only |
3–20 s, required | none: the frame sets it |
kling/kling-4.0-flash-omni |
contents[]: prompt, first_frame, refer_image, feature_video, base_video, element |
720p only |
3–20 s, required | the same four, or adaptive (the default: from the prompt, else the base_video, the first frame and the feature_video, in that order, else 16:9) |
settings.durationis required, as on 4.0: a request without it is a400.720pis the only resolution:1080pand4kare a400.kling/kling-4.0-flash-i2vtakes onefirst_frame, whose shape the video takes, and an optional prompt part: without one, Kling animates the frame on its own.- Kling 4.0 Flash has no middle or last frame and no voices: a
middle_frame,last_frameorvoicepart is a400, as aresettings.multi_shotand any other field Kling does not define. settings.audio, onkling/kling-4.0-flash-omnionly:native(the default) makes sound to match the picture;originalkeeps an input video's own sound, thebase_video's, else the firstfeature_video's, and needs one of them. Any other value is a400. Neither changes the price. The t2v and i2v ids take nosettings.audio.- Input videos, on
kling/kling-4.0-flash-omnionly: as onkling/kling-4.0-omni(a public https URL, at most 5 videos, at most one of them abase_video, read from the file's own header when you submit), except that each video, and all of them together, must be 3 to 20 seconds long. - Elements, on
kling/kling-4.0-flash-omnionly: as onkling/kling-4.0-omni, at most 7, yours or Kling's presets; any other id is a404. Naming an element adds nothing to the price. - Refused as on 4.0:
options.callback_url,options.external_task_id,options.watermark_info.enabled: true.
Price. Kling's list price, per second, billed once, on the first completed poll.
| model | 720p |
|---|---|
kling/kling-4.0-flash-t2v, kling/kling-4.0-flash-i2v, kling/kling-4.0-flash-omni, per second of output |
$0.0942/s |
kling/kling-4.0-flash-omni with input videos, per billed second |
$0.0628/s |
So a 10 second Flash clip is $0.942, and 20 seconds $1.884. With input videos the billed seconds are counted as on
4.0: the output's twice when the input videos together are no longer than the output, else input plus output, on the
input seconds Kling reports on the finished job (usage.input_duration). A 15 second clip with an 8.03 second
feature_video bills 30 s, $1.884; a 10 second edit of a 12.5 second base_video bills 22.5 s, $1.413.
# Submit (Kling 4.0 Flash): settings.duration is required; 720p only
curl -sS https://api.sociaro.com/v1/kling/generations \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{ "model": "kling/kling-4.0-flash-omni",
"contents": [ { "type": "prompt", "text": "the jacket from @image_1, worn on a windy pier" },
{ "type": "refer_image", "url": "https://your-cdn.example.com/jacket.png", "id": "image_1" } ],
"settings": { "duration": 10, "aspect_ratio": "9:16" } }'
Answers. The submit answers Kling's task fields with our job_id, status: "submitted" and model on top (ours
win where a name collides). On the poll, processing is {job_id, status} alone. completed is Kling's task fields
plus our job_id, status: "completed", model and media_url: our status replaces Kling's own word
(succeeded), Kling's id stays beside job_id, and outputs keeps each item's type and duration only — the
clip itself is media_url. billing is never returned. A 4.0 or 4.0 Flash Omni job with input videos also carries Kling's usage
as Kling sends it on that poll: input_duration, Kling's count of the input seconds, the ones the job is charged on.
Kling adds usage only once it is available, so until then such a job answers processing.
failed carries Kling's own reason in error.message when Kling gave one. A job the generator has not listed yet keeps
answering processing.
Errors on the submit.
| HTTP | meaning | retry? |
|---|---|---|
400 |
Kling refused the request: its own message, and its code in error.provider_code |
no — fix the request |
429 |
the generator is at capacity: Kling's own words in error.message and its code in error.provider_code when it gave them; Retry-After says how long to wait |
yes, after Retry-After seconds |
503 |
error.code Gateway.UpstreamUnavailable, no Retry-After: the generator refused the gateway, not your request. Nothing was created and nothing is charged |
yes, later |
502 |
the generator gave us no usable job: Kling's own words and code when it gave them | no — see 502 on submit |
# Submit: native audio on 2.6 needs 1080p
curl -sS https://api.sociaro.com/v1/kling/generations \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{ "model": "kling/kling-2.6-t2v",
"prompt": "a red fox trotting through fresh snow at sunrise",
"settings": { "resolution": "1080p", "duration": 5, "aspect_ratio": "16:9", "audio": "native" } }'
# -> { "id": "<job_id>", ..., "job_id": "<job_id>", "status": "submitted", "model": "kling/kling-2.6-t2v" }
# Poll (~5-10 s)
curl -sS https://api.sociaro.com/v1/kling/generations/<job_id> -H "Authorization: Bearer $KEY"
# -> { "job_id": ..., "status": "processing" }
# -> { "id": ..., "outputs": [ { "type": "video", "duration": ... } ], ..., "job_id": ..., "status": "completed",
# "model": ..., "media_url": "https://api.sociaro.com/v1/media/<id>" }
Images. kling/kling-v3 is Kling Image 3.0 and kling/kling-v3-omni is Kling Image 3.0 Omni, both text-to-image
and image-to-image; Omni also takes up to 10 reference images and makes image series. They are on Kling's image API,
whose body is flat: the fields sit at the top level, beside our model and user, as Kling documents them for
Image 3.0 and
Image 3.0 Omni. Kling's model_name is set by the
gateway (kling-v3, kling-v3-omni): leave it out, or send the id's own value — any other value is a 400.
| model | input | resolution |
how many | aspect_ratio |
|---|---|---|---|---|
kling/kling-v3 |
prompt (required), negative_prompt (not with image), image (the picture to start from), image_reference subject · face (needs image; Kling's capability map lists them as not supported on Image 3.0, so Kling decides) |
1k (default) · 2k |
n 1–9 (default 1) |
16:9 (default) · 9:16 · 1:1 · 4:3 · 3:4 · 3:2 · 2:3 · 21:9 |
kling/kling-v3-omni |
prompt (required; name a reference image in it as <<<image_1>>>), image_list [{"image": url}], up to 10 |
1k (default) · 2k · 4k |
result_type single (default) with n 1–9, or series with series_amount 2–9 or auto (default 4; Kling's capability map lists series for image-to-image only, so send an image_list with it) |
the same eight, or auto (the default; Kling does not support auto without an input image, so name a ratio for text-to-image) |
Refused, each a 400 before anything is sent: callback_url (poll instead), external_task_id (the gateway sets its
own), element_list, watermark_info.enabled: true (false is accepted), image_fidelity and human_fidelity on
kling/kling-v3 (Kling Image 2.1 only), a resolution the model does not have (4k on kling/kling-v3), an
aspect_ratio outside the list (auto on kling/kling-v3), a value of n, result_type or series_amount outside
the ranges above (on Omni both counts are checked, whichever result_type you send), and any field Kling does not
define for that model. Images go in as public URLs; the same 1 MiB cap applies.
Price. Kling's list price, per image delivered: $0.028 an image at 1k or 2k on both models, and $0.056 at
4k on kling/kling-v3-omni. You pay for the images the finished job hands you, never more than you asked for: n,
or series_amount for a series (auto counts as at most 9). Billed once, on the first completed poll; a failed
job is not billed. Kling counts one slot of its capacity per image asked for, so a large n or series_amount can
meet a 429 while smaller jobs pass; when that is the reason, the message says so, and a smaller job may be taken
sooner.
Answers. As for video, with two differences. completed carries media_url, the first image, and media_urls,
every image in Kling's order (media_url first; present even for one image), each its own /v1/media link for the
hour. Kling's own task fields keep their names: task_id (the same value as job_id), task_status (Kling's word;
read our status), and task_result reduced to result_type and each image's index — the images themselves are in
media_urls. final_unit_deduction and final_balance_deduction are never returned. failed carries Kling's own
reason in error.message when Kling gave one.
# Submit: two images from one reference, at 2k ($0.056 when both are delivered)
curl -sS https://api.sociaro.com/v1/kling/generations \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{ "model": "kling/kling-v3-omni",
"prompt": "the cup from <<<image_1>>> on a marble counter, morning light",
"image_list": [ { "image": "https://your-cdn.example.com/cup.png" } ],
"resolution": "2k", "n": 2 }'
# -> { "task_id": "<job_id>", "task_status": "submitted", ..., "job_id": "<job_id>", "status": "submitted",
# "model": "kling/kling-v3-omni" }
# Poll (~3-5 s)
curl -sS https://api.sociaro.com/v1/kling/generations/<job_id> -H "Authorization: Bearer $KEY"
# -> { "job_id": ..., "status": "processing" }
# -> { "task_id": ..., "task_result": { "result_type": "single", "images": [ { "index": 0 }, { "index": 1 } ] }, ...,
# "job_id": ..., "status": "completed", "model": ..., "media_url": "https://api.sociaro.com/v1/media/<id0>",
# "media_urls": [ "https://api.sociaro.com/v1/media/<id0>", "https://api.sociaro.com/v1/media/<id1>" ] }
Kling Image 4.0 — kling/kling-4.0-image
Text-to-image and image-to-image, single images or a series, on Kling's newer image body: contents, settings and
options, beside our model and user, as Kling documents it for
Image 4.0. Kling's model_name is set by the gateway.
| field | what it takes |
|---|---|
contents (required) |
the prompt {"type": "prompt", "text": ...}, reference images {"type": "refer_image", "url": ..., "id": ...} and elements {"type": "element", "element_id": ..., "id": ...}; name a reference in the prompt as @id. At most 10 images and elements together |
settings.result_type |
single (default) or series |
settings.n |
1–9 images for single (default 1) |
settings.series_amount |
2–10 for series, or auto (Kling chooses, at most 10; default 4) |
settings.resolution |
2k (default) · 4k · 8k |
settings.aspect_ratio |
auto (default; follows the reference images) · 16:9 · 9:16 · 1:1 · 4:3 · 3:4 · 3:2 · 2:3 · 21:9 |
options.watermark_info |
{"enabled": false}: only false is accepted |
A reference image goes in as a public URL or as Base64; either way the request body stays within the 1 MiB cap, so a
larger picture goes by URL. An element is one your organisation made on this gateway (see
Kling elements and voices below) or one of Kling's presets, any
other id is a 404 and nothing is sent; an element made from a video is not accepted. Refused, each a 400 before
anything is sent: options.callback_url (poll instead), options.external_task_id (the gateway sets its own),
options.watermark_info.enabled: true, more than 10 images and elements together, a value outside the ranges above, and
any field Kling does not define. On /v2/jobs the number of images is output.count (1–9 single, 2–10 series), not
settings.n or settings.series_amount, and auto is not offered: see the Jobs API.
Price. Per image delivered: $0.063 at 2k, $0.094 at 4k, $0.157 at 8k, plus $0.003 for each reference image
or element, once per job whatever the number of images. You pay for the images the finished job hands you, never more
than you asked for: n, or series_amount for a series (auto counts as at most 10). Two 2k images from one
reference come to 2 × $0.063 + $0.003 = $0.129. Billed once, on the first completed poll; a failed job is not billed.
Kling counts one slot of its capacity per image asked for, so a large job can meet a 429 while smaller ones pass.
Answers. As for the 3.x images: completed carries media_url, the first image, and media_urls, every image in
Kling's order (media_url first; present even for one image), each its own /v1/media link for the hour.
# Submit: one 2k image from one reference ($0.066; add "n": 2 in settings for two, $0.129)
curl -sS https://api.sociaro.com/v1/kling/generations \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{ "model": "kling/kling-4.0-image",
"contents": [ { "type": "prompt", "text": "the cup from @cup on a marble counter, morning light" },
{ "type": "refer_image", "url": "https://your-cdn.example.com/cup.png", "id": "cup" } ],
"settings": { "resolution": "2k" } }'
# -> { "task_id": "<job_id>", "task_status": "submitted", ..., "job_id": "<job_id>", "status": "submitted",
# "model": "kling/kling-4.0-image" }
# Poll (~3-5 s)
curl -sS https://api.sociaro.com/v1/kling/generations/<job_id> -H "Authorization: Bearer $KEY"
# -> { "job_id": ..., "status": "processing" }
# -> { ..., "job_id": ..., "status": "completed", "model": "kling/kling-4.0-image",
# "media_url": "https://api.sociaro.com/v1/media/<id0>",
# "media_urls": [ "https://api.sociaro.com/v1/media/<id0>" ] }
The thirteen video ids, the 4.0 and 4.0 Flash ones included, are also served on /v2/jobs, with Kling's body as input: see the
Jobs API. The two 3.x image ids, kling/kling-v3 and kling/kling-v3-omni, are /v1 only; kling/kling-4.0-image is on both.
Kling elements and voices — /v1/kling/elements, /v1/kling/voices
An element is a character or an object Kling keeps from your reference images; a voice is a voice Kling clones
from a recording. Make them here, then name them by id in a kling/kling-4.0-omni job (elements also in a
kling/kling-4.0-flash-omni job, which takes no voices), on /v1 or /v2. The bodies
and the answers are Kling's own, as Kling documents them for
elements and
voices; the same key as for every other route.
| route | what it does |
|---|---|
POST /v1/kling/elements · POST /v1/kling/voices |
create one: answers Kling's task_id, task_status and created_at |
GET /v1/kling/elements/{task_id} · GET /v1/kling/voices/{task_id} |
the create task, as Kling has it: task_status (submitted, processing, succeed, failed) and, once it succeeded, the element_id or voice_id under task_result |
GET /v1/kling/elements · GET /v1/kling/voices |
your organisation's create tasks, newest first, each with what it made, as {"data": [...]}; pageNum 1–1000 (default 1), pageSize 1–500 (default 30) |
GET /v1/kling/elements/presets · GET /v1/kling/voices/presets |
Kling's official presets, everyone's: Kling's own page as {"data": [...]}, paged the same way |
These eight routes are the whole set: there is no delete route. To remove an element or voice, ask support: an operator deletes it at Kling, and it leaves your list.
Whose they are. What you make belongs to your organisation: every key of it lists, reads and uses the same
elements and voices, and a key with no organisation has its own. Nobody else can reach them, and you cannot reach
anyone else's: another customer's task or id answers 404, exactly as one that does not exist, and nothing is sent
to Kling. Kling's presets are everyone's. Kling states no retention for elements or voices; the gateway keeps its
record of yours, with no expiry, until an operator deletes the element or voice at your request.
Bodies. An element: element_name, element_description, reference_type: "image_refer",
element_image_list (a frontal_image and 1 to 3 refer_images, as URLs: the body is capped at 1 MiB), and
optionally element_voice_id (one of your voices or a preset voice, any other a 404; empty or null binds no
voice, as on Kling's page; Kling binds a voice only to a character or humanoid element) and tag_list. A voice:
voice_name and voice_url, a public https URL of one clean voice, 5 to 30 seconds (mp3, wav, mp4 or mov). Kling
judges the names, the images and the recording when you create. Refused, each a 400 before anything is sent:
reference_type: "video_refer"andelement_video_list(an element made from a video), and a voice fromvideo_id: not available on this gateway yet;callback_url(these routes send no callback: get the task, or the list, instead) andexternal_task_id(the gateway sets its own);- any other field.
Finishing. A task takes about 30 seconds to 2 minutes. Get it (or the list) until task_status is succeed:
the element_id or voice_id under task_result is then yours to use. A list checks at most its 30 newest
unfinished tasks with Kling and shows the others as last seen: get those by their task_id. The task answers never
carry final_unit_deduction or final_balance_deduction.
Price. A voice is $0.007, Kling's list price, charged once when its task succeeds; a failed one is free. Until the
charge is written the task answers processing. The gateway also checks a voice's task on its own until it ends, so a
voice is charged when it succeeds whether or not you read its task. Creating an element is free: Kling publishes no
price for it. Naming either in a kling/kling-4.0-omni job, or an element in a kling/kling-4.0-flash-omni job, adds
nothing to the job's price.
Errors. As on the Kling video door: Kling's refusal is a 400 with its own message and error.provider_code;
429 with Retry-After when Kling is at capacity, and 502 when it failed, both with Kling's own words and code when
it gave them; 503 Gateway.UpstreamUnavailable when Kling refuses the gateway. 404 for a task or an id that is not yours. On a create, 503 "relay busy, retry shortly" means nothing was
sent: retry. A create answered 502, or 503 "job store unavailable; retry shortly", may have been made at Kling all
the same, and the gateway never recorded it: it is not in your list and cannot be read through the gateway. Before
creating it again, wait a few minutes, or ask support, who can find it by the time of your request. A
kling/kling-4.0-omni or kling/kling-4.0-flash-omni job naming a preset is a 503 Gateway.UpstreamUnavailable when the gateway cannot read
Kling's preset list at that moment (a 429, in Kling's words, when Kling is at capacity): retry it; on /v2 that is 503 unavailable.
# A voice from a recording ($0.007 once it succeeds)
curl -sS https://api.sociaro.com/v1/kling/voices \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{ "voice_name": "Narrator", "voice_url": "https://your-cdn.example.com/narrator.mp3" }'
# -> { "task_id": "<voice_task>", "task_status": "submitted", "created_at": 1761200000000 }
# A character element from images, bound to that voice (free; Kling binds a voice to a character or humanoid only)
curl -sS https://api.sociaro.com/v1/kling/elements \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{ "element_name": "Mia", "element_description": "a young woman with short red hair",
"reference_type": "image_refer",
"element_image_list": { "frontal_image": "https://your-cdn.example.com/front.png",
"refer_images": [ { "image_url": "https://your-cdn.example.com/side.png" } ] },
"element_voice_id": "<voice_id>", "tag_list": [ { "tag_id": "o_102" } ] }'
# Get it until it succeeds
curl -sS https://api.sociaro.com/v1/kling/elements/<element_task> -H "Authorization: Bearer $KEY"
# -> { "task_id": ..., "task_status": "succeed", "task_result": { "elements": [ { "element_id": 905..., ... } ] }, ... }
# Yours, newest first; Kling's presets
curl -sS "https://api.sociaro.com/v1/kling/elements?pageNum=1&pageSize=30" -H "Authorization: Bearer $KEY"
curl -sS "https://api.sociaro.com/v1/kling/voices/presets?pageSize=100" -H "Authorization: Bearer $KEY"
PixVerse video — /v1/pixverse/generations
pixverse/v6 and pixverse/c1, 1 to 15 seconds at 360p, 540p, 720p or 1080p. The mode follows the media you
send: a prompt alone is text-to-video, image_url is image-to-video, and first_frame_url + last_frame_url render
between two stills. prompt, quality and duration are required, and aspect_ratio too on text-to-video (it is
refused with an image, whose own shape is used). generate_multi_clip_switch exists on pixverse/v6 only and accepts
false alone; on pixverse/c1 describe several shots in the prompt instead. Images are public https URLs, which the
generator fetches. A field a model does not take is a 400 naming it, before anything is generated.
Price. Per second of output, by quality, at the with-audio rate when generate_audio_switch is true:
| model | 360p | 540p | 720p | 1080p |
|---|---|---|---|---|
pixverse/v6 |
$0.025/s · $0.035/s with audio | $0.035/s · $0.045/s | $0.045/s · $0.06/s | $0.09/s · $0.115/s |
pixverse/c1 |
$0.03/s · $0.04/s with audio | $0.04/s · $0.05/s | $0.05/s · $0.065/s | $0.095/s · $0.12/s |
Video Expand (pixverse/video-expand) widens a video to a new shape and fills the new area to match the picture.
Send video_url (a public https URL of an MP4, MOV or WebM, up to 30 seconds and 50 MB; the generator fetches it),
aspect_ratio (16:9, 9:16, 21:9, 4:3, 3:4 or 1:1) and quality (720p or 1080p), all three required;
there is no prompt. It is billed on the length of the video you send, in whole seconds rounded up: $0.06/s at 720p,
$0.12/s at 1080p.
Answers. The submit and the completed poll carry the generator's own task fields beside ours (job_id,
status, model, media_url), and ours win where a name collides. A request the generator refuses is a 400 at
submit, or a failed poll, with its own message and its code in error.provider_code.
curl -sS https://api.sociaro.com/v1/pixverse/generations \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"model": "pixverse/v6", "prompt": "a red kite over a beach", "quality": "540p", "duration": 5, "aspect_ratio": "16:9"}'
# -> { "video_id": ..., "job_id": "<job_id>", "status": "submitted", "model": "pixverse/v6" }
curl -sS https://api.sociaro.com/v1/pixverse/generations/<job_id> -H "Authorization: Bearer $KEY"
The Pruna route (/v1/pruna/generations)
pruna/p-image, pruna/p-image-edit, pruna/p-video, pruna/p-video-2-pro-reference,
pruna/p-video-2-pro-avatar, pruna/p-video-upscale and pruna/p-video-2-pro-replace take Pruna's own request body, so Pruna's documentation for each model reads one-to-one:
{"model": "pruna/p-video", "input": {"prompt": "…", "duration": 5}}, plus our optional user. Fields go inside
input; anything else at the top level is 400 unknown field(s).
- Priced from the request (the two image models and
pruna/p-video).pruna/p-imageis $0.005 per image andpruna/p-image-edit$0.01.pruna/p-videois charged per second fromduration(1–20, default 5),resolution(720pby default at $0.02/s, or1080pat $0.04/s) anddraft(defaultfalse;trueis a quarter of the rate). These three are checked before anything runs.input.audiois not offered on it (400 Gateway.InvalidRequest). - Billed on the finished video (
pruna/p-video-2-pro-reference,pruna/p-video-2-pro-avatar). The gateway reads the length of the finished MP4 when the job completes and bills whole seconds of it, rounded down: a 15 second request that renders 14.375 seconds is billed 14. The Avatar is billed on those seconds alone (resolution480p$0.02/s, or768pby default at $0.04/s; any other value is a400): the portrait, the audio, the voice and the language do not change the price. The Reference model also bills what you send: each reference image, and each second of reference video and audio, counted up to the output length plus half a second and at most 15 seconds of each in all. The gateway reads those lengths from each file's own header at submit (a file it cannot reach, or whose header does not state its length, is a400naming it), so the price never rests on a number you state. Rates are on the model's page. - Billed on the finished video, by its size and frame rate (
pruna/p-video-upscale: a video in, the same video back at a larger size). The gateway reads the finished MP4 when the job completes and bills the seconds of it rounded up, at a rate set by the tier of the video that comes back and by its frame rate, the source's orfps(16 to 60) when you set it. The tier istarget(720p,1080pby default,2k,4k), or a larger one when the video comes back larger: it is never belowtarget, and above 4k is billed as 4k (a 4K source sent withtarget: 720pcomes back at 4K and is billed at the4krate). Up to 30 fps720p$0.01/s,1080p$0.02/s,2k$0.04/s,4k$0.08/s; above 30 fps double that. Withturbo: truethe rate is about a third of the standard one at any frame rate:720p$0.0035/s,1080p$0.007/s,2k$0.014/s,4k$0.028/s. The source's length affects the price only through the seconds it returns. The generator processes at most 2400 frames at720p, 1200 at1080p, 600 at2kand 300 at4k(above 30 fps, 30 a second), and refuses a longer video. The video is a public https url up to 512 MiB. Rates are on the model's page. - Billed on the finished video, rounded up (
pruna/p-video-2-pro-replace: a source video and 1 or 2 pictures in, the same video back with the pictured person, or two people, in place, at 24 fps). The gateway reads the finished MP4 when the job completes and bills the seconds of it rounded up, at the rate ofresolution:480p$0.05/s,768pby default at $0.10/s,1080p$0.12/s,2k$0.14/s,4k$0.18/s; any other value is a400. The pictures,instruction_promptand the audio settings do not change the price. The source runs 1 to 120 seconds; a longer one is cut to 120 seconds by the generator and billed on the 120 seconds returned. A third picture is a400. A long video at2kor4kmay be refused by the generator in its own words, and is not billed. The job can be polled for 3 hours from submission. You must hold the rights to, or the consent of, every person whose likeness you send or replace. Rates are on the model's page. - The generator's own content check is always on where the model has a switch for it: the gateway sets
disable_safety_filter/disable_safety_checkertofalseand refusestrue; onpruna/p-video-upscaleandpruna/p-video-2-pro-replaceit setsenable_safety_filtertotrueand refusesfalse. - Errors. A request the generator refuses (an
inputfield the model does not know, a value outside its range) is400with the generator's own words inerror.message, and its code inerror.provider_codewhen it gives one. When the request cannot be taken right now the answer is503 Gateway.UpstreamUnavailable: nothing was created and nothing is charged. A busy generator is429withRetry-After, and a generator that failed is502; both carry its own words inerror.messageand its code inerror.provider_codewhen it gave them. - The poll answers our
job_id,status,modeland amedia_url, plus Pruna's ownmetadata(e.g.seed). A job whose finished video the gateway cannot read staysprocessingand is never billed. - Terms. Pruna's Terms of Service, its Acceptable Use Policy and the licence of each model apply to your use of the Pruna models and of their outputs, and you must pass them on to your own users; the clause and the licence links are on each model's page.
The Ideogram route (/v1/ideogram/generations)
Sixteen ids share one route and take Ideogram's own fields inside input:
{"model": "ideogram/ideogram-4", "input": {"prompt": "…", "rendering_speed": "turbo"}}, plus our optional user.
Anything else at the top level is 400 unknown field(s), and so is a field the chosen model does not list in the table
above. Poll GET /v1/ideogram/generations/{job_id}. All sixteen are also served by the Jobs API (POST /v2/jobs), where
num_images is fixed at 1.
- Text to image:
ideogram/ideogram-4andideogram/ideogram-3(3.0 adds style codes, presets, a colour palette and style reference images);ideogram/ideogram-4-transparentandideogram/ideogram-3-transparentgive a PNG with alpha (the 3.0 one can upscale in the same call withupscale_factor). - Edit one image:
ideogram/ideogram-4-remixandideogram/ideogram-3-remixtransform it by prompt;ideogram/ideogram-3-inpaintrepaints the masked part;ideogram/ideogram-3-reframeextends it to a newresolution(no prompt);ideogram/ideogram-3-replace-backgroundkeeps the subject and paints a new background from a prompt (no mask);ideogram/ideogram-remove-backgroundreturns the subject as a transparent PNG. - SVG:
ideogram/ideogram-vectordraws SVG artwork from a prompt and up to five optional source images;ideogram/ideogram-vectorizeconverts one raster image to SVG (mode:simple,detailedorauto). The result is an SVG file;media_urlpoints at it. - Files are public https urls, never base64:
image,images,maskandstyle_reference_images(up to ten) are fetched by the gateway itself, JPEG, PNG or WEBP, so a url behind a login fails with a400naming the field. Size limits per file: 25 MB onideogram-3-inpaint,ideogram-3-reframe,ideogram-remove-background,ideogram-vectorand everystyle_reference_images; 50 MB on the two remix models,ideogram-3-replace-backgroundandideogram-vectorize;ideogram-3takes only style reference images. The mask is black where the picture is edited and white where it is kept, and has the same width and height as the image.asyncandwebhook_urlare refused (400): use the job's own callback options. - Ideogram 4.5.
ideogram/ideogram-4-5(text to image, and editing with source images and a mask) andideogram/ideogram-4-5-precise-edit(edit one image) takequalityinstead ofrendering_speed, and the same rules apply. Their files are public https urls:imagesandmaskonideogram-4-5(up to 25 MB each),image,reference_imagesandmaskon Precise Edit (up to 50 MB each; the image at most 67,108,864 pixels). Precise Editcontext_window:none(the default) edits the whole image, and one larger than 2048×2048 pixels in area comes back scaled down;autoneeds amaskand keeps the full resolution unless the mask selects more than 2048×2048 pixels (then the whole image is edited and comes back scaled down); ory_min,x_min,y_max,x_max(rows first, max edges exclusive), a box inside the image with each side at least 256 px, area at most 2048×2048 and aspect at most 6:1. Price per image byquality:ideogram-4-5withoutimageslow $0.03, medium $0.06, high $0.10 (default high;very_lowis a400); withimages, and on Precise Edit, very_low $0.008, low $0.03, medium $0.06, high $0.22 (default medium). Onlyquality, and whether source images are sent onideogram-4-5, change the price;context_windowand the size of the image do not. - Ideogram 4.6.
ideogram/ideogram-4-6(text to image up to 4096×4096, and editing with source images and a mask) andideogram/ideogram-4-6-precise-edit(edit one image up to 8192×8192; the result keeps its width and height) take the same fields and file limits as 4.5, with these differences.sizeonideogram-4-6:auto(the default, about 2048×2048),source(the size of the first ofimages; needs them) orWIDTHxHEIGHT, both sides multiples of 32, at most 4096×4096 and an aspect of at most 6:1.qualitydefaults tomediumon both, andvery_lowis accepted withoutimagestoo, up to 2K. Precise Editcontext_windowdefaults toauto(the generator picks the region, around themaskwhen one is sent);nonesends the whole image; a boxy_min,x_min,y_max,x_max(rows first, max edges exclusive) edits part of a 4K or 8K image at full resolution. Price per image byqualityand size: 2K when the area is at most 2048×2048 pixels (4,194,304), 4K above that; the area decides, not the longer side (2880×1440 is 2K, 2080×2048 is 4K). The size is thesizeasked for onideogram-4-6(autois 2K,sourcethe first image's size) and the size ofimageon Precise Edit (up to 8192×8192 at the 4K price);context_windownever changes the price, andvery_lowis always $0.008, priced at 2K whatever the size (onideogram-4-6an exactsizeover 2048×2048 in area is a400). Undersourceand on Precise Edit, at any other quality an image that comes back larger than 2048×2048 in area is billed at 4K, and an input image whose width and height cannot be read from its own header is a400.ideogram-4-6withoutimages: low $0.03 / $0.06 (2K / 4K), medium $0.06 / $0.12, high $0.10 / $0.20. Withimages, and on Precise Edit: low $0.03 / $0.06, medium $0.06 / $0.20, high $0.22 / $0.60. Charged per image the generator produces (at mostnum_images). private(where the model lists it) is yours to set; left out, Ideogram's own default applies.- Price, per generated image.
rendering_speed(turbo,default,quality; defaultdefault) sets it on every model that takes it:ideogram-4,ideogram-4-remixturbo $0.03, default $0.06, quality $0.10;ideogram-3,ideogram-3-remix,ideogram-3-inpaint,ideogram-3-reframe,ideogram-3-replace-backgroundturbo $0.03, default $0.06, quality $0.09.ideogram-4-transparentalso depends onoutput_resolution(default1k): 1k and 2k turbo $0.03, default $0.06, quality $0.10; 4k $0.19 / $0.22 / $0.26; 8k $0.35 / $0.38 / $0.42.ideogram-3-transparentalso depends onupscale_factor(defaultx1): x1 turbo $0.04, default $0.07, quality $0.10; x2 $0.16 / $0.19 / $0.22; x4 $0.20 / $0.23 / $0.26.ideogram-remove-backgroundis $0.01 per request andideogram-vectorize$0.10 per request whatever the mode.ideogram-vector, per SVG, byquality(defaultmedium): low $0.13, medium $0.16, high $0.20; with source images low $0.13, medium $0.16, high $0.32. Multiplied bynum_images(1–8 on/v1; not on the two background and vectorize models that make one result). - Every image the generator produces is billed, including an image it withholds after its own safety check. A
withheld image is not delivered, so a job can be billed for more images than it returns; if all of them were
withheld the job ends
failedand is still billed. A request the generator refuses, and a job that fails without producing images, is not billed. - The poll answers
job_id,status,model,media_url(the first result) andmedia_urls(every delivered result), plus the generator's ownmetadata(for example the seed of each image). On/v1the links are on our domain and valid for one hour; on/v2/jobsthey are permanent links on our CDN. - Errors. A request the generator refuses is
400with its own words inerror.messageand its code (reject_reason) inerror.provider_code; a job that fails reportsfailure_reasonasprovider_code. When the request cannot be taken right now the answer is503 Gateway.UpstreamUnavailable: nothing was created and nothing is charged. The generator's404,405,407,409or415answers502submit failed upstream, with nothing of the generator's. A busy generator is429withRetry-After, and a generator that failed is502; both carry its own words and its code inerror.provider_codewhen it gave them.
The Recraft route (/v1/recraft/generations)
Nine ids share one route and take Recraft's own fields inside input:
{"model": "recraft/recraft-v4-1", "input": {"prompt": "…", "size": "16:9"}}, plus our optional user. Anything else
at the top level is 400 unknown field(s), and so is a field the chosen model does not list in the table above. Poll
GET /v1/recraft/generations/{job_id}. All nine are also served by the Jobs API (POST /v2/jobs), one image per job:
n is not sent there.
- Text to image:
recraft/recraft-v4-1-flash-v2andrecraft/recraft-v4-1make a 1K raster image,recraft/recraft-v4-1-proa 2K one;recraft/recraft-v4-1-vectorandrecraft/recraft-v4-1-pro-vectordraw SVG artwork.nis 1–6 on/v1(default 1).sizeis one of 14 aspect ratios (1:1,2:1,1:2,3:2,2:3,4:3,3:4,5:4,4:5,6:10,14:10,10:14,16:9,9:16) or, on the raster models, an exact size from the model's own list (1K such as1024x1024; 2K on Pro, such as2048x2048); left out, one is picked from the prompt.image_formatiswebp(the default) orpng; a vector result is always SVG.random_seed0–4294967295.controls: up to 10colorsand abackground_color, each{"rgb": [r, g, b]}with an optionalweight(0–1, set on every colour or on none, summing to at most 1) andstd. - Styles (every generator but Flash V2):
style_reference_urls, 1–10 images whose style the result borrows; the/v1poll answer then carries thestyle_idof the style they make, which a later request may send asstyle_id(a/v2job does not return it).style_idandstyle_reference_urlscannot be combined;style_matchisflexibleorprecise. - Tools on one image (
image_url, required):recraft/recraft-vectorizeconverts a raster image to SVG (versionv1, the default, orv1_pro;shape_stackinghierarchicalorcut_out; and the tuning fields in the table);recraft/recraft-remove-backgroundcuts the background away and returns a raster image (webporpng) whatever the input, SVG included;recraft/recraft-crisp-upscalesharpens and enlarges;recraft/recraft-creative-upscaleenlarges and adds detail. - Files are public https urls, never base64 (a
data:url is a400):image_urlandstyle_reference_urlsgo to the generator, which fetches them itself. An input image is PNG, JPEG or WEBP (SVG too on remove-background), under 20 MB, at most 16 megapixels, its longest side at most 4096 pixels and its shortest at least 256. zdr(every id): zero data retention — the generator neither stores nor logs the prompt or the input images. It does not cover the result, and it does not change the price.response_formatis refused (400): every result is delivered as a link.- Price. Per generated image:
recraft-v4-1-flash-v2$0.007,recraft-v4-1$0.035,recraft-v4-1-vector$0.08,recraft-v4-1-pro$0.21,recraft-v4-1-pro-vector$0.30;style_reference_urlsadd $0.005 once per request. Per request:recraft-vectorize$0.01 (v1) or $0.04 (v1_pro),recraft-remove-background$0.01,recraft-crisp-upscale$0.004,recraft-creative-upscale$0.25. Charged per image delivered, never more thann; a failed job is not charged. - The poll answers
job_id,status,model,media_url(the first result) andmedia_urls(every delivered result), plus the generator's own fields (for examplecreated, andstyle_idwhen references were sent). On/v1the links are on our domain and valid for one hour; on/v2/jobsthey are permanent links on our CDN. An SVG result is served as on Ideogram's vector models. - Errors arrive at the poll, not at submit. The submit answers
{"job_id", "status": "submitted", "model"}before the generator has seen the request. A request the generator refuses, a busy generator and a generator that failed all end the jobfailedat the poll, with the generator's own words inerror.messageand its code inerror.provider_codewhen it gave them, and nothing is charged; on/v2/jobssuch a job endsfailedwitherror.codeprovider_failed. A400at submit is the gateway's own check of the body (a field the model does not list, a value out of range, a url that is not public https). Besides out of balance and too many requests, a429at submit comes withRetry-Afterand means the job could not be taken right now: nothing was created or charged; wait that many seconds and send it again.
Music and sound effects for a video (/v1/sonilo)
sonilo/video-to-music scores a finished video with original music; sonilo/video-to-sfx adds sound effects
synchronised to what happens on screen. Submit POST /v1/sonilo/generations, poll
GET /v1/sonilo/generations/{job_id}.
- The body is JSON with the generator's own field names:
video_url(required) plus the fields in the table above;segmentsis an array of objects. Any other field is a400. - The video is fetched by the generator. A
/v2result link works at any time; a/v1/medialink only while it is still well inside its hour. - The poll answer is the generator's own finished task with every link replaced by a one-hour
/v1/medialink, plusmedia_url(the main track) andmedia_urls(every track: variants, and thevocals,mux,duckedor stem tracks you asked for). Download them within the hour. - Billing is per second of the generated track, rounded up to a whole second, at $0.009 per second, with a minimum
of 10 seconds per variant for music (each of
variants_numis billed as its own track) and 3 seconds for sound effects. - Errors. A
400at submit carries the generator's own reason and itsprovider_code(a video too long, no video track, bad segments). A busy generator's429comes withRetry-After: wait that long. It carries the generator's own words and itsprovider_codewhen it gave them, else readsthe generator is at capacity, retry shortly; a502(the generator failed) carries them the same way. A503 Gateway.UpstreamUnavailablemeans the request cannot be taken right now: nothing was created and nothing is charged. - Licence. Commercial use, including by your own users, is allowed. A release to film, TV, broadcast or streaming services needs Sonilo's sales team first.
Delivery: media_url is a capability, not a bearer URL
It points at https://api.sociaro.com/v1/media/{id} and needs no Authorization header — the opaque
id itself is the credential, so anyone holding the link can fetch the asset until it expires. Treat it
like a signed URL: do not log it, do not forward it, and copy the asset into your own storage within
the hour.
The generator's own storage host is never exposed through media_url.
Status codes
| HTTP | Meaning |
|---|---|
200 |
submitted · processing · completed — or a failed job; check the JSON status |
400 |
bad body: unknown, malformed or out-of-range field, an unsupported model, or the generator's own validation error passed through on submit |
401 |
missing or invalid key |
403 |
the key is not granted this model, or the job belongs to another key |
404 |
unknown or expired job id / media id |
413 |
body over the route's cap — send images as URLs, not inline base64 |
422 |
one of the media files you sent could not be prepared for the generator (Gateway.InputPreparationFailed); the message names the part and carries the reason |
429 |
budget exceeded, rate-limited, OR the generator busy — read error.message; they are different problems |
502 |
the generator gave us no usable job — retryable on poll, NOT on submit. When the generator said why, error.message is its own words and error.provider_code its code. (upstream_status=0 on a RelayError means the RELAY could not reach the vendor at all; that path carries no vendor code.) |
503 |
temporarily unavailable — retryable on poll; on submit only when it is a confirmed refusal; a 503 with Retry-After asks you to wait that many seconds. On /v1/ideogram/generations, /v1/kling/generations, /v1/pixverse/generations, /v1/pruna/generations and /v1/sonilo/generations a 503 with error.code Gateway.UpstreamUnavailable and no Retry-After is a refusal of the gateway, not of your request: nothing was created or charged, retry later (on Ideogram a refusal of the path, proxy or media type we send — its 404, 405, 407, 409, 415 — answers 502 submit failed upstream instead, also with nothing of the generator's) |
429 — check which one it is
budget exceeded for this organisation keeps answering 429 until the organisation is topped up;
a rate limit clears on its own after a backoff. It is the ORGANISATION's balance in both the message
and the fix — keys carry no separate monetary ceiling, so there is no key setting to raise. Both are always safe to retry on poll. (Before 2026-08-05 an
over-budget key got a 502 here, which read as a gateway fault.)
A third case: the generator itself is busy and did not take the job (on /v1/alibaba/generations,
/v1/ideogram/generations, /v1/kling/generations, /v1/pixverse/generations, /v1/pruna/generations and
/v1/sonilo/generations). error.message is then the generator's own sentence and error.provider_code its code when
it gave them, else the generator is at capacity, retry shortly. It comes with Retry-After: wait that many seconds
and send it again.
On /v1/recraft/generations a busy generator never answers the submit: the job ends failed at the poll with the
generator's words (see The Recraft route). A 429 with Retry-After on that submit means the job could not be taken
right now: nothing was created or charged; wait that many seconds and send it again.
An organisation that runs out of balance mid-generation can still poll and collect the job it already submitted — paid work in flight is never stranded. Submit is refused in that state.
502 on submit is NOT safely retryable
There is no idempotency key on these routes. A 502 can mean the generator never saw the request — or
that it accepted and started charging a job whose id never reached us. A network timeout after the
request was sent looks identical. Retrying creates a second paid generation. On a submit 502: stop,
and check whether a job appeared before sending anything again. The same caveat applies to a submit 503.
On the Seedance task route the two cases are told apart for you: Gateway.UpstreamUnreachable means
nothing left us and a retry is safe; Gateway.UpstreamOutcomeUnknown is the case this warning is about.
400, 401, 403, 404 are terminal, and so is a failed job — resubmit only if you want a fresh,
separately billed attempt.
Input URLs
Every generator fetches your input images and videos itself. The gateway never rewrites them, and downloads
none of them, with one exception: for pruna/p-video-2-pro-reference it reads the header of each reference video
and audio file to bill its length, so those URLs must be reachable by the gateway too. So a URL must be:
- publicly reachable — a host only visible from your own network fails inside the generator;
- still valid at fetch time — a signed link that expires in seconds will not survive the queue;
- served to automated clients. Some hosts refuse them: Wikimedia answers
403to the fetcher, and the failure surfaces as animage/video_urlparameter error that says nothing about the host.
Inline base64 works only for small inputs and is capped per route (413 above). URLs have no cap of ours.
No host of your own? POST /v2/files stores a picture, clip or sound on our CDN and returns a public link made for
this: see Files.
Billing
What is left, in one call: GET /v1/balance answers {"remaining": 312.58} — the same figure
the console shows: your ORGANISATION's limit minus what it has spent. That is the only balance there
is; keys and teams carry no separate budget, so every key in your organisation reads the same
number. When there is nothing left it answers 429 with no figures at all, which is deliberate: a
number you cannot spend is not an answer. It excludes work still running, because a generation is
billed on completion.
Charged against your organisation's balance when the generation completes — on the first completed poll for the submit-and-poll routes, and within the one call itself on the synchronous ones such as /v1/byteplus/images/generations, which has no poll. A failed job is not billed. What the
charge is computed FROM differs by model — per image, per second of output, or per vendor-metered token —
so read the per-model notes rather than assuming. Each model's own page has the exact rule. The
Seedance rows — bytedance/seedance-2.0, -2.0-fast, -2.0-mini, bytedance/seedance-2.5 and -2.5-flash — are
metered from what was actually rendered rather than from what you requested. On those, omitting
resolution bills the generator's own default tier, 720p — a per-model default, not a gateway-wide
one: the HappyHorse and Wan 2.7 video models default to 1080p, so check the model's own row rather
than carrying this number across.
Still on Seedance: a tier the model does not have — 1080p or 4k on bytedance/seedance-2.0-mini
and bytedance/seedance-2.0-fast, 4k on bytedance/seedance-2.5, 1080p or 4k on
bytedance/seedance-2.5-flash — is refused with a 400
naming the ones it does. Only bytedance/seedance-2.0 offers all four. The check applies however you
ask, including the legacy --resolution / --rs prompt flag (--rs:4k and --rs=4k included),
because the vendor would otherwise accept the value, ignore it, and bill you for a 720p render.
A prompt longer than 100,000 characters (all text parts together) is refused with a 400. The vendor recommends far less
(about 1,000 words) but accepts more; the limit only keeps the check itself cheap.