# Stork Singing Video API

One photo plus a song in, a performance video out: the person sings it, filmed from several camera angles and lip-synced. HTML docs: https://www.stork.ai/developers/singing-video-api

All requests: `Authorization: Bearer sk_stork_...`. Create a key at https://www.stork.ai/dashboard/api. One key and one credit balance cover every API. 1 credit = 1 cent; packs start at $2.00 and never expire (https://www.stork.ai/credits).

## Create: POST /singing-video

| Field | Required | Meaning |
| --- | --- | --- |
| `image_url` | yes | Public https URL of a JPG, PNG or WebP with one clear face, up to 12 MB |
| `audio_url` | yes | Public https URL of the song (MP3, WAV, M4A, OGG, WebM), at least 15 s, up to 100 MB |
| `seconds` | no | Length of video to make, from the start of the song, 15 to 330. Default: the whole song |
| `webhook_url` | no | https URL for the signed result |

```bash
curl -X POST https://api.stork.ai/api/v1/singing-video \
  -H "Authorization: Bearer sk_stork_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"image_url": "https://www.stork.ai/samples/talking-photo/portrait.jpg", "audio_url": "https://example.com/my-song.mp3", "seconds": 15}'
```

Returns 202: `{ id, object: "singing_video", status: "queued", seconds, audio_seconds, credits_held, balance_credits, status_url }`.

## Read: GET /singing-video?id=<id> | GET /singing-video?limit=20

`status` is `queued`, `running`, `succeeded` or `failed`. On success: `video_url` (MP4, H.264 + AAC), `duration_seconds`, `credits_charged`. This render is slow: a 15-second video takes about 8 minutes, a three-minute one about half an hour. Poll once a minute, or use a webhook.

## Estimate: POST /singing-video/estimate

Body: `{ "seconds": 120 }`. Returns `credits`, `usd`, `balance_credits`, `affordable`.

## Pricing

20 credits per second of delivered video ($12.00 a minute). No free tier. The price of the length ordered is held; you are charged for the length delivered.

## Limits

- 2 singing videos in the making at once per account (429 `too_many_in_flight`).
- Rendering capacity is shared: when it is full, create returns 429 `renderer_busy` and charges nothing. Retry in 10 minutes or order a shorter video.
- A video can be accepted and fail later; its `error` then starts with `capacity_reached`, `render_unavailable` or `render_failed`, and nothing is charged.

## Errors

- 400 `invalid_request`, `invalid_seconds`, `invalid_webhook_url`, `audio_too_short`, `image_fetch_failed`, `audio_fetch_failed`, `image_not_an_image`, `audio_not_audio`, `audio_unreadable`
- 401 `missing_api_key`, `invalid_api_key`
- 402 `insufficient_credits`
- 404 `not_found`
- 409 `idempotency_key_reused`, `request_in_progress`
- 413 `image_too_large`, `audio_too_large`
- 429 `too_many_in_flight`, `renderer_busy`
- 503 `singing_video_unavailable`, `probe_unavailable`

## Webhooks

Pass `webhook_url` (https) on create. We POST once when the job reaches a final state. Answer 2xx; otherwise we retry after 1 min, 5 min, 30 min, 2 h and 6 h. `Stork-Webhook-Id` is the same on every retry.

Body: `{ "id": "evt_...", "type": "<object>.<status>", "created_at": "...", "data": { ...same object as GET... } }`

Verify the `Stork-Signature: t=<unix>,v1=<hex>` header: `v1` is HMAC-SHA256, hex, of the string `<t>.<raw body>` keyed with your signing secret (`whsec_...`, shown at https://www.stork.ai/dashboard/api). Reject when `t` is more than 300 seconds old.

```js
import crypto from "node:crypto";
export function verifyStork(raw, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
  const expected = Buffer.from(crypto.createHmac("sha256", secret).update(`${t}.${raw}`).digest("hex"));
  const given = Buffer.from(parts.v1 ?? "");
  return given.length === expected.length && crypto.timingSafeEqual(expected, given);
}
```

Event types: `singing_video.succeeded`, `singing_video.failed`. A video that times out without a report from the renderer sends no webhook: poll as a fallback.

## Conventions

- Base URL: `https://api.stork.ai/api/v1`. OpenAPI 3.1: https://api.stork.ai/api/v1/openapi.json
- Jobs are asynchronous: create returns 202 with an `id`; poll `GET ?id=` or use a webhook.
- Node library: `npm install storkai`, then `import { Stork } from "storkai"`. It wraps every call here (`create`, `get`, `list`, `estimate`, `wait`, `createAndWait`) and verifies webhooks. Reference: https://www.npmjs.com/package/storkai
- Python library: `pip install storkai`, then `from storkai import Stork`. Same calls in snake_case (`create_and_wait`). Reference: https://pypi.org/project/storkai/
- `Idempotency-Key` header on create (any unique string, kept 24 h): a retry with the same key and body returns the first response with `Idempotent-Replayed: true` and creates nothing. Same key, different body: 409 `idempotency_key_reused`.
- Errors: `{ "error": { "code", "message", "param", "request_id", "doc_url" } }`. Every response carries `Stork-Request-Id`. 429 and 503 carry `Retry-After`.
- Money: the price is held when the job is created, you are charged for what is delivered, and a failed job returns every credit.

## MCP

The same calls as tools on `https://mcp.stork.ai/mcp`: `stork_singing_video_create`, `stork_singing_video_status`, `stork_singing_video_estimate`.
