POST /v1/videos

Long-running video generation. Send a prompt (and optional first/last frame), receive an asset URL when the job lands.

FIG.

FIG. 00 · POST /V1/VIDEOSPROMPT → CLIP

/v1/videos runs the slowest workloads in the catalog — text-to-video and image-to-video models like klingai/kling-2.1, bytedance/seedance-1.0-pro, google/veo-3. Connections can stay open up to 10 minutes. Use the AI SDK's streamText family for typed model calls, or hit this route directly when you need raw control.

FIG. 01LONG-RUNNING JOB

SCHEMATIC

Video models commonly take 30 s – 5 min per request. The route holds the connection until the upstream returns a final asset URL. Use `x-mg-idempotency-key` on every call so a network hiccup doesn't double-bill — replays return the original asset for 24 h.

Request

curl https://synapse.garden/api/v1/videos \
  -H "Authorization: Bearer $MG_KEY" \
  -H "Content-Type: application/json" \
  -H "x-mg-idempotency-key: 01J9Z9Z9Z9Z9Z9Z9Z9Z9Z9Z9" \
  -d '{
    "model": "klingai/kling-2.1",
    "prompt": "A koi swimming through morning mist, slow tracking shot",
    "aspect_ratio": "16:9",
    "duration": 5
  }'

Body schema

Field	Type	Required	Notes
`model`	string	yes	`provider/model-id`.
`prompt`	string	yes	1–8 000 chars.
`image_url`	string (URL)	no	Image-to-video seed. HTTPS required.
`last_frame_url`	string (URL)	no	Final-frame target for supported models (`klingai/*` interpolation).
`aspect_ratio`	enum	no	`16:9` \| `9:16` \| `1:1` \| `4:3` \| `3:4` \| `21:9`.
`duration`	number	no	Seconds. 1–60. Provider-clamped to its supported range.
`user`	string	no	Caller-defined identifier. Max 256 chars.
`providerOptions`	object	no	Provider-namespaced overrides.

Headers

Authorization: Bearer mg_live_* — required.
x-mg-idempotency-key: <ulid> — strongly recommended. Video calls are expensive and non-deterministic; replays within 24 h return the original asset.
x-mg-trace-id: <id> — optional caller trace id for OTEL correlation.

Response

{
  "id": "vid_01J9Z...",
  "created": 1778430000,
  "model": "klingai/kling-2.1",
  "data": [
    {
      "url": "https://assets.synapse.garden/v/01J9Z...?sig=...",
      "expires_at": 1778516400,
      "duration": 5,
      "size": "1280x720"
    }
  ],
  "usage": { "input_tokens": 22, "output_seconds": 5 }
}

Field	Type	Notes
`data[].url`	string	Signed URL; defaults to ~24 h validity. Re-fetch the response with the same idempotency key to refresh.
`data[].expires_at`	integer	Unix seconds.
`data[].duration`	number	Final clip length (may differ from requested if the model clamps).
`data[].size`	string	Final dimensions.
`usage.input_tokens`	integer	Tokens consumed by the prompt.
`usage.output_seconds`	integer	Seconds of video returned (used for billing).

Errors

Standard /v1/* envelope. Common codes:

Status	`error.code`	When
400	`BAD_REQUEST`	Unsupported aspect ratio, `duration` out of range, `image_url` not HTTPS, etc.
402	`BUDGET_EXCEEDED`	Spend cap reached — video models are the most expensive in the catalog.
403	`MODEL_NOT_ALLOWED`	Model not on the project's allowlist.
504	`UPSTREAM_TIMEOUT`	Provider didn't finish inside 10 min. Retry with the same idempotency key.

Limits

8 000-char prompt.
duration ≤ 60 s (most models cap at 5–10 s).
Connection held up to 600 s. Set an x-mg-idempotency-key so transient drops don't cost you twice.
One video model can serve only one job per account at a time on most providers — calls beyond that return 429.