Sociaro

Model inputs — the input object, model by model

This page covers the input object of POST /v2/jobs; the envelope around it is on Jobs API.

The parameters in input are the ones documented for that model, not a /v2 dialect, and every model's are checked at submit against its input_schema (see below). The families served here word their prompts differently:

Alibaba

Alibaba models (alibaba/*) take a plain prompt string:

{"model": "alibaba/wan-3-video", "input": {"prompt": "a paper boat drifting down a rain-soaked street"}}

Their input is closed: the fields are the ones in the model's input_schema, each with its type and range, and anything else is a 400 invalid_input at submit, including a field the generator would have ignored (for example negative_prompt on alibaba/wan-2-7-image). On the image models size is a W*H string or a tier, and color_palette on alibaba/wan-2-7-image takes 3 to 10 {hex, ratio} entries whose ratios add up to 100.

ByteDance Seedance

ByteDance Seedance models (bytedance/seedance-*) take the vendor's content array, the same shape as on /v1:

{"model": "bytedance/seedance-2.0",
 "input": {"content": [{"type": "text", "text": "a paper boat drifting down a rain-soaked street"}],
           "resolution": "480p", "duration": 4, "generate_audio": false}}

Seedance also takes the generator's execution_expires_after (seconds, 3600–259200) and safety_identifier (a fixed id for your end user, 1–64 characters). Both are checked at submit: a value outside those is a 400 invalid_input and no job. For safety_identifier we send a per-organisation pseudonym of your value, never the value itself, and the job stores only the pseudonym. The job itself still ends at its own max_runtime_sec.

Seedance's input is closed. At submit a 400 invalid_input and no job follow from: a field the model's input_schema does not name (service_tier, priority, callback_url, model and tools among them), a value outside an enum or range, and a content part that is wrongly shaped (an unknown type, a role the type does not take, an extra key, a url that is not a non-blank string). The part counts and the first-frame, last-frame and reference rules are checked there too.

return_last_frame: true also returns the clip's closing still, as an extra output after the clip (type image). It is not counted in output.count, adds no charge, and is optional: if it cannot be delivered, the clip is still delivered without it.

Seedance's own rules for frames, camera_fixed and draft are under How input is checked.

Edit or extend a clip

Editing or extending a clip on bytedance/seedance-2.0, bytedance/seedance-2.0-fast and bytedance/seedance-2.0-mini is the same shape, with no field or role of its own: put the clip in content as a reference_video part and say in the prompt what to do with it, naming it [Video 1]. Two or three clips are joined with generated transitions. The model page has the details, and the job is billed like any Seedance job with a video input:

{"model": "bytedance/seedance-2.0",
 "input": {"content": [{"type": "text", "text": "Replace the cat in [Video 1] with the lion from [Image 1]"},
                       {"type": "image_url", "image_url": {"url": "https://your-cdn.example.com/lion.jpg"},
                        "role": "reference_image"},
                       {"type": "video_url", "video_url": {"url": "https://your-cdn.example.com/cat.mp4"},
                        "role": "reference_video"}],
           "resolution": "720p", "ratio": "16:9", "duration": 5}}

Draft mode (Seedance 2.5)

bytedance/seedance-2.5 can render a cheap 480p draft first, so you can judge the shot before paying for the finished clip. It is a second job that names the first one. Send "draft": true in input:

{"model": "bytedance/seedance-2.5",
 "input": {"content": [{"type": "text", "text": "a paper boat drifting down a rain-soaked street"}],
           "duration": 4, "draft": true}}

The answer is an ordinary job, job_5cc8778b79574aaa7ea8fc09caec23e5. When it has succeeded, render the 1080p (or 4K) final by quoting that job_... id (ours, not the generator's) in a draft_task part, with a new Idempotency-Key:

{"model": "bytedance/seedance-2.5",
 "input": {"content": [{"type": "draft_task",
                        "draft_task": {"id": "job_5cc8778b79574aaa7ea8fc09caec23e5"}}]}}
  • Send no resolution unless you want the final at 4K. /v2 sets it on both steps, 480p on the draft and 1080p on the final; send "resolution": "4k" on the final for 4K. Any other value is a 400. (On /v1 a final does have to carry "resolution": "1080p" or "4k", because there your body goes to the generator as written. Here we build it, so you need not.)
  • The final reuses the draft's prompt, references, duration, ratio, seed and audio settings. You do not resend them.
  • The two jobs are billed separately, each as an ordinary video at its own resolution. The final's token rate is the one the draft's inputs earn, so a final whose draft had an input video is charged the with-video rate, although the final's own body has no video.
  • The draft has to be one of your own jobs, a draft, and succeeded. A job of someone else's gets the same answer as an id that does not exist. Past the generator's own seven days a final built from it fails.

Kling

Kling video models (the thirteen kling/* video ids) take Kling's own body, the same as on /v1/kling/generations: prompt on the -t2v ids, contents on the -i2v ids and on kling/kling-3.0-omni, kling/kling-4.0-omni and kling/kling-4.0-flash-omni, plus settings and options.

{"model": "kling/kling-2.6-t2v",
 "input": {"prompt": "a paper boat drifting down a rain-soaked street",
           "settings": {"resolution": "720p", "duration": 5}}}

Refused at submit

Their input_schema is closed, like every model's, and each of the following is a 400 invalid_input at submit:

  • a field the schema does not name (inside a contents part too: each part kind takes only the keys the schema lists for it)
  • options.callback_url (use the envelope's callback_url)
  • options.external_task_id
  • options.watermark_info.enabled: true
  • a contents part of type element except on kling/kling-4.0-omni and kling/kling-4.0-flash-omni, type voice except on kling/kling-4.0-omni
  • on kling/kling-3.0-omni a reference video (a contents part of type feature_video or base_video, or settings.audio: "original")
  • on 2.6 native audio or a last frame at 720p
  • on 4.0 and 4.0 Flash a missing settings.duration or more than 10 images
  • on Omni more than 5 input videos, two base_videos, a video not given as a public https URL, or more than 7 elements or 3 voices
  • on 4.0 Flash 1080p or a middle_frame or last_frame part

Elements, voices, failures and price

On kling/kling-4.0-omni and kling/kling-4.0-flash-omni an element_id (or, on 4.0 Omni, a voice_id) that is not your organisation's own (made on /v1/kling/elements or /v1/kling/voices, see the Generations API) or one of Kling's presets is a 404 not_found, and no job; a moment when the gateway cannot read Kling's preset list is a 503 unavailable, to retry. prompt_enhance is not offered on them. Their failures read like every /v2 job's (provider_rejected, provider_failed), with Kling's own reason in message, and on a refusal at submit its code in provider_code. The price is the /v1 price (Generations API), charged once, on completion.

Kling 4.0 and 4.0 Flash

The three Kling 4.0 ids, kling/kling-4.0-t2v, kling/kling-4.0-i2v and kling/kling-4.0-omni, are among the thirteen (Kling opened Kling 4.0 on 2026-10-23). On them settings.duration is required. kling/kling-4.0-omni also takes input videos, a feature_video and a base_video part, by URL, as on /v1: their lengths are read from each file's own header when you submit, so a video whose length cannot be read, or outside 3–30 seconds (each, and all together), is a 400 invalid_input and no job is created.

The three Kling 4.0 Flash ids, kling/kling-4.0-flash-t2v, kling/kling-4.0-flash-i2v and kling/kling-4.0-flash-omni, are among the thirteen too. On them settings.duration is required (3–20 seconds) and 720p is the only resolution. kling/kling-4.0-flash-omni takes input videos as kling/kling-4.0-omni does, each and all together 3–20 seconds, and elements, but no voices.

Kling Image 4.0

The two Kling 3.x image models, kling/kling-v3 and kling/kling-v3-omni, are not served here: they are /v1 only (Generations API). The Kling image model kling/kling-4.0-image is served here, with Kling's body (contents, settings and options, as on /v1) and settings.result_type (single or series). The number of images is output.count: 1 to 9 for a single result, 2 to 10 for a series. settings.n and settings.series_amount are refused, and so is auto. The images come back as outputs, in Kling's order, each with its own link, and the job is charged per image delivered, never more than output.count, at the /v1 price (Generations API).

MiniMax H3

MiniMax H3 video models (four ids, served direct from MiniMax and only here, on /v2: H3, H3 Max, H3 Highspeed and H3 Lite; GET /v2/models lists them and each has its own page in the catalogue) take MiniMax's own body: a content array of typed parts, exactly one text plus pictures (role first_frame, last_frame or reference_image), clips (reference_video) and sounds (reference_audio), each by a public https URL or a data: URI, and the required resolution and duration (whole seconds, 4–15; 5–15 on H3 Max), with an optional ratio. A text-only request needs a concrete ratio, never adaptive. Every clip comes with sound.

{"model": "minimax/h3",
 "input": {"content": [{"type": "text", "text": "The paper boat drifts down the rain-soaked street."},
                       {"type": "image_url", "image_url": {"url": "https://your-cdn.example.com/first.png"},
                        "role": "first_frame"}],
           "resolution": "768P", "duration": 10}}

Their schema is closed: a field it does not name, a value outside an enum or range and a content part of the wrong shape are each a 400 invalid_input at submit and no job. So are a resolution the model does not offer, spelt exactly as listed (H3 has 768P and 2K, Max, Highspeed and Lite 480P and 768P), a callback_url inside input (use the envelope's callback_url), an mm_file:// url, and model or resolution written in any other letter case (MODEL, Resolution). The counts are checked there too: at most one first frame, one last frame, nine reference pictures, three clips and three sounds; a first or last frame cannot share a request with reference parts; the text part is required; and a text-only request, like a request with reference parts on H3 Lite, needs a concrete ratio. The generator still judges the media itself (the length of a clip or sound, a picture's size and format) and the job then ends failed with provider_rejected, uncharged. prompt_enhance is not offered on them. They are billed once, on completion, from what the generator reports it rendered: seconds of output at the rendered resolution's rate, plus reference clips by their length and pictures past a free allowance; each model's page has the rates.

Again at 2K

minimax/h3-regeneration renders one of your own minimax/h3 jobs again at 2K, at its own length and with its own sound. Name that job by its id (ours, job_...) in source_job; nothing else needs sending, since the prompt, pictures and clips are the original job's:

{"model": "minimax/h3-regeneration",
 "input": {"source_job": "job_0123456789abcdef0123456789abcdef"}}

The original must be a job of yours that succeeded at 768P and was submitted less than 24 hours earlier. Any other source is a 400 invalid_input at submit and no job; someone else's job gets the same answer as an id that does not exist. Its schema is closed too, and narrower: source_job, an optional aigc_watermark (true or false) and a resolution of 2K (the only one, so it need not be sent) are all it takes, and anything else, MiniMax's own source_task_id included, is a 400 invalid_input. The original job is left as it was. The new one is billed once, on completion, from what the generator reports: seconds of 2K output, plus the original job's reference clips and pictures past the first five, which the generator bills again. The model's page has the rates.

Pruna

Pruna models (seven ids: 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; GET /v2/models lists them and each has its own page in the catalogue) take Pruna's own fields, the same object as input in the body of POST /v1/pruna/generations (Generations API). Each model's page lists its fields, and its GET /v2/models entry publishes them as input_schema, which is closed: a field it does not name is a 400 invalid_input at submit.

{"model": "pruna/p-video",
 "input": {"prompt": "a paper boat drifting down a rainy street", "duration": 5, "resolution": "720p"}}

A job makes one output (output.count is at most 1), and it is outputs[0].url, a link on cdn.sociaro.com kept for at least ten years (expires_at). pruna/p-video-2-pro-reference, pruna/p-video-2-pro-avatar, pruna/p-video-upscale and pruna/p-video-2-pro-replace are billed on the finished video, exactly as on /v1, once, on completion; the other three are priced from the request. pruna/p-video-2-pro-reference reads the length of each reference video and audio file from its own header when you submit, so a file whose length cannot be read is a 400 invalid_input and no job is created. pruna/p-video-2-pro-replace is the long one: its max_runtime_sec is 10800 (3 hours), where every other Pruna id has the default (video 30 minutes, image 5). The results of pruna/p-video-2-pro-replace and pruna/p-video-upscale can be up to 2 GiB. While a large result is being stored, one GET /v2/jobs/{id} can take long or time out; poll again.

How input is checked

GET /v2/models carries an input_schema per model, and it is a real one: the required field, every option that model takes, its allowed values, and — where the vendor publishes one — its limit, each with a short description. The resolutions and durations differ per model and the schema says which are which, so you can build a request from it rather than from a table.

The schema is enforced. It is JSON Schema draft 2020-12, the dialect of OpenAPI 3.1; it is not OpenAPI 3.0 and no 3.0 form is offered, so validate with a 2020-12 validator (ajv Ajv2020, Python jsonschema Draft202012Validator). Every model's schema is closed (additionalProperties is false), and POST /v2/jobs checks input against it with the same rules: an unknown field, a wrong type, a value outside an enum or range or a wrongly shaped part is a 400 invalid_input with job_created: false, no job and no charge. The message names the field, never the value. There is no grace period and no accept-and-ignore list.

Three details about how the check reads a body:

  • A whole-number field must be a JSON integer: send 5, not 5.0. A 2020-12 validator accepts 5.0; the API does not, and refuses it at submit. The same holds for the element_id and voice_id of a Kling part: send 7, not 7.0 or 7e0.
  • An optional top-level field sent as null counts as not sent.
  • On Seedance, frames and camera_fixed are not in the schema, because the generator refuses them on every Seedance model: they are refused at submit when they carry a value (anything but null, false, 0 or an empty string), with 400 invalid_input and frames is not supported by this model (or camera_fixed ...). On the 2.0 models omni_reference_task_type is listed as deprecated: it is accepted and has no effect there. draft is listed as deprecated on the 2.0 models and bytedance/seedance-2.5-flash, because only bytedance/seedance-2.5 has draft mode. On the 2.0 models and bytedance/seedance-2.5-flash, draft: true is refused at submit with 400 invalid_input, and draft: false passes the check and is sent to the generator as given, so leave the field out on those models.

What the check cannot judge is left to the generator, and a job that fails there ends failed and uncharged (see Failed jobs):

  • content moderation and the check for real people in input media
  • an input file the generator cannot fetch or decode (size, dimensions, codec, frame rate)
  • the length of an input clip or sound, except where it is read from the file's own header when you submit: on kling/kling-4.0-omni and kling/kling-4.0-flash-omni (input videos) and pruna/p-video-2-pro-reference (reference videos and sounds) a length that cannot be read is a 400 invalid_input, and so is a Kling video outside the model's range (see above); on Leda Pro a reference video or sound outside 2–15 s, or more than 15 s of either kind together, is a 400 invalid_input, with 0.15 s of tolerance per clip, and a length that cannot be read is left to the generator, except a reference video's on a request near Leda Pro's sequence limit, which is a 400 too
  • an expired draft
  • on Seedance a task type that does not fit the inputs when the type is left automatic, and old-style flags written inside the prompt text
  • on MiniMax a second text part and a last_frame sent without a first_frame
  • on Alibaba enable_thinking with prompt_extend off and some combinations of wan-3 references
  • a generator outage or timeout

The schema does not repeat what each model's own page explains in prose.

The text of all content parts together may be at most 100,000 characters (the vendor recommends about 1,000 words, so this only catches a runaway prompt). As on /v1, a longer prompt is a 400 invalid_input at submit, with job_created: false and no job; the estimate refuses it the same way.