---
title: Enviar una generación
description: POST /v1/models/{model} — ponga en cola una generación de imagen, vídeo o audio, obtenga un request_id y envíe la solicitud directamente desde esta página.
icon: Send
---

Ponga en cola una generación de imagen, vídeo o audio. Rellene los parámetros siguientes y envíe la solicitud con su clave.

## Playground

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

`POST /v1/models/:model` pone en cola una generación y devuelve de inmediato un `request_id`, enlaces a su estado y a su resultado, y el coste reservado en créditos. La clave necesita el permiso `generate`.

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

## Solicitud

**Parámetro de ruta**

<TypeTable
  type={{
    model: { type: 'string', description: 'Slug del modelo, por ejemplo nano-banana-2 o seedance-2-fast-i2v. Letras minúsculas, dígitos y guiones. Consulte la lista en GET /v1/models.', required: true }
  }}
/>

**Cabeceras**

<TypeTable
  type={{
    Authorization: { type: 'string', description: 'Bearer clipia_live_… (o el esquema Key, o la cabecera X-Api-Key)', required: true },
    'Content-Type': { type: 'string', description: 'application/json', required: true },
    'Idempotency-Key': { type: 'string', description: 'Hasta 255 caracteres; se recomienda un UUID v4. Hace que los reintentos sean seguros durante 24 horas.' }
  }}
/>

**Cuerpo**

<TypeTable
  type={{
    input: { type: 'object', description: 'Parámetros de la generación. La estructura depende del modelo: consulte input_schema en GET /v1/models/:model. Hasta 100.000 bytes y 8 niveles de anidamiento.', required: true },
    webhook_url: { type: 'string', description: 'Dirección HTTPS que recibe un POST cuando termina el trabajo. Se rechazan las direcciones internas y privadas.' }
  }}
/>

Claves habituales dentro de `input`: `prompt`, `image_url`, `image_urls`, `aspect_ratio`, `duration`, `resolution`; pero cada modelo tiene su propio conjunto: pase lo que el modelo declara en `input_schema` (qué ocurre con una clave sobrante, [más abajo](#warnings)). Si el modelo trabaja a partir de una imagen o un vídeo de origen, `prompt` es opcional; en otro caso, es obligatorio.

## Ejemplo

<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! });

// La Idempotency-Key se añade automáticamente.
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"])

# La Idempotency-Key se añade automáticamente.
job = client.submit(
    "nano-banana-2",
    {"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>

**Respuesta `200`**

```json
{
  "request_id": "764cabcf-b745-4b3e-ae38-1200304cf45b",
  "status": "IN_QUEUE",
  "queue_position": 0,
  "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
}
```

**Campos de la respuesta**

<TypeTable
  type={{
    request_id: { type: 'string', description: 'Identificador del trabajo (UUID)' },
    status: { type: 'string', description: 'IN_QUEUE, IN_PROGRESS, COMPLETED, FAILED o CANCELED' },
    queue_position: { type: 'integer', description: 'Posición en la cola, 0 por defecto' },
    status_url: { type: 'string', description: 'Enlace para consultar el estado' },
    response_url: { type: 'string', description: 'Enlace para obtener el resultado' },
    cost: { type: 'integer', description: 'Créditos reservados para el trabajo' },
    warnings: { type: 'array', description: 'Parámetros de input que el modelo no aplicará. Solo aparece cuando se han encontrado; véase más abajo.' }
  }}
/>

Los créditos de `cost` se reservan al enviar, se cobran si la generación tiene éxito y se reembolsan íntegramente si falla. Para conocer el precio de antemano, llame a la [estimación del coste](/es/docs/api-reference/estimate) con el mismo `input`.

<Callout type="info" title="Reintentos">
Con una cabecera `Idempotency-Key`, repetir el mismo cuerpo en un plazo de 24 horas devuelve el mismo trabajo sin un segundo cargo. Sin la cabecera, las solicitudes idénticas que llegan en un intervalo de 20 segundos también se fusionan en un solo trabajo. Consulte [Idempotencia](/es/docs/api-reference/idempotency).
</Callout>

## Parámetros ignorados [#warnings]

Cada modelo tiene su propio conjunto de parámetros. Si `input` contiene una clave que el modelo no aplicará (una errata, un parámetro de otro modelo, una clave de un ejemplo antiguo), la solicitud se acepta como antes y no se rechaza. Pero la respuesta incluye además una matriz `warnings`, con un elemento por cada clave:

```json
{
  "request_id": "5b0c1f7e-2a53-4a0e-9d0b-6f1f4d0f2c11",
  "status": "IN_QUEUE",
  "queue_position": 0,
  "status_url": "https://api.clipia.ai/v1/requests/5b0c1f7e-2a53-4a0e-9d0b-6f1f4d0f2c11/status",
  "response_url": "https://api.clipia.ai/v1/requests/5b0c1f7e-2a53-4a0e-9d0b-6f1f4d0f2c11",
  "cost": 12,
  "warnings": [
    {
      "code": "unsupported_parameter",
      "parameter": "duration",
      "message": "Parameter \"duration\" is not supported by model \"nano-banana-2\" and was ignored. Parameters declared by this model: aspect_ratio, prompt, resolution. Full schema: GET /v1/models/nano-banana-2."
    }
  ]
}
```

<TypeTable
  type={{
    code: { type: 'string', description: 'unknown_parameter: el servidor no conoce el nombre (por ejemplo, una errata); unsupported_parameter: el nombre existe, pero este modelo no lo declara ni lo usa. Trate un valor desconocido como «no aplicado».' },
    parameter: { type: 'string', description: 'Nombre de la clave de input' },
    message: { type: 'string', description: 'Explicación en inglés con la lista de parámetros que el modelo declara' }
  }}
/>

- Cuando se aceptan todos los parámetros, la respuesta no tiene el campo `warnings`. La matriz contiene como máximo 20 elementos.
- Otra forma de escribir un parámetro declarado, que el servidor convierte por sí mismo al nombre correcto, no se considera una advertencia.
- La advertencia aparece solo cuando el servidor está seguro de que el parámetro no se aplicará. Su ausencia no confirma que todos los parámetros hayan surtido efecto: compare `input` con el `input_schema` del modelo.
- Los mismos `warnings` los devuelven la [estimación del coste](/es/docs/api-reference/estimate), una clave de prueba y un reintento con el mismo `Idempotency-Key`.
- En MCP, el mismo caso es un rechazo antes de iniciar la generación: consulte [Herramientas MCP](/es/docs/mcp/tools#unsupported-parameters).

## Errores del envío [#submit-errors]

Los errores usan el formato común `{"error": {"type", "code", "message"}}`: consulte [Errores](/es/docs/api-reference/errors). En los errores `400`, el motivo concreto está en el campo `message`.

| HTTP | `code` | `message` | Cuándo |
|------|--------|-----------|--------|
| 400 | `invalid_request` | `invalid_model` | el slug no tiene el formato correcto: letras minúsculas, dígitos, guiones |
| 400 | `invalid_request` | `prompt_required` | no hay `prompt` ni imagen o vídeo de origen |
| 400 | `invalid_request` | `input_too_large` / `input_too_deep` | `input` supera los 100.000 bytes o los 8 niveles de anidamiento |
| 400 | `invalid_request` | `idempotency_key_too_long` | `Idempotency-Key` tiene más de 255 caracteres |
| 400 | `invalid_request` | `webhook_url_invalid` | `webhook_url` no es HTTPS o apunta a una dirección interna |
| 400 | `invalid_request` | `media_url_invalid` | la URL de un archivo de origen apunta a una dirección interna |
| 402 | `insufficient_credits` | — | no hay créditos suficientes, o la cuenta nunca ha hecho una compra (clave live) |
| 402 | `subscription_required` | — | esta operación requiere una suscripción activa |
| 403 | `insufficient_scope` | — | la clave no tiene el permiso `generate` |
| 404 | `not_found` | `model_not_found` | no existe ningún modelo con este slug, o no está disponible |
| 409 | `request_in_progress` / `idempotency_key_reuse` | — | consulte [Idempotencia](/es/docs/api-reference/idempotency) |
| 429 | `rate_limit_exceeded` / `concurrency_limit_exceeded` | — | consulte [Límites de solicitudes](/es/docs/api-reference/rate-limits) |