---
title: Submit a generation
description: "POST /v1/models/{model} — enqueue a generation and send the request interactively."
---

Enqueue an image or video generation. Fill in the parameters below and send the request with your key.

## Playground

<ApiPlayground path="/v1/models/{model}" method="post" />

`POST /v1/models/:model` enqueues a generation and instantly returns a `request_id` with links to its status and result, plus the operation cost in credits. Creating a generation requires the `generate` scope.

<Method name="POST" path="/v1/models/:model" />

## Request

**Path parameter**

<TypeTable
  type={{
    model: { type: 'string', description: 'Model slug, e.g. nano-banana-2, seedance-2-fast-i2v. List them via GET /v1/models.', required: true }
  }}
/>

**Headers**

<TypeTable
  type={{
    Authorization: { type: 'string', description: 'Bearer clipia_live_… (or the Key scheme, or X-Api-Key)', required: true },
    'Content-Type': { type: 'string', description: 'application/json', required: true },
    'Idempotency-Key': { type: 'string', description: 'UUID v4 for safe POST retries (recommended)' }
  }}
/>

**Body**

<TypeTable
  type={{
    input: { type: 'object', description: 'Generation parameters. Keys depend on the model — the exact schema is in GET /v1/models/:model (input_schema).', required: true },
    webhook_url: { type: 'string', description: 'URL to receive a POST notification on completion (optional)' }
  }}
/>

Common keys inside `input`: `prompt`, `image_url`, `image_urls`, `aspect_ratio`, `duration`, `resolution`.

## Example

<Tabs items={['cURL', 'TypeScript', 'Python']}>
<Tab value="cURL">

```bash
curl -X POST https://api.clipia.ai/v1/models/nano-banana-2 \
  -H "Authorization: Bearer $CLIPIA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f3a1c7e-2b4d-4e6f-9a01-23456789abcd" \
  -d '{
    "input": {
      "prompt": "a sunset over mountains, cinematic",
      "aspect_ratio": "16:9"
    },
    "webhook_url": "https://your-server.com/clipia/webhook"
  }'
```

</Tab>
<Tab value="TypeScript">

```ts
import { createClient } from 'clipia-ai';

const clipia = createClient({ apiKey: process.env.CLIPIA_KEY! });

// An Idempotency-Key (UUID v4) is attached automatically.
const job = await clipia.queue.submit('nano-banana-2', {
  input: { prompt: 'a sunset over mountains, cinematic', aspect_ratio: '16:9' },
  webhookUrl: 'https://your-server.com/clipia/webhook',
});

console.log(job.request_id, job.cost);
```

</Tab>
<Tab value="Python">

```python
import os
from clipia import Clipia

client = Clipia(api_key=os.environ["CLIPIA_KEY"])

# An Idempotency-Key (UUID v4) is attached automatically.
job = client.submit(
    "nano-banana-2",
    input={"prompt": "a sunset over mountains, cinematic", "aspect_ratio": "16:9"},
    webhook_url="https://your-server.com/clipia/webhook",
)

print(job.request_id, job.cost)
```

</Tab>
</Tabs>

**Response `200`**

```json
{
  "request_id": "764cabcf-b745-4b3e-ae38-1200304cf45b",
  "status": "IN_QUEUE",
  "queue_position": 2,
  "status_url": "https://api.clipia.ai/v1/requests/764cabcf-b745-4b3e-ae38-1200304cf45b/status",
  "response_url": "https://api.clipia.ai/v1/requests/764cabcf-b745-4b3e-ae38-1200304cf45b",
  "cost": 12
}
```

**Response fields**

<TypeTable
  type={{
    request_id: { type: 'string', description: 'Generation request identifier (uuid)' },
    status: { type: 'string', description: 'IN_QUEUE, IN_PROGRESS, COMPLETED, FAILED, or CANCELED' },
    queue_position: { type: 'integer | null', description: 'Queue position while the request is queued' },
    status_url: { type: 'string', description: 'Link to check the status' },
    response_url: { type: 'string', description: 'Link to fetch the result' },
    cost: { type: 'number', description: 'Fixed operation cost in credits (reserved at submit)' }
  }}
/>

- `cost` is the fixed operation price in credits, known up front. It is reserved at `submit` and settled on success; on failure it is fully refunded.
- If the balance is too low, the request returns `402 insufficient_credits`.

<Callout type="info" title="Idempotency">
Pass an `Idempotency-Key` (UUID v4) to retry a `POST` safely after network failures. The same key with the same parameters returns the same `request_id` with no double charge (kept for 24 hours). The same key with different parameters returns `409`.
</Callout>

## Cost estimate

To learn the price before enqueueing, use `POST /v1/models/:model/estimate`. It takes the same `input` and returns the credit cost without charging or starting a generation.

<Method name="POST" path="/v1/models/:model/estimate" />

<Tabs items={['cURL', 'TypeScript', 'Python']}>
<Tab value="cURL">

```bash
curl -X POST https://api.clipia.ai/v1/models/seedance-2-fast-i2v/estimate \
  -H "Authorization: Bearer $CLIPIA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "prompt": "aerial shot over a neon city",
      "duration": 8,
      "resolution": "1080p"
    }
  }'
```

</Tab>
<Tab value="TypeScript">

```ts
const { credits } = await clipia.models.estimate('seedance-2-fast-i2v', {
  prompt: 'aerial shot over a neon city',
  duration: 8,
  resolution: '1080p',
});

console.log(`this will cost ${credits} credits`);
```

</Tab>
<Tab value="Python">

```python
est = client.models.estimate(
    "seedance-2-fast-i2v",
    {"prompt": "aerial shot over a neon city", "duration": 8, "resolution": "1080p"},
)

print(est.credits)
```

</Tab>
</Tabs>

```json
{
  "credits": 40
}
```