Sociaro

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/videos serves no model in this document and answers 404 with error.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_generation on /model/info: that field says what a model produces, not where to send it. /v1/models returns only the OpenAI shape (id, object, created, owned_by), carries no routing information at all, and its owned_by is always the literal openai no 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. There n becomes a maximum of 1–12 and defaults to 12. The generator decides how many images to make, and each one is charged. Send n with it to cap the count. On /v2, n and enable_sequential: true are refused with 400 invalid_input (enable_sequential: false is fine); output.count sets the number there.
  • size: 1K (1024×1024 pixels in total) or 2K (2048×2048, default), or width*height with total pixels from 768×768 to 2048×2048 and an aspect ratio from 1:8 to 8:1. alibaba/wan-2-7-image-pro also takes 4K, and width*height up to 4096×4096 in total, except in image-set mode, where the limit is 2K (1K or 2K, or width*height up to 2048×2048). alibaba/wan-2-7-image has 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_sequential false).
  • prompt: the generator reads up to 5,000 characters and cuts off anything longer.
  • The generator does not support negative_prompt or prompt_extend on these two models. Say what to leave out in prompt.

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: true switches 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. With enable_interleave, n must be 1 or left out; the generator refuses any other value.
  • max_images (only with enable_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 mode 1K (default) or 2K, which keep the aspect ratio of the last input image. Or width*height, with total pixels from 768×768 to 2048×2048 (up to 1280×1280 with enable_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, and negative_prompt up 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_urls turns the request into an edit: 1–3 images on the 3.0 models, 1–10 on alibaba/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 between 512*512 and 2048*2048 and 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. Send false to keep your wording.
  • prompt_extend_mode: direct (default) or agent. agent is text-to-image only: with image_urls the generator returns 400.
  • enable_thinking: default true. It needs prompt_extend true, and it is not supported for an edit with agent.
  • 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-pro a 2K image costs nearly twice a 1K one; on alibaba/qwen-image-3 the 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-pro costs the same at every size and does not charge for input images.
  • alibaba/qwen-image-2-1-pro decides 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_url is removed (you poll), priority is removed, both in any letter case, safety_identifier is replaced, and generate_audio is set to false when you leave it out: sound is off unless you send true. Not on a final from a draft (it keeps the draft's sound), nor when you send your own audio (reference_audio) or omni_reference_task_type edit/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": true or 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. For safety_identifier we 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 a 400 Gateway.InvalidRequest. Nothing else about the answer changes.
  • model comes 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's model can be sent straight back as its final's model.
  • 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; a draft: true task 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 answers 404, as for an unknown id). We read the task first and send the generator a cancel only while it is queued, once; then we read it again, and only a task the generator now reports cancelled is cancelled: the answer is {"id", "status": "cancelled"}, a later poll answers the same, and a cancelled task is never charged. A running task is a 409 ("a running job cannot be cancelled"), a finished one a 409 too, and neither is touched — unlike the vendor's own DELETE, 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 a 403 Gateway.TaskNotOwned and an unknown id a 404, 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 is 502 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) and page_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 a 400), 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, so total can count tasks whose record has expired.
  • bytedance/seedance-2.5 goes to 4k (2.5 Flash stops at 720p). At 4k the generator takes at most 15 requests a minute and one task at a time; past that its own 429 reaches you as it is on this route (on /v1/modelark it arrives on the poll as a failed task with its error.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 is 503 Gateway.UpstreamUnavailable, and a task that failed for that reason reads status: "failed" with that same error. Only our own refusals look different, and every one of them carries a stable error.code beginning Gateway. (below). Status codes are the ones listed under Status codes; the code tells apart refusals that share a status — notably the two 429s and the two submit 502s.
{"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 as draft_task.id when 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 queued it 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 own error.code and message, unchanged. queued normally 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 still queued after it is failed with Gateway.InputPreparationTimeout, which is an error case.
  • After queued the poll answers the generator's statuses (running, succeeded, failed, expired, cancelled), with your id and model in the form you sent. A task is succeeded only when its result links are ready, so running for a little longer than the generator itself needs is normal.
  • Results are delivered as permanent links. On succeeded, content.video_url (and content.last_frame_url when you asked for it) are stable https links 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 https links in every media role: first_frame, last_frame, reference_image, reference_video and reference_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 public https and 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.id set to the draft's mk-… id, at 1080p or 4k. The draft must have succeeded first. Naming one that is still queued, or that failed before the generator took it, is refused on the submit with Gateway.InvalidDraft; 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.
  • Errors that are not ours: when the generator itself refuses a submit (including ModelOverloaded, InternalServiceError and RateLimitExceeded), the poll answers failed with that error — its code, message and provider_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 queued at once, and the gateway 200; past that the submit is refused with 429 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 a callback_url);
  • options.external_task_id — the gateway sets its own;
  • options.watermark_info.enabled: true — false is accepted;
  • a contents[] part of type element or voice;
  • on kling/kling-3.0-omni, reference videos: a contents[] part of type feature_video or base_video, and settings.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 a last_frame without settings.resolution: "1080p". Kling renders both at 1080p only, so at the default 720p the 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.duration is 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 a 400.
  • Kling's default resolution on 4.0 is 1080p, not 720p, and it is priced as such.
  • Up to 10 images per request, frames and reference images together. Give an image an id to name it in the prompt as @id; on Omni every middle_frame and refer_image needs one when there are several.
  • 4.0 has no settings.audio (describe the sound in the prompt), no settings.multi_shot and no 4k: each is a 400, 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, on kling/kling-4.0-t2v and kling/kling-4.0-i2v, contents[] parts of type element and voice.
  • Input videos, on kling/kling-4.0-omni only: feature_video, a feature reference video (follow its motion, its rhythm, its camera), and base_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 a base_video (Kling allows up to 5 reference videos and one base_video; the gateway counts the base_video among 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 a 400 and 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.duration stays required with a base_video.
  • Elements and voices, on kling/kling-4.0-omni only: 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 a 404 and 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: a 400. 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.duration is required, as on 4.0: a request without it is a 400.
  • 720p is the only resolution: 1080p and 4k are a 400.
  • kling/kling-4.0-flash-i2v takes one first_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_frame or voice part is a 400, as are settings.multi_shot and any other field Kling does not define.
  • settings.audio, on kling/kling-4.0-flash-omni only: native (the default) makes sound to match the picture; original keeps an input video's own sound, the base_video's, else the first feature_video's, and needs one of them. Any other value is a 400. Neither changes the price. The t2v and i2v ids take no settings.audio.
  • Input videos, on kling/kling-4.0-flash-omni only: as on kling/kling-4.0-omni (a public https URL, at most 5 videos, at most one of them a base_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-omni only: as on kling/kling-4.0-omni, at most 7, yours or Kling's presets; any other id is a 404. 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" and element_video_list (an element made from a video), and a voice from video_id: not available on this gateway yet;
  • callback_url (these routes send no callback: get the task, or the list, instead) and external_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-image is $0.005 per image and pruna/p-image-edit $0.01. pruna/p-video is charged per second from duration (1–20, default 5), resolution (720p by default at $0.02/s, or 1080p at $0.04/s) and draft (default false; true is a quarter of the rate). These three are checked before anything runs. input.audio is 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 (resolution 480p $0.02/s, or 768p by default at $0.04/s; any other value is a 400): 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 a 400 naming 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 or fps (16 to 60) when you set it. The tier is target (720p, 1080p by default, 2k, 4k), or a larger one when the video comes back larger: it is never below target, and above 4k is billed as 4k (a 4K source sent with target: 720p comes back at 4K and is billed at the 4k rate). Up to 30 fps 720p $0.01/s, 1080p $0.02/s, 2k $0.04/s, 4k $0.08/s; above 30 fps double that. With turbo: true the 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 at 720p, 1200 at 1080p, 600 at 2k and 300 at 4k (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 of resolution: 480p $0.05/s, 768p by default at $0.10/s, 1080p $0.12/s, 2k $0.14/s, 4k $0.18/s; any other value is a 400. The pictures, instruction_prompt and 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 a 400. A long video at 2k or 4k may 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_checker to false and refuses true; on pruna/p-video-upscale and pruna/p-video-2-pro-replace it sets enable_safety_filter to true and refuses false.
  • Errors. A request the generator refuses (an input field the model does not know, a value outside its range) is 400 with the generator's own words in error.message, and its code in error.provider_code when it gives one. When the request cannot be taken right now the answer is 503 Gateway.UpstreamUnavailable: nothing was created and nothing is charged. A busy generator is 429 with Retry-After, and a generator that failed is 502; both carry its own words in error.message and its code in error.provider_code when it gave them.
  • The poll answers our job_id, status, model and a media_url, plus Pruna's own metadata (e.g. seed). A job whose finished video the gateway cannot read stays processing and 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-4 and ideogram/ideogram-3 (3.0 adds style codes, presets, a colour palette and style reference images); ideogram/ideogram-4-transparent and ideogram/ideogram-3-transparent give a PNG with alpha (the 3.0 one can upscale in the same call with upscale_factor).
  • Edit one image: ideogram/ideogram-4-remix and ideogram/ideogram-3-remix transform it by prompt; ideogram/ideogram-3-inpaint repaints the masked part; ideogram/ideogram-3-reframe extends it to a new resolution (no prompt); ideogram/ideogram-3-replace-background keeps the subject and paints a new background from a prompt (no mask); ideogram/ideogram-remove-background returns the subject as a transparent PNG.
  • SVG: ideogram/ideogram-vector draws SVG artwork from a prompt and up to five optional source images; ideogram/ideogram-vectorize converts one raster image to SVG (mode: simple, detailed or auto). The result is an SVG file; media_url points at it.
  • Files are public https urls, never base64: image, images, mask and style_reference_images (up to ten) are fetched by the gateway itself, JPEG, PNG or WEBP, so a url behind a login fails with a 400 naming the field. Size limits per file: 25 MB on ideogram-3-inpaint, ideogram-3-reframe, ideogram-remove-background, ideogram-vector and every style_reference_images; 50 MB on the two remix models, ideogram-3-replace-background and ideogram-vectorize; ideogram-3 takes 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. async and webhook_url are 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) and ideogram/ideogram-4-5-precise-edit (edit one image) take quality instead of rendering_speed, and the same rules apply. Their files are public https urls: images and mask on ideogram-4-5 (up to 25 MB each), image, reference_images and mask on Precise Edit (up to 50 MB each; the image at most 67,108,864 pixels). Precise Edit context_window: none (the default) edits the whole image, and one larger than 2048×2048 pixels in area comes back scaled down; auto needs a mask and keeps the full resolution unless the mask selects more than 2048×2048 pixels (then the whole image is edited and comes back scaled down); or y_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 by quality: ideogram-4-5 without images low $0.03, medium $0.06, high $0.10 (default high; very_low is a 400); with images, and on Precise Edit, very_low $0.008, low $0.03, medium $0.06, high $0.22 (default medium). Only quality, and whether source images are sent on ideogram-4-5, change the price; context_window and 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) and ideogram/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. size on ideogram-4-6: auto (the default, about 2048×2048), source (the size of the first of images; needs them) or WIDTHxHEIGHT, both sides multiples of 32, at most 4096×4096 and an aspect of at most 6:1. quality defaults to medium on both, and very_low is accepted without images too, up to 2K. Precise Edit context_window defaults to auto (the generator picks the region, around the mask when one is sent); none sends the whole image; a box y_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 by quality and 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 the size asked for on ideogram-4-6 (auto is 2K, source the first image's size) and the size of image on Precise Edit (up to 8192×8192 at the 4K price); context_window never changes the price, and very_low is always $0.008, priced at 2K whatever the size (on ideogram-4-6 an exact size over 2048×2048 in area is a 400). Under source and 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 a 400. ideogram-4-6 without images: low $0.03 / $0.06 (2K / 4K), medium $0.06 / $0.12, high $0.10 / $0.20. With images, 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 most num_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; default default) sets it on every model that takes it: ideogram-4, ideogram-4-remix turbo $0.03, default $0.06, quality $0.10; ideogram-3, ideogram-3-remix, ideogram-3-inpaint, ideogram-3-reframe, ideogram-3-replace-background turbo $0.03, default $0.06, quality $0.09. ideogram-4-transparent also depends on output_resolution (default 1k): 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-transparent also depends on upscale_factor (default x1): 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-background is $0.01 per request and ideogram-vectorize $0.10 per request whatever the mode. ideogram-vector, per SVG, by quality (default medium): low $0.13, medium $0.16, high $0.20; with source images low $0.13, medium $0.16, high $0.32. Multiplied by num_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 failed and 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) and media_urls (every delivered result), plus the generator's own metadata (for example the seed of each image). On /v1 the links are on our domain and valid for one hour; on /v2/jobs they are permanent links on our CDN.
  • Errors. A request the generator refuses is 400 with its own words in error.message and its code (reject_reason) in error.provider_code; a job that fails reports failure_reason as provider_code. When the request cannot be taken right now the answer is 503 Gateway.UpstreamUnavailable: nothing was created and nothing is charged. The generator's 404, 405, 407, 409 or 415 answers 502 submit failed upstream, with nothing of the generator's. A busy generator is 429 with Retry-After, and a generator that failed is 502; both carry its own words and its code in error.provider_code when 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-v2 and recraft/recraft-v4-1 make a 1K raster image, recraft/recraft-v4-1-pro a 2K one; recraft/recraft-v4-1-vector and recraft/recraft-v4-1-pro-vector draw SVG artwork. n is 1–6 on /v1 (default 1). size is 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 as 1024x1024; 2K on Pro, such as 2048x2048); left out, one is picked from the prompt. image_format is webp (the default) or png; a vector result is always SVG. random_seed 0–4294967295. controls: up to 10 colors and a background_color, each {"rgb": [r, g, b]} with an optional weight (0–1, set on every colour or on none, summing to at most 1) and std.
  • Styles (every generator but Flash V2): style_reference_urls, 1–10 images whose style the result borrows; the /v1 poll answer then carries the style_id of the style they make, which a later request may send as style_id (a /v2 job does not return it). style_id and style_reference_urls cannot be combined; style_match is flexible or precise.
  • Tools on one image (image_url, required): recraft/recraft-vectorize converts a raster image to SVG (version v1, the default, or v1_pro; shape_stacking hierarchical or cut_out; and the tuning fields in the table); recraft/recraft-remove-background cuts the background away and returns a raster image (webp or png) whatever the input, SVG included; recraft/recraft-crisp-upscale sharpens and enlarges; recraft/recraft-creative-upscale enlarges and adds detail.
  • Files are public https urls, never base64 (a data: url is a 400): image_url and style_reference_urls go 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_format is 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_urls add $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 than n; a failed job is not charged.
  • The poll answers job_id, status, model, media_url (the first result) and media_urls (every delivered result), plus the generator's own fields (for example created, and style_id when references were sent). On /v1 the links are on our domain and valid for one hour; on /v2/jobs they 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 job failed at the poll, with the generator's own words in error.message and its code in error.provider_code when it gave them, and nothing is charged; on /v2/jobs such a job ends failed with error.code provider_failed. A 400 at 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, a 429 at submit comes with Retry-After and 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; segments is an array of objects. Any other field is a 400.
  • The video is fetched by the generator. A /v2 result link works at any time; a /v1/media link 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/media link, plus media_url (the main track) and media_urls (every track: variants, and the vocals, mux, ducked or 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_num is billed as its own track) and 3 seconds for sound effects.
  • Errors. A 400 at submit carries the generator's own reason and its provider_code (a video too long, no video track, bad segments). A busy generator's 429 comes with Retry-After: wait that long. It carries the generator's own words and its provider_code when it gave them, else reads the generator is at capacity, retry shortly; a 502 (the generator failed) carries them the same way. A 503 Gateway.UpstreamUnavailable means 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 403 to the fetcher, and the failure surfaces as an image/video_url parameter 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.