Sociaro Leda

Request headers

Response header Retry-After: 5 comes with GET /v2/jobs/{id} while the job is queued or running, and with 429 too_many_inflight_jobs: wait that many seconds before the next request.

Request body

POST /v2/jobs takes a JSON object. It is closed: an unknown top-level field returns 400 invalid_input.

Input fields

• input is closed: any field not listed above returns 400 invalid_input.
• Use the flat fields (prompt and the media fields) or content, not both. Mixing them returns 400.
• A prompt alone works (text only), with a named ratio.
• Deprecated synonyms, still accepted with the same values: enhance for upscale, and extra.prompt_expansion_mode for prompt_enhance. If both names are sent, they must agree; otherwise the request returns 400.
• Media URLs (references, frames, keyframes, soundtrack): https, a public host with an ASCII hostname, port 443 or none, no user name or password, no #fragment, no backslash or control characters, up to 8192 characters each.

• With a prompt of up to 400 bytes. Leda Pro counts each reference image at its own size and each reference video at its own length. Anything past the table returns 400 invalid_input when the job is created.
• When a request fits only at the real sizes, we read each file's header as the job is created. A reference we cannot read there (another format, a fragmented MP4, a URL that redirects or does not answer in time) makes the request a 400, and no job is created.
• A video longer than the clip is cut to it. One reference image alone always fits. First, last and keyframe images are not references: they count at a smaller size, and every combination of them fits at every length on Leda Pro.

Frames, keyframes, soundtrack

Every Leda model: Leda Lite, Leda and Leda Pro. 768P and 2K (and 480P on Leda Lite), 4 to 15 s, as everywhere.

• Frames: frame is a frame of the output at 24 fps, from 0. A clip has N frames: 124 at 4 and 5 s, 158 at 6 s, 175 at 7 s, 192 at 8 s, 226 at 9 s, 243 at 10 s, 277 at 11 s, 294 at 12 s, 328 at 13 s, 345 at 14 s, 362 at 15 s. A negative frame counts from the end: -1 is the last.
• Keyframes: without reference images a keyframe sits on 1 to N‑2, since the first and last frames belong to the first and last frame images. Beside reference images it may sit on 0 to N‑1. One keyframe per frame: 62 and -62 are the same frame of a 5 s clip. A JSON integer only: 62.0 is rejected.
• Images: at most 9 in all, first and last frame plus keyframes, or reference images plus keyframes. At most one first frame, one last frame and one soundtrack.
• Soundtrack: MP3 or WAV, 2 to 15 s, up to 15 MiB. A longer track is cut to the clip, a shorter one ends in silence. The track is checked after the job is accepted: a track outside these limits ends the job failed (error.code provider_failed, provider_code invalid_input), not charged.
• Long clips: frame and keyframe images share the length limit with the prompt. With a prompt of up to 400 bytes, all 9 fit at every length on every model.

Job object

Returned by GET /v2/jobs/{id}, by a create retry with the same Idempotency-Key, and sent to callback_url. A field without a value is omitted, never null. The job object does not echo the input: no prompt, references, seed, resolution or duration.

Errors

Errors return a JSON body {"error": {"code": "...", "message": "..."}}. Branch on code; message is for people and names the exact problem.

Examples

# poll every Retry-After seconds until final
curl https://api.sociaro.com/v2/jobs/$JOB_ID \
  -H "Authorization: Bearer $SOCIARO_API_KEY"

# 200: a finished Leda Lite job, duration 4, 768P, 16:9
{
  "id": "job_0123456789abcdef0123456789abcdef",
  "status": "succeeded",
  "model": "sociaro/leda-lite",
  "media": "video",
  "created_at": "2026-10-30T10:05:04.110366+00:00",
  "deadline_at": "2026-10-30T10:53:04.110366+00:00",
  "retention_until": "2026-11-29T10:05:04.110366+00:00",
  "completed_at": "2026-10-30T10:06:20.033665+00:00",
  "cost_usd": 0.08,
  "outputs": [{
    "url": "https://cdn.sociaro.com/v2/job_0123.../0-....mp4",
    "type": "video",
    "content_type": "video/mp4",
    "expires_at": "2036-10-30T10:06:20.021745+00:00",
    "width": 1344,
    "height": 768,
    "duration_sec": 5.166666666666667
  }]
}

# Python 3 with requests: create a job, then poll it
import os, time, uuid
import requests

API = "https://api.sociaro.com/v2/jobs"
KEY = os.environ["SOCIARO_API_KEY"]
AUTH = {"Authorization": f"Bearer {KEY}"}

body = {
    "model": "sociaro/leda-lite",
    "input": {
        "prompt": "The woman in the reference picture "
                  "turns toward the window and smiles.",
        "reference_image_urls": [
            "https://your-cdn.example.com/reference.png"],
        "duration": 10,
        "resolution": "768P",
        "ratio": "16:9",
    },
}

# keep this key if you retry the POST: no duplicate job
idem = str(uuid.uuid4())
r = requests.post(API, json=body, timeout=30,
    headers={**AUTH, "Idempotency-Key": idem})
r.raise_for_status()
job = r.json()

# poll until the status is final
while job["status"] in ("queued", "running"):
    time.sleep(int(r.headers.get("Retry-After", 5)))
    r = requests.get(f"{API}/{job['id']}", headers=AUTH,
                     timeout=30)
    r.raise_for_status()
    job = r.json()

if job["status"] == "succeeded":
    print(job["outputs"][0]["url"], job["cost_usd"])
else:
    print(job["status"], job["error"]["code"])