The API is plain REST with an OpenAPI 3 schema at api.craftstory.com/api/v1/docs/public/swagger.json — generate a typed client for any language, or point an AI coding agent at the schema and the curl walkthrough.

CraftStory API

Generate hyper-realistic AI avatar videos programmatically. One photo or a custom avatar plus a script or audio — the REST API returns a finished talking video with natural lip-sync and gestures, up to 30 minutes long, in 30+ languages. Built by the team behind OpenCV.

Plain REST + OpenAPI schema — works with any language and any AI coding agent

Read the API docs Get your API key

What you can build

UGC ads at scale — generate dozens of hook variants with the same presenter for TikTok, Reels and YouTube Shorts, straight from your ad pipeline.
Personalized video outreach — render a talking video per lead or per customer from a template script.
Products and agents that speak — give your app, workflow or AI agent the ability to produce talking-head video: the API is self-describing via OpenAPI, so coding agents integrate it in minutes.
Custom avatars and voices — list and use LoRA avatars trained from ~15 seconds of video, and voices cloned in the app.

Quickstart

Authentication is a Bearer API key (sk-cs-...), created in the app under Profile → API. Base URL: https://api.craftstory.com/api/v1/

# 1. List avatars (yours + library) curl -H "Authorization: Bearer $CRAFTSTORY_API_KEY" \ https://api.craftstory.com/api/v1/image2video/avatars/ # 2. Start a video generation curl -X POST -H "Authorization: Bearer $CRAFTSTORY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"text": "Hello from the CraftStory API!", "voice_id": "...", "lora_avatar_id": "..."}' \ https://api.craftstory.com/api/v1/image2video/ # 3. Poll status and download the MP4 curl -H "Authorization: Bearer $CRAFTSTORY_API_KEY" \ https://api.craftstory.com/api/v1/image2video/{id}/

Full request/response shapes for every endpoint: step-by-step curl walkthrough · API reference (ReDoc) · OpenAPI schema

Python and JavaScript

Same three calls, if curl is not your language. Polling is the whole client — generation is asynchronous and a long video takes minutes, so there is no streaming endpoint to get wrong.

# Python import os, time, requests API = "https://api.craftstory.com/api/v1" HEAD = {"Authorization": f"Bearer {os.environ['CRAFTSTORY_API_KEY']}"} job = requests.post(f"{API}/image2video/", headers=HEAD, json={ "text": "Hello from the CraftStory API!", "voice_id": "...", "lora_avatar_id": "...", }).json() while True: job = requests.get(f"{API}/image2video/{job['id']}/", headers=HEAD).json() if job["status"] in ("done", "failed_video", "no_face_detected_video"): break time.sleep(15) print(job["status"], job.get("video"))

// JavaScript (Node 18+, no dependencies) const API = "https://api.craftstory.com/api/v1"; const head = { Authorization: `Bearer ${process.env.CRAFTSTORY_API_KEY}`, "Content-Type": "application/json", }; let job = await (await fetch(`${API}/image2video/`, { method: "POST", headers: head, body: JSON.stringify({ text: "Hello from the CraftStory API!", voice_id: "...", lora_avatar_id: "...", }), })).json(); while (!["done", "failed_video", "no_face_detected_video"].includes(job.status)) { await new Promise(r => setTimeout(r, 15000)); job = await (await fetch(`${API}/image2video/${job.id}/`, { headers: head })).json(); } console.log(job.status, job.video);

What a video costs through the API

There is no separate API contract and no per-seat fee. Generation spends the same credits as the app: roughly 3 credits per second of 720p video. That makes the price per finished minute easy to work out in advance.

Where the credits come from	Per credit	Per minute of 720p
Producer plan — $34/mo, 2,400 credits	$0.014	$2.55
Indie plan — $19/mo, 900 credits	$0.021	$3.80
Top-up pack — $50 / 3,000 credits	$0.017	$3.00
Top-up pack — $25 / 1,000 credits	$0.025	$4.50

Packs stack on top of a plan, so a burst month does not force an upgrade. A free plan exists for trying the API before any of this — see pricing.

Statuses and failure modes

Poll GET /image2video/{id}/ and branch on status. Worth handling explicitly: a bad input photo fails after the job is queued, not at submit time, and it still costs the wait.

status	What it means
`in_progress`	Queued or generating. Poll every 10–30 seconds; long videos take minutes.
`done`	Finished. `video` holds the MP4 URL.
`no_face_detected_video`	No usable face in the source. The most common failure by far — check the photo before submitting.
`no_person_detected_image`	No person found in the image at all.
`multiple_people_detected_image`	More than one face; pick a single-subject photo.
`failed_video`	Generation failed. Safe to retry once before escalating.

Why CraftStory instead of a generic video API

Most video-generation APIs cap talking-head clips at 30–60 seconds and lose the face over time. CraftStory keeps the same identity across the whole video — up to 30 minutes — and supports custom avatars of real people (with consent) trained from a short phone video. Pricing is credit-based on your existing plan; there is no separate API contract, and a free plan to try.

FAQ

Frequently asked questions

How do I get a CraftStory API key?

API access is included in paid CraftStory plans. Sign in to app.craftstory.com, open Profile → API and create a key (format sk-cs-...). Use it as a Bearer token in the Authorization header.

What can the CraftStory API do?

Everything the app does: turn a photo or an AI actor into a hyper-realistic talking video from a script or audio (up to 30 minutes), list and use your custom LoRA avatars and cloned voices, poll job status and download finished MP4s.

Is there an SDK?

The API is plain REST with an OpenAPI 3 schema — generate a typed client for any language, or point an AI coding agent at the schema and the curl walkthrough.

Does API usage cost extra?

No separate API pricing: API-generated videos use the same credits as videos made in the app, on your existing subscription.