Images and video

Generation takes longer than a request should wait, so media works in three moves: submit, then poll, then collect.

Submitting

curl https://api.sociaro.com/v1/alibaba/generations \
  -H "Authorization: Bearer $SOCIARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "alibaba/wan-3-video",
        "prompt": "a paper boat drifting down a rain-soaked street",
        "resolution": "720p",
        "duration": 8
      }'

{"job_id": "cgt-20260816024141-rhl5n", "status": "submitted"}

Polling

curl https://api.sociaro.com/v1/alibaba/generations/cgt-20260816024141-rhl5n \
  -H "Authorization: Bearer $SOCIARO_API_KEY"

status moves through submitted and processing to completed — with the result's URL — or failed, with a reason. Poll every few seconds; a video can take minutes.

On /v1/alibaba/generations, an image model that makes more than one picture (n greater than 1) returns all of them: media_urls lists every image in the order the generator made them, and media_url is the first. Each link expires on its own terms, exactly like a single media_url. The charge is the number of images the generator reports making, and it never exceeds the links you are given: if the generator lists more links than that, you get them all and pay for its count. If any one of the images cannot be delivered the whole job is failed and nothing is charged — you are never billed for a picture you were not given a link to. Models on the other doors keep the result shape their own page describes.

Which door

Media models are served on the door matching their family, and each model's page names its own:

• /v1/alibaba/generations — models we serve direct from our own Alibaba workspace
• /v1/spicy/generations — the spicy family
• /v1/byteplus/... — ByteDance models

The catalogue states the door for every model. Sending a model to the wrong door is refused rather than guessed at.

Sending images and video in

Models that take input media accept public https URLs, which the vendor fetches itself. A URL behind a login or a firewall will fail — the vendor is doing the fetching, not your browser.

Field names vary by what the model does: a first frame, a last frame, reference images. Every model's page lists exactly what it accepts.

Results

The URL you get back is ours, not the vendor's, and it checks that the job is yours before serving the file. Download what you need — links do not live forever.

When it fails

A failed job costs nothing and still appears in your Logs, with the reason. That is deliberate: a generation that silently vanished would leave you unable to tell a refusal from a bug in your own code.