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 custom avatars trained from ~15 seconds of your video, and voices cloned in the app.
The frame itself — generate or edit the starting picture with Nano Banana in the exact shape of the ad (9:16, 4:5, 1:1, 16:9), then animate it, all with one key.
The soundtrack — a music bed and sound effects for each video, from a text description, so a pipeline ships finished ads instead of silent clips.

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}/

Building with an AI agent? The CraftStory MCP server wraps this API for Claude Desktop, Claude Code, Cursor and any other MCP client: install it with npx @craftstory/mcp and the agent creates avatars, starts generations and polls jobs without writing a single HTTP call.

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.

Images for your videos

The same key also makes the pictures a video starts from. POST /images/ takes a prompt and, optionally, up to 8 of your own pictures (files or URLs) to edit or to take a person, a product or a place from, and returns a PNG in the shape you ask for: 9:16, 16:9, 4:5, 1:1, 3:4 or 4:3. Two models: nano-banana (13 credits per image) and nano-banana-pro (25 credits; better with text in the picture, fine detail and several people). An image takes 10–25 seconds; a failed or rejected one is refunded.

# A 9:16 frame for a talking video curl -X POST -H "Authorization: Bearer $CRAFTSTORY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"prompt": "A woman in a bright kitchen holding a coffee mug, looking at the camera", "aspect_ratio": "9:16"}' \ https://api.craftstory.com/api/v1/images/ # Poll, then use image_url as the image of any video endpoint curl -H "Authorization: Bearer $CRAFTSTORY_API_KEY" \ https://api.craftstory.com/api/v1/images/{id}/

Step by step, with source pictures and failure reasons: curl walkthrough, Flow H.

Music and sound effects

The soundtrack around the voice comes from the same key. POST /music/ makes a track of 5–180 seconds from a description of genre, mood, instruments and tempo, instrumental by default (1 credit per second, 5 minimum). POST /sound-effects/ makes an effect or an ambience of 0.5–30 seconds, optionally as a seamless loop under a long video (1 credit per started 5 seconds, 2 minimum). Both return an MP3; a failed job is refunded. Prompts that name an artist or an existing song are declined with a suggested rewrite.

# A 30-second music bed curl -X POST -H "Authorization: Bearer $CRAFTSTORY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"prompt": "Upbeat lo-fi beat with soft piano for a product demo", "duration_s": 30}' \ https://api.craftstory.com/api/v1/music/ # A looping ambience curl -X POST -H "Authorization: Bearer $CRAFTSTORY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"prompt": "Quiet cafe, cups and soft chatter", "duration_s": 20, "loop": true}' \ https://api.craftstory.com/api/v1/sound-effects/

Poll /music/{id}/status/ or /sound-effects/{id}/status/, then read audio_url. Walkthrough: Flow I (music) · Flow J (sound effects).

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 avatars and cloned voices, generate or edit the starting image with Nano Banana in any of six aspect ratios, make music tracks and sound effects for the soundtrack, 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. For AI agents there is also the CraftStory MCP server (npx @craftstory/mcp).

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.