Sociaro

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.