Jobs API — one envelope for every async model
/v2 is a single pair of routes for every model that renders asynchronously. Where /v1 gives each
vendor family its own submit path, its own poll path and its own response shape, here you always
POST /v2/jobs, always GET /v2/jobs/{id}, and always read the same fields back — whichever
model you called.
- Base URL:
https://api.sociaro.com - Auth:
Authorization: Bearer <your-api-key>, the same key you use on/v1. /v1is unchanged and stays supported. Nothing you already have needs migrating.
The Jobs API is five pages:
- Overview (this page) — submit, poll, cancel and limits, several outputs, the callback and prompt enhancement.
- Model inputs — what goes in
input, model by model. - Models and prices — what a model costs before you send a request and after.
- Failures and retries — what to do when a job fails or an answer is lost.
- Webhooks — the signed
callback_urldelivery, how to verify it and how it is retried.
Submit
POST /v2/jobs, with an Idempotency-Key header — it is required. Replaying the same key returns
the same job; reusing it with a different body is a 409. If an answer never arrived, see Look up a job by its key.
curl https://api.sociaro.com/v2/jobs \
-H "Authorization: Bearer $SOCIARO_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: my-request-0001" \
-d '{
"model": "alibaba/wan-2-7-image",
"input": {"prompt": "a paper boat drifting down a rain-soaked street"}
}'
{"id": "job_5cc8778b79574aaa7ea8fc09caec23e5",
"model": "alibaba/wan-2-7-image",
"status": "queued",
"created_at": "2026-08-24T08:54:16.457268+00:00"}
The body has two required fields and three optional ones:
| field | what it is | |
|---|---|---|
model |
required | An id from GET /v2/models. |
input |
required | The model's own parameters. This is the one part of the envelope that differs per model, and it is checked at submit against the model's published input_schema: a field the schema does not name, a wrong type or a value outside its range is a 400 invalid_input and no job. See Model inputs. |
output |
optional | How many outputs to make (count) and in which format. See Several outputs. |
callback_url |
optional | An https URL we POST to when the job ends: succeeded, failed, expired or canceled. See Webhooks. |
prompt_enhance |
optional | How much work goes into your prompt before generation: "off", "basic" or "full". See Prompt enhancement. |
Several outputs
count (how many outputs, up to the model's max_output_count) and format (url). count is the only way to ask for more than one — a vendor's own n inside input is refused, because two numbers for one question is how you get billed for one render and charged for four. The same goes for a truthy enable_sequential (Wan 2.7's image-set mode, up to 12 images), refused with the same 400 invalid_input; enable_sequential: false is fine.
An image model also refuses a parameters object inside input (400 invalid_input, "input.parameters is not accepted on this model — send generator fields directly in input, and the number of outputs as output.count"): put the generator's fields straight in input, and the number of outputs in output.count. Those are refusals at submit.
If a generator nonetheless returns more result URLs than output.count, nothing is staged and nothing is charged, and the job stays running until it ends expired. An extra output that an option adds is not counted in count: on Seedance, return_last_frame: true adds the clip's closing frame (type image) as the output after the clip.
Callback
We POST a signed notification to this https URL when the job ends, whatever the status: succeeded, failed, expired or canceled, so a cancel you asked for and a job that expired are posted too, and a failed job carries its error. A delivery that fails is retried. Verification, headers and the retry schedule are on Webhooks. A failed, expired or canceled job that ended without a charge also appears in the console's Logs, as a free row.
Prompt enhancement
How much work goes into your prompt before generation:
"off"(default) sends it as written,"basic"has a fast language model rewrite it into the model's structured shot format, close to your own wording,"full"first has your attached pictures described, each for its role (a reference image as the subject to keep; a first, last or keyframe picture as that moment of the clip, a later one by what differs from the first frame), and your attached audio transcribed (reference audio, and your own soundtrack) by models that read them and writes a fuller, timed shot-by-shot prompt from those findings (reference videos are not analysed).
On a model that makes the sound together with the picture, both modes are also asked to write the sound: a soundscape for the scene, your quoted lines as dialogue, music only when you ask for it — except with your own soundtrack, which is the clip's whole audio: then the rewrite adds no sound or dialogue of its own.
Only on models that support it: their GET /v2/models entry lists the modes they take under prompt_enhance, and a model with no such field takes none, so any mode but "off" is a 400. The rewritten text is not returned. Prompt enhancement is free: nothing is added to the job's cost_usd. If the rewrite cannot be produced (or the prompt is longer than 4,000 characters), your original prompt is used.
The rewrite runs on a third-party model provider (Groq): your prompt leaves Sociaro, and in "full" so do those pictures and that audio, for analysis.
What goes in input for each family of models is on Model inputs.
Poll
GET /v2/jobs/{id}. While the job is unfinished the response carries retry_after (seconds), which
mirrors the Retry-After header — wait that long rather than polling in a tight loop.
{"id": "job_5cc8778b79574aaa7ea8fc09caec23e5",
"status": "succeeded",
"model": "alibaba/wan-2-7-image",
"media": "image",
"created_at": "2026-08-24T08:54:16.457268+00:00",
"completed_at": "2026-08-24T08:55:28.624694+00:00",
"retention_until": "2026-09-23T08:54:16.457268+00:00",
"cost_usd": 0.03,
"outputs": [{"url": "https://cdn.sociaro.com/v2/job_5cc8778b79574aaa7ea8fc09caec23e5/0-3f21c8ead6af7a981b5bf99fd705a745.png",
"type": "image",
"content_type": "image/png",
"expires_at": "2036-08-24T08:55:28.608057+00:00"}]}
status is one of queued, running, succeeded, failed, canceled, expired. The last four are
terminal — stop polling. A failed job's error is explained in Failed jobs.
The outputs[].url is a stable link on our CDN (https://cdn.sociaro.com/…). No key, no signature,
no deadline: fetch it with a plain GET, embed it, or store it — it keeps working after retention_until,
when the job record itself is gone. Results are kept for at least ten years (expires_at). The address is
unguessable and we only ever show it to the account that owns the job — but anyone who has the link can
fetch the file, so hand it out as you would the file itself. To delete an output, find its id with
GET /v2/files?job_id=<job id> and send DELETE /v2/files/{id} (Files); it then leaves outputs[].
If a url ever points at https://api.sociaro.com/v1/media/… instead (a deployment without the CDN
configured), that route needs an Authorization: Bearer header for any valid key of your account and
answers 404 without one. Read the host of the url you were given rather than assuming either form.
curl -L -o boat.png "https://cdn.sociaro.com/v2/job_5cc8778b79574aaa7ea8fc09caec23e5/0-3f21c8ead6af7a981b5bf99fd705a745.png"
Submitting the same request again with the same Idempotency-Key returns the finished job with its
outputs, so a lost response is never a lost result.
Cancel
POST /v2/jobs/{id}/cancel while a job is still cancellable. A job that already finished is returned
unchanged rather than treated as an error.
Limits
- Video jobs get up to 30 minutes to render, images 5 (
pruna/p-video-2-pro-replacegets 3 hours). Past a job'sdeadline_atit is abandoned and reported asexpired. - A job does not fail because one of our own checks on it was refused: it stays
runninguntil the generator finishes it (succeeded, charged) or its deadline passes (expired, not charged). A failure the generator itself reports still ends the jobfailedat once. output.countcannot exceed the model'smax_output_count; an extra output such as thereturn_last_frameframe is not counted.- Billing is identical to
/v1— same rates, same account, one charge per successful job, visible in the same usage figures. See Billing. MiniMax's H3 models have no/v1price to match: their rates are on each model's own page.