> ## Documentation Index
> Fetch the complete documentation index at: https://docs.codzen.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Create an API key, submit your first generation to https://codzen.ai/api/v1 with curl, and poll it until its output is ready to download.

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

**1. Create an API key**

Sign in to [Codzen](https://codzen.ai), 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:

```bash theme={null}
export CODZEN_API_KEY="cz_..."
```

Never put an API key in a browser or mobile app. See [Authentication and rate limits](https://docs.codzen.ai/guides/authentication.md).

**2. Submit a generation**

Send the model's slug as `model` and its parameters as `input`. This example uses `codzen-play`; the [Models](https://docs.codzen.ai/models.md) index lists every slug and links to each model's input fields.

```bash theme={null}
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:

```json theme={null}
{
  "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
}
```

**3. Poll until it finishes**

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

```bash theme={null}
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:

```json theme={null}
{
  "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](https://docs.codzen.ai/guides/errors.md).

**4. Download the output**

Each output's `url` downloads without an API key:

```bash theme={null}
curl -o output.mp4 "https://files.codzen.ai/..."
```

The amounts above are examples. See [pricing](https://codzen.ai/pricing) for each model's prices.

## Next steps

> **[Generation lifecycle](https://docs.codzen.ai/guides/generation-lifecycle.md)**
>
> The states a generation goes through, and polling versus webhooks.

> **[Webhooks and signatures](https://docs.codzen.ai/guides/webhooks.md)**
>
> Get called when a generation finishes, and verify the call.

> **[Errors](https://docs.codzen.ai/guides/errors.md)**
>
> Every error code, and which ones to retry.

> **[API reference](https://docs.codzen.ai/api-reference/create-a-generation.md)**
>
> Every endpoint with its request and response shapes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.