Autoclips API

The Autoclips API lets your own code, automation tools (Zapier, Make, n8n) and AI apps (Claude, ChatGPT) do what the Autoclips app does: create videos, change them and check on them.

1. 1Create an API key in the app: Settings → API. Pick what it may do. The key is shown once, so copy it then.
2. 2Keep the key out of your code. Put it in an environment variable, for example AUTOCLIPS_API_KEY.
3. 3Check the key works with the call below. It answers with your account and what the key may do.
4. 4Before you create anything, read the choices for your product with GET /api/v1/options (it needs the read permission), so you only send values that exist.

export AUTOCLIPS_API_KEY="ac_live_..."

curl 'https://app.autoclips.app/api/v1/me' \
  -H "Authorization: Bearer $AUTOCLIPS_API_KEY"

Requests and answers

• Every address starts with https://app.autoclips.app/api/v1. Send bodies as JSON with Content-Type: application/json.
• A success answers { "data": ... }, sometimes with meta. An error answers { "error": { "code", "message", "details", "docs_url" } }.
• Every answer has an X-Request-Id header. Mention it if you contact us about a request.
• Paged lists (such as GET /api/v1/credits/history) answer items, next_cursor and has_more. Send cursor (the last next_cursor) for the next page and limit (1–100, default 20; at most 50 for GET /api/v1/ce/projects) for the page size. Other lists (such as GET /api/v1/voices) answer with their own fields, shown with each operation.

{
  "data": {
    "userId": "5dc8655f-0000-4000-8000-000000000000",
    "email": "you@example.com"
  }
}

{
  "error": {
    "code": "not_found",
    "message": "Not found.",
    "docs_url": "https://app.autoclips.app/developers#error-not_found"
  }
}

The whole API is also described as OpenAPI 3.1 (add ?product=v3 for one product, or ?operation=<operation id> for one operation with a request that works), and summarised for AI tools in llms.txt.

The quickest way is to ask an AI app that is connected to Autoclips (set it up under AI apps (MCP)). For example: "Make a 60 second video about how volcanoes form, with a British narrator." The AI picks the tool and waits for your yes before anything is charged. It shows you the price, or, for a video charged step by step as it is made, a spending limit and the expected price (create_video shows an estimate). V3 Quick Create's and Character Explainer Quick Create's spending limits are the most each can charge. Autopilot stops before a step that would go past its spending limit, but one step's final cost can run a little over. It tells you when the video is ready.

Tools that make a video

Follow a create_video or create_character_video video with get_video_status and post it with publish_video. Follow the others with autoclips_jobs → get. All the original AI tools are listed under AI apps (MCP).

With the API, in one call

1. 1Read the choices with GET /api/v1/options and product=v3, or leave settings out for the defaults.
2. 2Ask for the spending limit: send "operation": "v3.projects.quick_create" and your input to POST /api/v1/quotes. You get the most it can charge (the run is charged step by step, usually less), the expected price in its notes, and a quote_token. Nothing is charged.
3. 3Start it with POST /api/v1/v3/projects/quick: the same input, the quote_token (or max_credits, at least the limit) and an Idempotency-Key header. It answers 202 with a job and the project.
4. 4Ask GET /api/v1/jobs/{jobId} again after poll_after_seconds, until status is final: at succeeded, result.videoUrl is your video; failed and canceled say why in error. A job that carries stalled has shown no progress for much longer than usual and may have stopped: tell the user instead of waiting. One that failed with the code stalled did stop: read the project to see where it got to and what can be done next.

# 1. The spending limit
curl -X POST 'https://app.autoclips.app/api/v1/quotes' \
  -H "Authorization: Bearer $AUTOCLIPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "operation": "v3.projects.quick_create",
  "input": {
    "topic": "The lighthouse keeper who vanished in 1900",
    "category": "mythology",
    "recipe": "quick"
  }
}'

# 2. Start it
curl -X POST 'https://app.autoclips.app/api/v1/v3/projects/quick' \
  -H "Authorization: Bearer $AUTOCLIPS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "topic": "The lighthouse keeper who vanished in 1900",
  "category": "mythology",
  "recipe": "quick",
  "quote_token": "<quote_token from step 1>"
}'

# 3. Check on it until status is "succeeded" (or "failed" or "canceled", which say why)
curl 'https://app.autoclips.app/api/v1/jobs/<job.id from step 2>' \
  -H "Authorization: Bearer $AUTOCLIPS_API_KEY"

Autoclips V3, step by step

To look at and change each part before paying for the next, make the video one step at a time. Each paid step shows its price first.

1. 1Make a free draft with its settings. POST /api/v1/v3/projects (AI apps: v3_projects → create)
2. 2Write the script. POST /api/v1/v3/projects/{projectId}/script/generate (AI apps: v3_script → generate)
3. 3Change scenes and words, free. PATCH /api/v1/v3/projects/{projectId}/script (AI apps: v3_script → edit)
4. 4Make the pictures, voice and music. The price follows how long the written script really runs, and it already covers the render. POST /api/v1/v3/projects/{projectId}/assets/generate (AI apps: v3_production → generate_assets)
5. 5Build the edit. POST /api/v1/v3/projects/{projectId}/timeline/build (AI apps: v3_production → build_timeline)
6. 6Render the video (no extra charge: it was paid for with the pictures). POST /api/v1/v3/projects/{projectId}/render (AI apps: v3_production → render)

Character Explainer, step by step

Step by step, you read and change the script and each scene before anything is charged. Only the pictures (optional) and the render cost credits; each shows its price first, and long steps answer with a job you follow the same way.

1. 1Make a free draft with its topic (or, on a paid plan, your own script), characters and settings. POST /api/v1/ce/projects (AI apps: ce_projects → create)
2. 2Write the script, free. It answers with a job. POST /api/v1/ce/projects/{projectId}/script (AI apps: ce_script → generate)
3. 3Optional: change a scene's words, speaker or picture idea, free. PATCH /api/v1/ce/projects/{projectId}/scenes/{sceneNumber} (AI apps: ce_scenes → update)
4. 4Optional, on a paid plan, for a gameplay video: make pictures for the scenes. Each picture is charged when it is made, and one that fails is given back. POST /api/v1/ce/projects/{projectId}/pictures (AI apps: ce_scenes → generate_pictures)
5. 5Optional, for a gameplay video: add sound effects to the scenes, free. POST /api/v1/ce/projects/{projectId}/sound-effects/suggest (AI apps: ce_scenes → suggest_sound_effects)
6. 6Render the video. The API cannot stop a started video; if it fails, its credits come back. POST /api/v1/ce/projects/{projectId}/render (AI apps: ce_render → start)

3D Animated Studio, step by step

Or skip all of this with Autopilot (above). Step by step, you see and change each part before the next is made; each paid step shows its price first, and long steps answer with a job you follow the same way.

1. 1Make a project from your idea and its settings, free. POST /api/v1/studio/projects (AI apps: studio_projects → create)
2. 2Optional: turn the idea into a fuller brief. POST /api/v1/studio/projects/{projectId}/brief (AI apps: studio_ideas → write_brief)
3. 3Write the script. POST /api/v1/studio/projects/{projectId}/script/generate (AI apps: studio_script → generate)
4. 4Change lines, speakers and characters, free. PATCH /api/v1/studio/projects/{projectId}/script (AI apps: studio_script → edit)
5. 5Draw the character sheets. POST /api/v1/studio/projects/{projectId}/sheets (AI apps: studio_looks → make_sheets)
6. 6Draw the places and objects. POST /api/v1/studio/projects/{projectId}/pictures (AI apps: studio_looks → make_pictures)
7. 7Plan every clip. POST /api/v1/studio/projects/{projectId}/clips/prepare (AI apps: studio_clips → prepare)
8. 8Make every clip and join them into the film, on our servers. POST /api/v1/studio/projects/{projectId}/render (AI apps: studio_clips → render_all)
9. 9Optional: read what the free check for mistakes flagged in each clip (every join starts it). GET /api/v1/studio/projects/{projectId}/review (AI apps: studio_review → get)
10. 10Optional: fix a flagged moment for the price of a few seconds of video, then join the film again (free). POST /api/v1/studio/projects/{projectId}/review/fixes (AI apps: studio_review → fix)
11. 11Optional: finish it with a watermark, an end card or a soundtrack. POST /api/v1/studio/projects/{projectId}/watermark (AI apps: studio_finish → watermark)

Send your key in the Authorization header as Bearer <key>, or in an x-api-key header. Never put a key in a link or a query string: links end up in logs.

Permissions (scopes)

• A key without the permission an operation needs gets 403 insufficient_scope. Permissions do not include each other: spend does not include edit.
• Anything that is not on your account answers 404 not_found, exactly like something that does not exist, so ids cannot be guessed.
• Revoking a key stops it on the very next request. Rotating gives a new secret with the same name, permissions and cap.
• Keys can only be made or changed from the signed-in app, never with a key, so a leaked key cannot make more keys.

Nothing costs credits without a clear yes. Every price is worked out on our side, never taken from the request, and it is an upper bound: you are never charged more than the quote. The original create_video AI tool is an exception: it shows an estimate for the length asked, and the final price follows how long the written script really runs, so it can cost more. Autopilot is also an exception: it stops before a step that would go past its spending limit, but one step's final cost can run a little over. A quote to raise a spending limit is also an exception: it is only how much the limit grows, not what the run is charged.

Approving a paid request

1. 1Send max_credits in the body: for a price, the most you accept; for a spending limit, the highest limit you accept; to raise a spending limit, the most you accept to add. If the request asks for more, nothing runs and you get 402 quote_exceeds_max_credits with what it asks for.
2. 2Or get a quote first with POST /api/v1/quotes: send the operation id and the exact input, and you get what it asks you to approve and a quote_token. Send the same request with that quote_token within 10 minutes. It works once; any change to the input needs a new quote.
3. 3Send neither and nothing runs: you get 402 confirmation_required with what it asks you to approve and a quote_token you can send back.

A video charged step by step as it is made (v3.projects.quick_create, ce.projects.quick_create, studio.autopilot.start) asks you to approve a spending limit instead of a price. Its quote also gives the expected price, and it is charged as the work runs, usually less. V3 Quick Create's and Character Explainer Quick Create's spending limits are the most each can charge. Autopilot stops before a step that would go past its spending limit, but one step's final cost can run a little over. Over REST, max_credits must cover the limit.

A paid answer says in meta what it did with your credits: creditsCharged is what this request charged, and creditsApproved is what you approved for work that is charged as it runs (not a charge yet).

curl -X POST 'https://app.autoclips.app/api/v1/quotes' \
  -H "Authorization: Bearer $AUTOCLIPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "operation": "v3.projects.quick_create",
  "input": {
    "topic": "The lighthouse keeper who vanished in 1900",
    "category": "mythology",
    "recipe": "quick"
  }
}'

Idempotency-Key: a retry never charges twice

• Every request that costs credits needs an Idempotency-Key header: a fresh random value (a UUID) for each new request. So do the free requests marked as needing one: POST /api/v1/v3/projects, POST /api/v1/ce/projects, POST /api/v1/studio/projects and 8 more. Each operation says so under its fields.
• Sending the same key again within 24 hours gives back the first answer, with the Idempotent-Replayed: true header and meta.idempotentReplay: true. Nothing runs or is charged twice. On a paid request, its meta.creditsCharged is 0 and meta.originallyCharged is what the first request charged (for work charged as it runs, creditsApproved is 0 and originallyApproved is what the first request approved).
• The same key with a different body gets 409 idempotency_key_reused. A request that failed without a charge can be retried with the same key. One that was charged and then failed answers the same error again (its details.creditsCharged says what it was charged), never a second charge.

In AI apps

Claude, ChatGPT and other AI apps get what you are asked to approve first: the price, a spending limit or how much a spending limit grows (for deletes and posts, a preview of what will happen). The AI must show it to you and ask. It can only go ahead with a one-time confirm token that is tied to the exact settings and amount and expires after 10 minutes.

Caps

• Give a key a daily credit cap. A request that would go over it is refused before it runs, with 402 daily_credit_cap_reached. Caps reset at 00:00 UTC.
• Every account has a daily credit limit for API keys and AI apps together (all its keys, the Claude key and connected apps): 500 credits on the free plan, half the plan's monthly credits on a paid plan (at least 2,000). Change it in Settings → API. A request over it is refused before it runs, with 402 daily_credit_cap_reached. The website itself has no such limit.
• Without a key cap, the account's daily limit and your credit balance are the limits. A request you cannot afford is refused with 402 insufficient_credits, and nothing is charged.
• New videos and some free AI helpers also have daily limits per account (see Limits).

Every error has a stable code: build on the code, not the message, which may be reworded. details adds specifics, like which field was wrong (details.issues). Every error answer links to its entry here in docs_url.

Limits protect your account and ours. Going over one answers 429 with a Retry-After header, in seconds. Daily limits reset at 00:00 UTC.

MCP (Model Context Protocol) lets AI apps use Autoclips for you: "make a 60 second video about volcanoes", "put this picture in scenes 1 and 2", "is my render done?". The AI gets the same powers as the API, grouped into a few tools.

https://app.autoclips.app/api/mcp

Claude (web, desktop and mobile)

1. 1In Claude, open Settings → Connectors and add a custom connector.
2. 2Paste the server address above and save.
3. 3Choose Connect, sign in to Autoclips and approve what Claude may do.

Claude Code

claude mcp add --transport http autoclips \
  https://app.autoclips.app/api/mcp

Then run /mcp in Claude Code, pick autoclips and sign in to Autoclips. That is all most people need.

To use a key instead of signing in, make an API key in Settings → API and add the server like this. The key's permissions apply, and so does its daily credit cap: it gets only the tools that check them. The older tools, such as create_video and the UGC ad tools, check neither, so they need a key that may do everything: the Claude key below, or a sign-in. An API key never sees them.

claude mcp add --transport http autoclips \
  https://app.autoclips.app/api/mcp \
  --header "Authorization: Bearer $AUTOCLIPS_API_KEY"

The older Claude key from Settings → Claude (it starts with acmcp_ and may do everything) also still works the same way.

ChatGPT

1. 1Turn on developer mode in ChatGPT (Settings → Apps & Connectors → Advanced settings).
2. 2Create a connector with the server address above, and sign in to Autoclips when asked.

For a custom GPT, add an Action instead: import the OpenAPI document and set authentication to API key, type Bearer, with an API key from Settings → API. The whole API is large: for one product, import https://app.autoclips.app/api/v1/openapi.json?product=v3 (or ce, studio), which keeps the shared calls every video needs and the shared calls that work on that product's projects (for V3, the timeline it is edited with).

How the AI behaves

• It asks only about choices that matter and offers the defaults for the rest. It can look up every choice with the autoclips_options tool.
• For anything that costs credits, deletes or posts, it shows you the price (for a video charged step by step as it is made, a spending limit and the expected price; to raise a spending limit, how much it grows) or a preview and waits for your yes. Character Explainer Quick Create's and V3 Quick Create's spending limits are the most each can charge. Autopilot stops before a step that would go past its spending limit, but one step's final cost can run a little over.
• Free changes happen straight away, and it tells you what changed.

Tools

Each tool groups the actions for one kind of thing. The AI passes action and the fields that action takes. Every action checks the permissions of the key or sign-in.

Original tools

These came before the tools above and keep working. They check neither permissions nor a key's daily credit cap, so an API key never sees them: A sign-in or the Claude key (never an API key) can use them. What they spend counts toward the account's daily limit for API keys and AI apps. The UGC ad tools are only here, so they need a sign-in or the Claude key too. Anything that costs credits or posts shows you the price or a preview first.

Use your own pictures, clips and audio, even from a chat on your phone.

1. 1Ask the AI for an upload link. It opens a page that works once, for 15 minutes, and the files go into your own library.
2. 2Drop the file there, or pick it from your phone, and watch it upload.
3. 3Tell the AI what to do with it, for example "add this picture to scenes 1 and 2, starting at 3:36". It finds the file in your media.

Already online? Give the AI (or the API) a public https link, for example from Google Drive or Dropbox, and it is imported. Only public addresses are fetched.

File types and size limits: see Media file type.

• shared.media.list: List the pictures, videos and sounds in your library, newest first.
• shared.media.get: Get one picture, video or sound from your library by its id.
• shared.media.upload_links.get: Check an upload link: waiting, uploading, uploaded, failed, expired or revoked, and the files that came in.
• shared.media.upload_links.create: Make a one-time upload link for the user. They open it on any device and drop files into your library.
• shared.media.delete: Delete a file from your library. Projects that already use it may stop rendering.
• shared.media.import: Copy a file from a public https link (Google Drive, Dropbox or any direct link) into your library.
• shared.media.upload: Upload 1 to 10 files (multipart/form-data, field "file") into your library.