Ziztu API

Base URL: https://getziztu.com/api/v1. The OpenAPI 3.1 spec is at https://getziztu.com/api/v1/openapi.json.

1. Open the Studio at getziztu.com/app and sign in. Open Settings, then API keys.
2. Name the key (for example "Claude Code") and pick its scopes: read to look around, generate to plan and make things, export to download films.
3. Copy the key. It starts with sk_sakuga_ and is shown once.

Send the key on every request, in either header:

Authorization: Bearer sk_sakuga_your_key
X-API-Key: sk_sakuga_your_key

Scopes: read for every GET, generate for every change including paid generation, export for renders and downloads. A key can hold any of them. You can have up to 20 active keys.

Every call that costs credits needs max_credits. The call is refused if the real price is higher, and nothing is started. To see the price first, add dry_run: true:

{
  "max_credits": 200,
  "dry_run": true
}

• max_credits is required on every call that costs credits: first frames, clips, music and Studio app runs. If the price is higher, the call is refused before anything starts.
• Above 500 credits, add confirm: true. A bigger spend needs a second, explicit yes.
• Ask the price first. dry_run: true or the quote tool returns the exact credits and starts nothing. The quote also lists any shot that is blocked, and why.
• Retries are safe with an Idempotency-Key header: the same key and body returns the first answer instead of running twice.
• Scope the key. A key without generate cannot start paid work. Make a read key for an agent that should only look.
• Revoke it any time under Settings, API keys. It stops working at once.

From a new project to an exported film. Replace PID, MID and JID with the ids in the replies.

BASE=https://getziztu.com/api/v1
AUTH="Authorization: Bearer $ZIZTU_TOKEN"
JSON='Content-Type: application/json'

# 1. Check the key and the balance
curl -s $BASE/credits -H "$AUTH"

# 2. Create a project (9:16 for a vertical micro drama)
curl -sX POST $BASE/projects -H "$AUTH" -H "$JSON" \
  -d '{"name":"Dough letter","aspect":"9:16"}'
PID=...   # the id in the reply

# 3. Ask the Director to plan it. The reply has an id and proposed actions
curl -sX POST $BASE/projects/$PID/director/chat -H "$AUTH" -H "$JSON" \
  -d '{"message":"Plan a 60 second micro drama about a baker who finds a love letter in the dough"}'
MID=...   # message.id in the reply

# 4. Apply the free actions: the cast, the places and the shots
curl -sX POST $BASE/projects/$PID/director/messages/$MID/apply-all -H "$AUTH"

# 5. Price the first frames. Nothing is spent
curl -sX POST $BASE/projects/$PID/generate/frames -H "$AUTH" -H "$JSON" \
  -d '{"max_credits":999,"dry_run":true}'

# 6. Make them, within a cap. The Idempotency-Key makes a retry safe
curl -sX POST $BASE/projects/$PID/generate/frames -H "$AUTH" -H "$JSON" \
  -H 'Idempotency-Key: frames-001' \
  -d '{"max_credits":200}'

# 7. Poll a job
curl -s $BASE/jobs/$JID -H "$AUTH"

# 8. Export the film
curl -sX POST $BASE/projects/$PID/export -H "$AUTH"

Retrying a paid call with the same Idempotency-Key and body returns the first answer (with Idempotent-Replayed: true) instead of running again. Answers are kept for 24 hours.

The paths below are under https://getziztu.com/api/v1, except the API key routes. The OpenAPI spec has the request shapes.

Projects

Characters and places

Shots

Music tracks

Director AI

Paid generation

Export and media

Jobs

Credits

Tools

API keys

The API key routes work with a signed-in session, not with an API key. A key cannot make other keys.

{
  "error": {
    "code": "over_max_credits",
    "message": "This would spend 150 credits, more than max_credits (100). Nothing more was started.",
    "max_credits": 100,
    "needed": 150
  }
}

A paid call from an account with too few credits is refused with HTTP 402 before anything starts.

By default 120 requests a minute per key, and 30 paid POSTs a minute. A response carries X-RateLimit-Limit and X-RateLimit-Remaining. When you pass the limit you get HTTP 429 and a Retry-After header with the seconds to wait.