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. The Kling image models (kling/kling-v3,
kling/kling-v3-omni, kling/kling-4.0-image) on /v1/kling/generations deliver the same way, media_urls with
media_url first, and charge per image delivered, never more than the n (or, for a series, the
series_amount) you asked for. 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/byteplus/...— ByteDance models/v1/ideogram/generations— Ideogram image and vector (SVG) models, sent with Ideogram's own request body; also on/v2/jobs/v1/kling/generations— Kling video and image models, sent with Kling's own request body/v1/pixverse/generations— PixVerse video models/v1/pruna/generations— Pruna image and video models, sent with Pruna's own request body; also on/v2/jobs/v1/recraft/generations— Recraft image and vector (SVG) models and image tools (vectorize, remove background, upscale), sent with Recraft's own request body; also on/v2/jobs/v1/sonilo/generations— music and sound effects for a finished video/v2/jobs— MiniMax's H3 video models, served only through the Jobs API
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 (on
Ideogram the gateway fetches them and refuses one it cannot read with a 400). A URL behind a login
or a firewall will fail — the fetching is not done by 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.
A vector model's result (Ideogram's and Recraft's) is an SVG file (image/svg+xml). A /v1 link serves it with a
sandboxing Content-Security-Policy; a /v2 link downloads when opened directly in a browser and still works as
<img src>.
When it fails
A failed job costs nothing and still appears in your Logs, with the reason. The one exception is an
Ideogram job whose images were all withheld by the generator's safety check: it is billed for the
images produced. On /v1/recraft/generations the generator sees the request only after the submit is accepted, so
a request it refuses, a busy generator and a generator that failed all show up as the job's failed status at the
poll, with the generator's own words, and cost nothing. Showing every failure is deliberate: a
generation that silently vanished would leave you unable to tell a refusal from a bug in your own
code.