Make animated Shorts from your own code or agent.

Quick start

The base URL is https://api.toonyx.com/v1. Sign in to the dashboard with your Toonyx account and make a key, then:

1. Write a Short from an idea

curl https://api.toonyx.com/v1/shorts \
  -H "Authorization: Bearer $TOONYX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"idea": "A banana and a lemon open rival juice stands on the same street"}'

Writing is free. You get back the video with its id, its script and credits_estimate, the price of making it.

2. Get the price, then make it

curl -X POST https://api.toonyx.com/v1/videos/VIDEO_ID/make \
  -H "Authorization: Bearer $TOONYX_KEY"
# {"needs_approval": true, "quote": {"credits": 36, "credits_left": 1264, ...}, "approve": "apv_..."}

curl -X POST https://api.toonyx.com/v1/videos/VIDEO_ID/make \
  -H "Authorization: Bearer $TOONYX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"approve": "apv_..."}'

3. Poll, then download

curl https://api.toonyx.com/v1/videos/VIDEO_ID -H "Authorization: Bearer $TOONYX_KEY"
# status: queued, rendering (with stage, scene and scene_of), then ready

curl -L -o short.mp4 https://api.toonyx.com/v1/videos/VIDEO_ID/download \
  -H "Authorization: Bearer $TOONYX_KEY"

Keys and scopes

Send your key on every call as Authorization: Bearer nyk_.... A key acts as the account that made it: your plan, your credits, your videos, your connected TikTok and YouTube. Nothing more.

• full keys can do everything your account can do in the app.
• read keys only read: GET routes and read tools. Anything else answers 403 read_only_key.
• A key is shown once, when you make it. Toonyx keeps only a hash of it, so a lost key cannot be shown again: revoke it and make a new one.
• Make and revoke keys in the dashboard, signed in with your Toonyx account; it also shows each key's calls, what it was approved to do and the credits its videos were charged. A key cannot make more keys. Up to 10 live keys per account.

Quote, then approve

Nothing that spends credits, posts in public or changes settings runs on a first call. The first call answers with what it would do, the price where there is one, and an approve token:

{
  "ok": false,
  "needs_approval": true,
  "quote": {"credits": 36, "credits_left": 1264, "billed": true},
  "approve": "apv_6v0Qn...",
  "expires_in": 1800,
  "next": "Nothing was spent, posted or changed. Show this to your user. Only on their yes, call make_video again with the same arguments and approve set to this token."
}

Make the same call again with approve set to that token. The token is bound to your key, that tool, those exact arguments and that price. It works once and lasts 30 minutes. If the price changes in between, the token stops matching and you get a fresh quote. If you build an agent on this, have it show the quote to its user and only send the token on their yes.

Endpoints

Every response is JSON (except downloads). Every route needs a key except /v1/pricing.

curl https://api.toonyx.com/v1/me -H "Authorization: Bearer $TOONYX_KEY"

curl https://api.toonyx.com/v1/credits -H "Authorization: Bearer $TOONYX_KEY"

curl https://api.toonyx.com/v1/pricing

curl https://api.toonyx.com/v1/catalog -H "Authorization: Bearer $TOONYX_KEY"

curl https://api.toonyx.com/v1/niches -H "Authorization: Bearer $TOONYX_KEY"

Videos

curl https://api.toonyx.com/v1/shorts \
  -H "Authorization: Bearer $TOONYX_KEY" -H "Content-Type: application/json" \
  -d '{"idea": "A strawberry hides a secret from her sister", "engine": "wan3_prime", "length": "short"}'

curl https://api.toonyx.com/v1/long \
  -H "Authorization: Bearer $TOONYX_KEY" -H "Content-Type: application/json" \
  -d '{"idea": "What if the Moon disappeared tonight", "minutes": 8}'

curl "https://api.toonyx.com/v1/videos?limit=20" -H "Authorization: Bearer $TOONYX_KEY"

curl https://api.toonyx.com/v1/videos/VIDEO_ID -H "Authorization: Bearer $TOONYX_KEY"

curl -X POST https://api.toonyx.com/v1/videos/VIDEO_ID/make \
  -H "Authorization: Bearer $TOONYX_KEY" -H "Content-Type: application/json" \
  -d '{"approve": "apv_..."}'

curl -L -o video.mp4 https://api.toonyx.com/v1/videos/VIDEO_ID/download -H "Authorization: Bearer $TOONYX_KEY"

Thumbnails

YouTube thumbnails, Shorts covers, channel logos and banners, billed in Toonyx credits per image. Open to Toonyx plan holders once Thumbnails opens; until then these answer 403 on customer accounts.

curl https://api.toonyx.com/v1/thumbnails/quote \
  -H "Authorization: Bearer $TOONYX_KEY" -H "Content-Type: application/json" \
  -d '{"mode": "thumbnail", "models": ["Nano Banana Pro"], "per_model": 2}'

curl https://api.toonyx.com/v1/thumbnails \
  -H "Authorization: Bearer $TOONYX_KEY" -H "Content-Type: application/json" \
  -d '{"quote_id": "QUOTE_ID", "title": "I lived on bananas for 30 days", "approve": "apv_..."}'

curl https://api.toonyx.com/v1/thumbnails -H "Authorization: Bearer $TOONYX_KEY"

Every agent tool

Everything the Toonyx agent can do for your account is also a REST call: editing lines, the storyboard, sound, posting, Autopilot, the Niche Lab, channel numbers and more. The list is per account, so a tool your plan does not include is not offered.

curl https://api.toonyx.com/v1/tools -H "Authorization: Bearer $TOONYX_KEY"

curl https://api.toonyx.com/v1/tools/list_dramas \
  -H "Authorization: Bearer $TOONYX_KEY" -H "Content-Type: application/json" -d '{"arguments": {}}'

Errors and limits

Errors are JSON with the HTTP status:

{"error": {"status": 402, "code": "payment_required", "message": "This drama needs 36 credits and you have 20 left."}}

Limits are per key, per minute: 120 calls in all, of which at most 20 may change something (POSTs and non read tools). GET /v1/me shows your key's limits.

MCP server

Plug Toonyx into any agent that speaks the Model Context Protocol. The server is https://api.toonyx.com/mcp (streamable HTTP), with your key as a Bearer header. Its tools are exactly the ones your account can use, plus make_video and video_download. Spend, post and settings tools follow quote, then approve: the tool takes an approve argument.

claude mcp add --transport http toonyx https://api.toonyx.com/mcp \
  --header "Authorization: Bearer nyk_YOUR_KEY"

{
  "mcpServers": {
    "toonyx": {
      "type": "http",
      "url": "https://api.toonyx.com/mcp",
      "headers": { "Authorization": "Bearer nyk_YOUR_KEY" }
    }
  }
}

curl https://api.toonyx.com/mcp \
  -H "Authorization: Bearer $TOONYX_KEY" \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

Credits and pricing

Everything you make is paid in Toonyx credits from your plan, then from credit packs. Loading the live prices. A failed render gives its credits back, and writing, quotes and reads are free.

Video models

Plans

These numbers come live from GET /v1/pricing, the same catalog the app bills from. Full plan details are on toonyx.com/pricing.