Enviar una generación

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

Authorization: Bearer <CLIPIA_API_KEY>

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

{
  "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
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_api_key",
    "message": "API-ключ отсутствует, неверный или отозван."
  }
}

{
  "error": {
    "type": "billing_error",
    "code": "insufficient_credits",
    "message": "Insufficient credits. Top up your balance to continue."
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "insufficient_scope",
    "message": "У ключа нет scope `generate`."
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "model_input_invalid",
    "message": "Параметр `resolution` не поддерживается этой моделью."
  }
}

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after the reset window.",
    "retry_after_seconds": 12
  }
}

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.

Solicitud

Parámetro de ruta

Cabeceras

Cuerpo

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). Si el modelo trabaja a partir de una imagen o un vídeo de origen, prompt es opcional; en otro caso, es obligatorio.

Ejemplo

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"
  }'

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

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)

Respuesta 200

{
  "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

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 con el mismo input.

Parámetros ignorados

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:

{
  "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."
    }
  ]
}

• 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, 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.

Errores del envío

Los errores usan el formato común {"error": {"type", "code", "message"}}: consulte Errores. En los errores 400, el motivo concreto está en el campo message.