Generaciones

Los modelos de video e imagen tardan desde unos segundos hasta varios minutos, por lo que las solicitudes son asíncronas. Al enviar una solicitud, recibes de inmediato una generación; luego puedes consultar su estado o recibir un webhook cuando alcance un estado final. Un objeto de generación describe la tarea completa: entrada, estado, resultado, error y coste.

Ciclo de vida#

succeeded, failed y canceled son estados finales: la generación no cambia después de alcanzar uno de ellos. Trata cualquier otro valor como «aún en curso» para que tu código siga funcionando si añadimos estados intermedios.

1. Enviar#

POST /api/v1/run/{endpoint} con las entradas del modelo en el cuerpo JSON. El ID del endpoint combina el modelo y la tarea; por ejemplo, bytedance/seedance-2.0-fast/text-to-video. Consulta la página de Modelos para ver todos los endpoints y sus campos.

Validamos la entrada, calculamos el precio, lo reservamos de tu saldo y ponemos la tarea en cola. La respuesta es 202 Accepted con la generación, además de urls.get y urls.cancel para mayor comodidad:

{
  "id": "gen_8c2QmX1nq0k4Lw7Z",
  "object": "generation",
  "model": "bytedance/seedance-2.0-fast",
  "endpoint": "bytedance/seedance-2.0-fast/text-to-video",
  "mode": "text-to-video",
  "status": "queued",
  "input": {
    "prompt": "Travelling lento hacia un ceramista que da forma a un jarrón a la hora dorada; polvo en la luz y poca profundidad de campo",
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "duration": 5,
    "generate_audio": true
  },
  "output": null,
  "error": null,
  "cost": {
    "amount_usd": 0.4494,
    "currency": "usd",
    "estimated": true
  },
  "source": "api",
  "created_at": "2026-10-15T09:21:04.512Z",
  "started_at": null,
  "completed_at": null,
  "retention": "1d",
  "expires_at": null,
  "purged_at": null,
  "urls": {
    "get": "https://cheapergen.com/api/v1/generations/gen_8c2QmX1nq0k4Lw7Z",
    "cancel": "https://cheapergen.com/api/v1/generations/gen_8c2QmX1nq0k4Lw7Z/cancel"
  }
}

Imágenes, videos y audios de referencia#

Las modalidades reference-to-video admiten hasta tres tipos de referencias, cada uno como una lista de URL HTTPS (enlaces públicos o URL de uploads): reference_image_urls para personajes, productos y escenas; reference_video_urls para movimiento, movimientos de cámara y efectos; y reference_audio_urls para voz, música y sonido.

Menciónalas en el prompt por posición: @Image1 es la primera URL de reference_image_urls, @Video1 la primera de reference_video_urls, @Audio2 el segundo clip de audio, etc. Las menciones no distinguen mayúsculas y se normalizan como @Image1. Si una mención no tiene una referencia correspondiente (por ejemplo, @Video2 con un solo video adjunto), se rechaza con 400 invalid_request (param: "prompt") antes de cobrar nada.

{
  "prompt": "@Image1 dances on a rooftop, copying the choreography and camera move of @Video1, in sync with @Audio1",
  "reference_image_urls": [
    "https://example.com/dancer.jpg"
  ],
  "reference_video_urls": [
    "https://example.com/choreo.mp4"
  ],
  "reference_audio_urls": [
    "https://example.com/beat.mp3"
  ],
  "resolution": "720p",
  "duration": 8
}

Al enviar la solicitud, descargamos el inicio de cada video y archivo de audio de referencia y comprobamos su duración, tamaño, resolución y frecuencia de fotogramas reales frente a los límites del modelo. Si un archivo no cumple los límites —por ejemplo, un clip de 20 segundos, un video de 1080p para un modelo que admite 720p, un M4A cuando se requiere MP3 o WAV, o una URL que no responde—, devolvemos 400 invalid_request con param indicando el campo (por ejemplo, reference_video_urls) y un mensaje que identifica el clip, sin cobrar nada. Los videos de referencia añaden segundos facturables; consulta Facturación.

Los videos deben ser archivos MP4/MOV con H.264 o H.265. Se aplican los límites más estrictos de la capacidad que usa cada modelo, por lo que el servicio del modelo acepta cualquier solicitud que supere esta comprobación. Las imágenes y el audio de referencia no modifican el precio.

2. Consultar el resultado#

GET /api/v1/generations/{id} devuelve el estado actual. Consultar una generación también hace avanzar el proceso: si corresponde comprobar el estado, lo hacemos antes de responder; por eso, los datos de una consulta nunca tienen más de unos segundos.

const API = "https://cheapergen.com/api/v1";
const headers = { Authorization: `Bearer ${process.env.CHEAPERGEN_API_KEY}` };
const FINAL = new Set(["succeeded", "failed", "canceled"]);

export async function wait(id, timeoutMs = 15 * 60_000) {
  let delay = 2000;
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const gen = await fetch(`${API}/generations/${id}`, { headers }).then((r) => r.json());
    if (FINAL.has(gen.status)) return gen;
    await new Promise((r) => setTimeout(r, delay));
    delay = Math.min(delay * 1.5, 10_000); // back off to every 10 s
  }
  // Giving up: cancel it first, or it still runs and is charged when it finishes (once running it can't be: 409).
  await fetch(`${API}/generations/${id}/cancel`, { method: "POST", headers }).catch(() => {});
  throw new Error(`Timed out waiting for ${id}`);
}

import os, time, requests

API = "https://cheapergen.com/api/v1"
headers = {"Authorization": f"Bearer {os.environ['CHEAPERGEN_API_KEY']}"}

def wait(gen_id, timeout=900):
    delay, waited = 2, 0
    while waited < timeout:
        gen = requests.get(f"{API}/generations/{gen_id}", headers=headers).json()
        if gen["status"] in ("succeeded", "failed", "canceled"):
            return gen
        time.sleep(delay)
        waited += delay
        delay = min(delay * 1.5, 10)  # back off to every 10 s
    # Giving up: cancel it first, or it still runs and is charged when it finishes (once running it can't be: 409).
    requests.post(f"{API}/generations/{gen_id}/cancel", headers=headers)
    raise TimeoutError(gen_id)

Intervalos de consulta recomendados#

• Imágenes: cada 1–2 segundos. La mayoría termina en menos de 30 segundos.
• Videos: cada 3–5 segundos al principio; después, amplía gradualmente el intervalo hasta 10 segundos. Un clip de 5 segundos suele tardar entre uno y tres minutos; las resoluciones altas tardan más.
• Las consultas cuentan para el límite de solicitudes. Si ejecutas muchas tareas a la vez, es preferible usar webhooks.

3. Usa el resultado#

Si la tarea termina correctamente, output contiene URL HTTPS a los archivos multimedia generados. Los modelos de video devuelven un archivo:

{
  "output": {
    "video": {
      "url": "https://cdn.cheapergen.com/outputs/gen_8c2QmX1nq0k4Lw7Z.mp4",
      "content_type": "video/mp4"
    }
  }
}

Los modelos de imagen devuelven una lista, con una entrada por cada imagen generada:

{
  "output": {
    "images": [
      {
        "url": "https://cdn.cheapergen.com/outputs/gen_8c2QmX1nq0k4Lw7Z.png",
        "content_type": "image/png"
      }
    ]
  }
}

Fallos y reembolsos#

Si una generación falla, status es failed, error indica el motivo y qué hacer, y cost.amount_usd pasa a 0: se devuelve a tu saldo todo el importe retenido. Los trabajos se reintentan automáticamente en todas las demás rutas disponibles antes de marcarlos como fallidos, si se trata de una interrupción o un error del proveedor. No se reintentan si los rechaza el filtro de seguridad o si el modelo no admite una entrada: volverían a rechazarse por el mismo motivo. Cuando un proveedor no puede descargar uno de tus archivos de entrada, normalmente lo descargamos nosotros y volvemos a intentarlo con nuestra copia, al mismo precio; input_unreachable suele significar que no se pudo descargar en absoluto.

{
  "status": "failed",
  "error": {
    "code": "generation_failed",
    "message": "ByteDance's safety review for Seedance 2.0 Fast rejected this request (the prompt or an input file).",
    "reason": "content_blocked",
    "hint": "Describe the character's look instead of naming a copyrighted character or real person, keep it non-explicit, or try another model.",
    "retryable": false,
    "refunded": true,
    "detail": "Tu solicitud no superó la revisión de seguridad del contenido. Ajusta el prompt y vuelve a intentarlo."
  },
  "cost": {
    "amount_usd": 0,
    "currency": "usd",
    "estimated": false
  }
}

• code: la categoría general, sin cambios desde el lanzamiento: generation_failed (se rechazó la entrada o no se pudo completar), upstream_error, timeout o model_unavailable.
• reason: el motivo exacto, según la tabla siguiente. Usa este valor en las integraciones nuevas; pueden añadirse otros motivos.
• message: explicación en lenguaje claro de lo ocurrido, apta para mostrar a tus usuarios. Si lo rechaza un filtro de seguridad, identifica al responsable (el proveedor del modelo).
• hint: qué cambiar o hacer a continuación.
• retryable: true si al volver a enviar la misma solicitud puede funcionar; false si volvería a fallar por el mismo motivo.
• refunded: true cuando se devuelve el importe reservado. Las generaciones fallidas nunca se cobran.
• param: el campo de entrada que hay que cambiar, si podemos identificarlo (por ejemplo, image_url o duration).
• detail: el texto original del proveedor del modelo, si aporta información adicional.

Las generaciones que fallaron antes de que existiera reason conservan el code original; también se rellenan reason y hint.

Precio de emergencia#

Si la capacidad habitual de una solicitud no está disponible, puede ejecutarse con capacidad de mayor costo al precio de emergencia, que nunca supera el precio oficial del modelo. allow_fallback_price determina el comportamiento y, en la API REST y MCP, el valor predeterminado es true para nuevas solicitudes: se cotiza y cobra el precio de emergencia. Si falla a mitad de camino la capacidad de un trabajo que ya se aceptó al precio estándar, puede cambiarse a esa otra capacidad (el importe adicional se reserva en ese momento). max_cost_usd establece un límite para ambos importes. Envía allow_fallback_price: false para no pagar nunca más que el precio cotizado (en un Plan Pro o Max; de lo contrario, un trabajo aceptado también puede subir, como máximo, hasta el precio estándar): las nuevas solicitudes reciben 503 fallback_price_declinedy, si falla un trabajo aceptado, se reembolsará. Los trabajos de Studio nunca pasan a un precio superior después de que haces clic. Cuando se aplica, el pricing.fallback (también en los webhooks) lo indica junto con ambos precios.

Verificador de seguridad#

enable_safety_checker tiene el valor predeterminado true. Puedes enviar false mediante la API; en Studio y en las páginas de los modelos está siempre activado. Su función depende del modelo:

• Modelos cerrados (Seedance, Kling, Veo, MiniMax H3, Wan 3.0…) incluyen la moderación propia de sus laboratorios, que nadie puede desactivar. Aceptan true y false, y ninguno de los dos cambia nada, así que la opción no aparece en sus esquemas. MiniMax H3 Max es la excepción: permite desactivar el filtro, por lo que incluye esa opción en su esquema. Esas solicitudes utilizan su propia configuración de seguridad — posiblemente al precio de emergencia, pero nunca por encima del precio oficial.
• Seedream 4.5 and Seedream 5.0 Lite también lo incluyen. Si se desactiva, la solicitud se ejecuta con la configuración internacional propia del modelo de ByteDance; esa configuración no aplica ningún filtro adicional; si está activado, se aplican los filtros habituales. Nuestro filtro sigue bloqueando cualquier contenido sexual que involucre a menores. Las solicitudes con esta opción desactivada tienen un precio propio más alto: Seedream 4.5 $0.04 per image · Seedream 5.0 Lite $0.035 per image. /quote lo devuelve cuando envías enable_safety_checker: false (con fallback.reason "safety_checker_off"). Cuenta como una precio de emergencia: con allow_fallback_price: false se rechaza una solicitud así. Si no se puede ejecutar en ese momento, la solicitud se rechaza con 503 model_unavailable (param: "enable_safety_checker"); envía true para ejecutarla con el filtro estándar.
• Modelos de pesos abiertos los incluye. Cuando una generación se ejecuta en una capacidad sin filtro propio, nuestro verificador revisa primero el prompt y las imágenes de entrada: con el interruptor activado, bloquea el contenido sexual, la violencia gráfica y el contenido de autolesión; desactivado, sigue bloqueando cualquier contenido sexual que involucre a menores. Cuando la capacidad tiene un filtro propio que se puede activar o desactivar, el interruptor se le pasa tal como lo enviaste; desactivado, nuestro verificador sigue bloqueando cualquier contenido sexual que involucre a menores.

false en un modo que no enumera la opción (y no puede desactivar su verificador) devuelve 400 invalid_request. Desactivarla no permite ningún contenido que prohíba nuestra Política de uso aceptable.

Retención de datos#

Generaciones de API se conservan durante 1 día de forma predeterminada, a partir del momento en que termina la generación. Después, eliminamos automáticamente el prompt, los archivos multimedia de entrada, los resultados y sus archivos. La generación se conserva con su modelo, los parámetros que determinan el precio, el coste y las marcas de tiempo, para que el historial de uso y las facturas sigan siendo precisos: output pasa a ser null, se establece purged_at y content_expired explica el motivo. Descarga los resultados que quieras conservar antes de expires_at.

Envía retention en el cuerpo de la solicitud para elegir el plazo de cada generación. Cualquier cuenta puede acortarlo (o solicitar hasta 1d); 7d y 30d requieren un ajuste de retención a nivel de cuenta: contactar con ventas. Si solicitas un plazo superior al permitido en tu cuenta, se devuelve 400 invalid_request con param: "retention".

{
  "prompt": "A paper boat drifting down a rain-soaked street",
  "resolution": "720p",
  "duration": 5,
  "retention": "immediate",
  "webhook_url": "https://example.com/hooks/cheapergen"
}

Generaciones de Studio y del entorno de prueba se conservan hasta que los elimines. Las Cargas se conservan mientras alguna generación guardada las use; los archivos que no use ninguna generación se eliminan después de 1 día. Al eliminar tu cuenta, se eliminan todas tus generaciones y archivos. Cuando el proveedor del modelo permite elegir, también le pedimos que conserve lo mínimo posible.

Eliminar una generación#

Elimina cualquier generación terminada con DELETE /api/v1/generations/{id}, desde la lista de generaciones del panel o desde el visor de Studio; con la API, también una en cola mientras aún se pueda cancelar (primero se cancela y lo reservado se reembolsa íntegramente). Sus archivos, prompt y entradas se eliminan al momento y desaparece de las listas; el cargo permanece en tu historial de facturación. Consulta la referencia de la API.

Cancelación#

POST /api/v1/generations/{id}/cancel cancela una generación que aún está queued y reembolsa el importe reservado. Cuando una tarea está running, el modelo ya está procesándola; cancelarla devuelve 409 conflict, pero la tarea termina y se factura con normalidad. Algunos modelos no permiten cancelar tareas una vez en cola; en esos casos también se devuelve 409.

curl -X POST https://cheapergen.com/api/v1/generations/gen_8c2QmX1nq0k4Lw7Z/cancel \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY"

Listar generaciones#

GET /api/v1/generations muestra tus generaciones, de la más reciente a la más antigua, con paginación por cursor. Filtra por status, model o source (playground, api, mcp); pasa el next_cursor devuelto como cursor para obtener la página siguiente. Consulta los detalles en referencia de la API.

curl "https://cheapergen.com/api/v1/generations?status=succeeded&limit=50" \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY"

Las generaciones de Studio y del entorno de prueba de las páginas de modelos también aparecen aquí, con source: "playground"; las solicitudes de la API tienen source: "api".