# Stork API

Talking video and voice over one REST API, paid from prepaid credits by the minute or second. No subscription. HTML: https://www.stork.ai/developers

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).

## APIs

- [Talking Photo API](https://www.stork.ai/developers/talking-photo-api.md): one photo plus text or audio in, a lip-synced MP4 out. From $0.10 a minute; free watermarked tier.
- [Speech API](https://www.stork.ai/developers/speech-api.md): text in, an MP3 out. $0.05 a minute; free tier.
- [Singing Video API](https://www.stork.ai/developers/singing-video-api.md): one photo plus a song in, a performance video out. $12.00 a minute, billed by the second.

## Node library

`npm install storkai`, then `import { Stork } from "storkai"` and `new Stork()` with `STORK_API_KEY` set. Each API is a resource (`talkingPhoto`, `speech`, `singingVideo`) with `create`, `get`, `list`, `estimate`, `wait` and `createAndWait`. Reference: https://www.npmjs.com/package/storkai

## Python library

`pip install storkai`, then `from storkai import Stork` and `Stork()` with `STORK_API_KEY` set. Resources are `talking_photo`, `speech` and `singing_video`, each with `create`, `get`, `list`, `estimate`, `wait` and `create_and_wait`; results are dicts. No dependencies, Python 3.8+. Reference: https://pypi.org/project/storkai/

## n8n

Community node `n8n-nodes-storkai`: Talking Photo, Speech and Singing Video, each with Create (waits for the file by default), Estimate, Get and Get Many. Install in a self-hosted n8n under Settings > Community Nodes. Source: https://github.com/jupiterspins/n8n-nodes-storkai

## Machine-readable

- OpenAPI 3.1: https://api.stork.ai/api/v1/openapi.json
- API index (JSON): https://api.stork.ai/
- MCP server: https://mcp.stork.ai/mcp (official MCP registry name: ai.stork/mcp)
- Changelog: https://www.stork.ai/developers/changelog

## 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.
