Quickstart

The Codzen API generates video and images with every Codzen model through one asynchronous API. You submit a generation, then poll it (or receive a webhook) until it finishes.

Base URL: https://codzen.ai/api/v1
Authentication: Authorization: Bearer cz_…
Format: JSON request and response bodies, snake_case fields

Create an API key

Sign in to Codzen, open the console and create an API key. Copy it right away: the full key is shown only once.Keep it in an environment variable on your server:

export CODZEN_API_KEY="cz_..."

Never put an API key in a browser or mobile app. See Authentication and rate limits.

Submit a generation

Send the model’s slug as model and its parameters as input. This example uses codzen-play; the Models index lists every slug and links to each model’s input fields.

curl https://codzen.ai/api/v1/generations \
  -H "Authorization: Bearer $CODZEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "codzen-play",
    "input": {
      "prompt": "A knight draws a glowing sword in a ruined castle, game cutscene"
    }
  }'

The API answers 202 Accepted with the new generation, queued. The estimate is held from your balance:

{
  "id": "gen_01JBXK2Y7P1N3R5T7V9X1Z3B5D",
  "model": "codzen-play",
  "status": "queued",
  "input": {
    "prompt": "A knight draws a glowing sword in a ruined castle, game cutscene"
  },
  "outputs": [],
  "cost": { "currency": "USD", "estimated": "0.50", "amount": null, "usage": [] },
  "error": null,
  "created_at": "2026-10-26T08:00:00Z",
  "started_at": null,
  "completed_at": null
}

Poll until it finishes

Fetch the generation by its id every few seconds until status is succeeded or failed:

curl https://codzen.ai/api/v1/generations/gen_01JBXK2Y7P1N3R5T7V9X1Z3B5D \
  -H "Authorization: Bearer $CODZEN_API_KEY"

Once it has succeeded, outputs lists what it produced and cost.amount is what it cost:

{
  "id": "gen_01JBXK2Y7P1N3R5T7V9X1Z3B5D",
  "model": "codzen-play",
  "status": "succeeded",
  "input": {
    "prompt": "A knight draws a glowing sword in a ruined castle, game cutscene"
  },
  "outputs": [{ "type": "video", "url": "https://files.codzen.ai/..." }],
  "cost": {
    "currency": "USD",
    "estimated": "0.50",
    "amount": "0.50",
    "usage": [{ "unit": "output_second", "quantity": 5, "unit_price": "0.10" }]
  },
  "error": null,
  "created_at": "2026-10-26T08:00:00Z",
  "started_at": "2026-10-26T08:00:03Z",
  "completed_at": "2026-10-26T08:01:10Z"
}

If it failed, error says why. See Errors.

Download the output

Each output’s url downloads without an API key:

curl -o output.mp4 "https://files.codzen.ai/..."

The amounts above are examples. See pricing for each model’s prices.

Next steps

Generation lifecycle

The states a generation goes through, and polling versus webhooks.

Webhooks and signatures

Get called when a generation finishes, and verify the call.

Errors

Every error code, and which ones to retry.

API reference

Every endpoint with its request and response shapes.

Get started

Guides

API reference

Models

Next steps

Generation lifecycle

Webhooks and signatures

Errors

API reference

​Next steps

Generation lifecycle

Webhooks and signatures

Errors

API reference

Next steps