Referencia de la API: endpoints y objetos

referencia de la API

Referencia de la API REST: enviar, consultar y cancelar generaciones; listar modelos y precios; obtener cotizaciones; consultar tu saldo y subir imágenes, videos y audio, con ejemplos.

La API se organiza en torno a unos pocos recursos: generations (las tareas que ejecutas), models (lo que puedes ejecutar y cuánto cuesta), quotes, tu account y uploads. Todas las solicitudes y respuestas usan JSON a través de HTTPS.

URL basehttps://cheapergen.com/api/v1

Autentícate con Authorization: Bearer cg_live_… (consulta Autenticación). Los errores usan el formato que se describe en Errores. Todos los endpoints envían encabezados CORS; no expongas tu clave en un navegador: solo los endpoints públicos están diseñados para invocarse desde el cliente.

Endpoints de la API
Endpoint	Descripción
POST/run/{endpoint}	Enviar una generación
GET/generations/{id}	Consultar una generación
GET/generations	Listar generaciones
POST/generations/{id}/cancel	Cancelar una generación en cola
DELETE/generations/{id}	Eliminar una generación y sus archivos multimedia
GET/models	Listar modelos y precios
GET/models/{vendor}/{model}	Consultar un modelo y sus esquemas de entrada
POST/quote/{endpoint}	Calcular el precio de una entrada
GET/account	Saldo, crédito de imagen y recarga automática
GET/account/pricing	Tu plan y tus precios
POST/uploads	Subir un archivo de imagen, video o audio
GET/webhooks/secret	Tu secreto de firma de webhooks

Enviar una generación#

POST/api/v1/run/{endpoint}Se requiere una clave de API

Inicia una generación asíncrona y devuelve 202 Accepted con objeto de generación en estado queued. En ese momento, se reserva el precio de tu saldo (consulta Facturación).

Parámetros de ruta

endpointstringobligatorio: El ID del endpoint del modelo, {vendor}/{model}/{task}; por ejemplo, bytedance/seedance-2.0-fast/text-to-video. Encontrarás todos los ID en la página de Modelos.

Cuerpo

…model inputsobjectobligatorio: Los campos de entrada del endpoint, como prompt, resolution o image_url. En la página de la API de cada modelo se documentan sus campos, tipos, valores predeterminados y valores permitidos; también se devuelven como JSON Schema mediante Consultar un modelo. Se rechazan los campos desconocidos.
webhook_urlstring (https URL): Opcional. Enviaremos aquí la generación terminada mediante una solicitud POST. Consulta Webhooks.
retentionstring: Opcional. Cuánto tiempo conservamos el prompt, las entradas y las salidas de esta generación: immediate, 1h, 1d, 7d o 30d. De forma predeterminada, se usa el ajuste de tu cuenta (1d). Cualquier cuenta puede acortar el plazo; 7d y 30d requieren un ajuste de retención empresarial. Consulta Retención de datos.
allow_fallback_priceboolean: Opcional; valor predeterminado: true. Si no hay capacidad habitual disponible para esta solicitud, se ejecuta en capacidad de mayor costo al precio de emergencia, como máximo al precio oficial del modelo y nunca por encima de max_cost_usd. Esto se aplica al enviar la solicitud (el precio aparece en la respuesta y en /quote) y también, si la capacidad falla después de aceptar el trabajo, a una migración posterior (el importe adicional queda retenido entonces; pricing.fallback y los webhooks lo indican). Establece false para no pagar nunca más que el precio cotizado (con un plan Pro o Max, un trabajo aceptado también podría pasar a la capacidad estándar, pero como máximo al precio estándar): recibirás 503 fallback_price_declined en vez de un precio más alto o de un trabajo fallido con reembolso.
max_cost_usdnumber: Opcional. El máximo que aceptas pagar por esta generación, incluido el precio de emergencia. Si se supera, recibirás 400 max_cost_exceeded y no se te cobrará nada; la tarea nunca se cambiará después a un precio superior.

const resp = await fetch("https://cheapergen.com/api/v1/run/bytedance/seedance-2.0-fast/text-to-video", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CHEAPERGEN_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "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
  }),
});
const generation = await resp.json();

import os, requests

resp = requests.post(
    "https://cheapergen.com/api/v1/run/bytedance/seedance-2.0-fast/text-to-video",
    headers={"Authorization": f"Bearer {os.environ['CHEAPERGEN_API_KEY']}"},
    json={
        "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
    },
)
generation = resp.json()

curl -X POST https://cheapergen.com/api/v1/run/bytedance/seedance-2.0-fast/text-to-video \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "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
}'

Respuesta · 202 Accepted

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

Errores: 400 invalid_request (validación), 401 unauthorized, 402 insufficient_balance, 404 not_found (endpoint desconocido), 429 rate_limited (frecuencia de solicitudes, o tu cola de generaciones en espera está llena), 503 model_unavailable, 503 pricing_unavailable (vuelve a intentarlo en unos segundos; no se cobró nada), 503 fallback_price_declined (solo está disponible el precio de emergencia y enviaste allow_fallback_price: false), 400 max_cost_exceeded.

Consultar una generación#

GET/api/v1/generations/{id}Se requiere una clave de API

Devuelve una generación por su ID. Si corresponde hacer una comprobación de estado, se realiza antes de responder; por eso, basta con consultar este endpoint para que la tarea llegue a completarse. Devuelve 404 not_found si el ID es desconocido o si la generación pertenece a otra cuenta.

Solicitud

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

Respuesta · 200 OK

{
  "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": "succeeded",
  "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": {
    "video": {
      "url": "https://cdn.cheapergen.com/outputs/gen_8c2QmX1nq0k4Lw7Z.mp4",
      "content_type": "video/mp4"
    }
  },
  "error": null,
  "cost": {
    "amount_usd": 0.4494,
    "currency": "usd",
    "estimated": false
  },
  "source": "api",
  "created_at": "2026-10-15T09:21:04.512Z",
  "started_at": "2026-10-15T09:21:09.031Z",
  "completed_at": "2026-10-15T09:22:31.870Z",
  "retention": "1d",
  "expires_at": "2026-10-16T09:22:31.870Z",
  "purged_at": null
}

Listar generaciones#

GET/api/v1/generationsSe requiere una clave de API

Lista tus generaciones, de la más reciente a la más antigua. Incluye los trabajos enviados desde Studio y los entornos de prueba.

Parámetros de consulta

limitinteger: Tamaño de página: 1–100. Valor predeterminado: 20.
cursorstring: El next_cursor de la página anterior.
statusstring: Devuelve únicamente las generaciones con este estado: queued, running, succeeded, failed o canceled.
modelstring: Devuelve únicamente las generaciones de este ID de modelo; por ejemplo, bytedance/seedance-2.0-fast.
sourcestring: Devuelve únicamente las generaciones creadas desde playground (Studio y las páginas de modelos), api o mcp (agentes de IA).

Solicitud

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

Respuesta · 200 OK

{
  "object": "list",
  "data": [
    {
      "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": "succeeded",
      "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": {
        "video": {
          "url": "https://cdn.cheapergen.com/outputs/gen_8c2QmX1nq0k4Lw7Z.mp4",
          "content_type": "video/mp4"
        }
      },
      "error": null,
      "cost": {
        "amount_usd": 0.4494,
        "currency": "usd",
        "estimated": false
      },
      "source": "api",
      "created_at": "2026-10-15T09:21:04.512Z",
      "started_at": "2026-10-15T09:21:09.031Z",
      "completed_at": "2026-10-15T09:22:31.870Z",
      "retention": "1d",
      "expires_at": "2026-10-16T09:22:31.870Z",
      "purged_at": null
    },
    {
      "id": "gen_3vYk2PqL9sTn0bWd",
      "object": "generation",
      "model": "bytedance/seedream-5.0-pro",
      "endpoint": "bytedance/seedream-5.0-pro/text-to-image",
      "mode": "text-to-image",
      "status": "succeeded",
      "input": {
        "prompt": "Foto editorial de producto de una cafetera espresso negro mate sobre travertino, luz suave de ventana, 85 mm",
        "aspect_ratio": "1:1",
        "size": "2K"
      },
      "output": {
        "images": [
          {
            "url": "https://cdn.cheapergen.com/outputs/gen_8c2QmX1nq0k4Lw7Z.png",
            "content_type": "image/png"
          }
        ]
      },
      "error": null,
      "cost": {
        "amount_usd": 0.0665,
        "currency": "usd",
        "estimated": false
      },
      "source": "api",
      "created_at": "2026-10-15T09:21:04.512Z",
      "started_at": "2026-10-15T09:21:09.031Z",
      "completed_at": "2026-10-15T09:22:31.870Z",
      "retention": "1d",
      "expires_at": "2026-10-16T09:22:31.870Z",
      "purged_at": null
    }
  ],
  "next_cursor": "gen_3vYk2PqL9sTn0bWd"
}

next_cursor es null en la última página.

Cancelar una generación#

POST/api/v1/generations/{id}/cancelSe requiere una clave de API

Cancela una generación que aún está queued y reembolsa íntegramente el importe reservado. Devuelve la generación actualizada con status: "canceled". Devuelve 409 conflict si la generación ya está en curso o terminó, o si el modelo no permite cancelar tareas en cola.

Solicitud

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

Respuesta · 200 OK

{
  "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": "canceled",
  "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,
    "currency": "usd",
    "estimated": false
  },
  "source": "api",
  "created_at": "2026-10-15T09:21:04.512Z",
  "started_at": null,
  "completed_at": "2026-10-15T09:21:06.200Z",
  "retention": "1d",
  "expires_at": "2026-10-16T09:21:06.200Z",
  "purged_at": null
}

Eliminar una generación#

DELETE/api/v1/generations/{id}Se requiere una clave de API

Elimina una generación: sus archivos de salida, los archivos de entrada subidos que ninguna otra generación use, el prompt y la entrada se eliminan de inmediato; deja de aparecer en las listas y GET devuelve 404. Los registros de facturación (el cargo en tu libro mayor y los totales de uso) se conservan. Una generación que sigue en estado queued se cancela primero y lo reservado se reembolsa íntegramente; si ya no se puede cancelar (está en curso o su modelo no permite cancelar tareas en cola), devuelve 409 conflict: espera a que termine.

Solicitud

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

Respuesta · 200 OK

{
  "id": "gen_8c2QmX1nq0k4Lw7Z",
  "object": "generation",
  "deleted": true
}

El objeto de generación#

idstring: ID único con el prefijo gen_.
objectstring: Siempre "generation".
modelstring: ID del modelo; por ejemplo, bytedance/seedance-2.0-fast.
endpointstring: ID del endpoint al que se envió la tarea; por ejemplo, bytedance/seedance-2.0-fast/text-to-video.
modestring: Tarea: text-to-video, image-to-video, reference-to-video, text-to-image o image-edit.
statusstring: queued → running → succeeded | failed, o canceled. Consulta Generaciones.
inputobject: The validated input, with defaults filled in.
outputobject | null: Se establece si hay éxito. Video: { "video": { "url", "content_type" } }. Imagen: { "images": [{ "url", "content_type" }] }. Una imagen que el verificador de seguridad sustituye (queda en blanco) también incluye "safety_filtered": true; se cobra igual que cualquier otro resultado.
errorobject | null: Se establece si la tarea falla: { "code", "message", "reason", "hint", "retryable", "refunded" }, además de param (el campo que se debe cambiar) y detail (el texto del proveedor), si se conocen. reason explica el motivo; por ejemplo, content_blocked, invalid_input o upstream_unavailable. Consulta motivos de fallo.
costobject: amount_usd, currency ("usd") y estimated: true mientras el importe está retenido y false cuando se liquida definitivamente. Las generaciones fallidas y canceladas cuestan 0.
pricingobject: custom_price (tu precio: el precio de un contrato o tu Plan Pro o Max), volume_level (1 = Pro, 2 = Max cuando el plan fija el precio; en caso contrario, null), standard_usd (lo que normalmente te cuesta esta solicitud) y fallback: null, o { "active", "reason", "message", "standard_usd", "amount_usd" } si se ejecutó al precio de emergencia —como máximo el precio oficial—, definido por allow_fallback_price y limitado a max_cost_usd.
sourcestring: "api" o "playground" (Studio y las páginas de modelos).
created_atstring: ISO 8601 timestamp of submission.
started_atstring | null: When the model started generating.
completed_atstring | null: When the generation reached a final state.
retentionstring | null: Generaciones de la API: immediate, 1h, 1d, 7d o 30d. null para las generaciones de Studio, que se conservan hasta que las elimines.
expires_atstring | null: Se elimina el contenido (prompt, entradas, resultados y archivos multimedia). Se establece cuando termina la generación. Con immediate, el plazo pasa a ser 10 minutos después de entregar el resultado por primera vez.
purged_atstring | null: Se establece una vez eliminado el contenido. Entonces, output pasa a ser null, input conserva solo los parámetros que determinan el precio y content_expired explica el motivo. Se conservan el coste y las marcas de tiempo.
urlsobject: Solo en la respuesta al enviar la solicitud: las URL get y cancel de esta generación.

Listar modelos#

GET/api/v1/modelsPúblico · sin autenticación

Devuelve todos los modelos disponibles con sus endpoints y precios actuales. Los precios se indican por unit (second de video o image); list_price_usd es el precio de lista de referencia y discount_pct, el ahorro porcentual.list_price_source indica de qué precio se trata: official (la tarifa de lista propia del desarrollador) o reference (otro precio de referencia, identificado por list_price_label; por ejemplo, fal API para un modelo cuyo desarrollador no ofrece una API internacional).

Solicitud

curl https://cheapergen.com/api/v1/models

Respuesta · 200 OK

{
  "object": "list",
  "data": [
    {
      "id": "bytedance/seedance-2.0-fast",
      "object": "model",
      "name": "Seedance 2.0 Fast",
      "vendor": "ByteDance",
      "category": "video",
      "available": true,
      "url": "https://cheapergen.com/models/bytedance/seedance-2.0-fast",
      "endpoints": [
        {
          "id": "bytedance/seedance-2.0-fast/text-to-video",
          "mode": "text-to-video",
          "output": "video"
        },
        {
          "id": "bytedance/seedance-2.0-fast/image-to-video",
          "mode": "image-to-video",
          "output": "video"
        },
        {
          "id": "bytedance/seedance-2.0-fast/reference-to-video",
          "mode": "reference-to-video",
          "output": "video"
        }
      ],
      "pricing": {
        "unit": "second",
        "list_price_source": "official",
        "list_price_label": "Official",
        "tiers": [
          {
            "tier": "480p",
            "price_usd": 0.050086,
            "list_price_usd": 0.056246,
            "discount_pct": 11
          },
          {
            "tier": "720p",
            "price_usd": 0.08988,
            "list_price_usd": 0.12096,
            "discount_pct": 26
          }
        ]
      },
      "deprecation": null,
      "upcoming_price_changes": []
    }
  ]
}

Se muestra un solo modelo para abreviar.

Consultar un modelo#

GET/api/v1/models/{vendor}/{model}Público · sin autenticación

Devuelve un modelo con un JSON Schema para las entradas de cada endpoint; es útil para crear formularios o validar solicitudes antes de enviarlas. Devuelve 404 not_found si el modelo es desconocido.

Solicitud

curl https://cheapergen.com/api/v1/models/bytedance/seedream-5.0-pro

Respuesta · 200 OK

{
  "id": "bytedance/seedream-5.0-pro",
  "object": "model",
  "name": "Seedream 5.0 Pro",
  "vendor": "ByteDance",
  "category": "image",
  "available": true,
  "description": "Seedream 5.0 Pro de ByteDance crea y edita imágenes fotorrealistas y fieles a la marca de hasta 2K, con edición precisa de varias imágenes y representación exacta del texto.",
  "url": "https://cheapergen.com/models/bytedance/seedream-5.0-pro",
  "endpoints": [
    {
      "id": "bytedance/seedream-5.0-pro/text-to-image",
      "mode": "text-to-image",
      "label": "Texto a imagen",
      "output": "image",
      "input_schema": {
        "type": "object",
        "required": [
          "prompt"
        ],
        "properties": {
          "prompt": {
            "title": "Prompt",
            "description": "Describe la toma: sujeto, acción, movimiento de cámara, iluminación y estilo.",
            "type": "string",
            "maxLength": 5000
          },
          "aspect_ratio": {
            "title": "Relación de aspecto",
            "description": "Formato de la imagen de salida.",
            "type": "string",
            "enum": [
              "1:1",
              "4:3",
              "3:4",
              "16:9",
              "9:16",
              "3:2",
              "2:3",
              "21:9"
            ],
            "default": "1:1"
          },
          "size": {
            "title": "Tamaño",
            "description": "1K ≈ 1 megapíxel, 2K ≈ 4 megapíxeles.",
            "type": "string",
            "enum": [
              "1K",
              "2K"
            ],
            "default": "2K"
          },
          "seed": {
            "title": "Semilla",
            "description": "Usa la misma semilla y los mismos ajustes para reproducir un resultado. Déjalo vacío para usar una semilla aleatoria.",
            "type": "integer",
            "minimum": 0,
            "maximum": 2147483647
          },
          "webhook_url": {
            "type": "string",
            "format": "uri",
            "title": "Webhook URL",
            "description": "Optional. We POST the finished generation here (signed)."
          }
        },
        "additionalProperties": false
      }
    }
  ],
  "pricing": {
    "unit": "image",
    "notes": [],
    "list_price_source": "official",
    "list_price_label": "Official",
    "tiers": [
      {
        "tier": "1K",
        "detail": "≈1 MP",
        "price_usd": 0.03325,
        "list_price_usd": 0.045,
        "discount_pct": 26
      },
      {
        "tier": "2K",
        "detail": "≈4 MP",
        "price_usd": 0.0665,
        "list_price_usd": 0.09,
        "discount_pct": 26
      }
    ]
  },
  "deprecation": null,
  "upcoming_price_changes": []
}

Se muestra un solo endpoint para abreviar.

Retiros y cambios de precio#

Anunciamos con antelación los aumentos de precio y las retiradas de modelos: al menos 14 días antes de un aumento (más si tu contrato lo establece) y 14–30 días antes de retirar un modelo. Avisamos por correo a todas las personas que lo hayan usado en los últimos 90 días y lo publicamos en registro de cambios (RSS). La API ofrece la misma información para que tu código y tus agentes puedan reaccionar:

deprecationobject | null: En las respuestas de «Listar modelos» y «Consultar un modelo» se incluyen estos campos. Mientras esté programada la retirada de un modelo, se establecen: sunset_at (fecha y hora ISO 8601; desde entonces, las solicitudes devuelven 410 model_delisted y no se cobra nada), replacement (ID de modelos de reemplazo recomendados, en orden de preferencia), reason, announced_at y info_url. En caso contrario, se establece null.
upcoming_price_changesarray: Cambios de precio programados por nivel que aún no se aplican: tier, effective_at, current_price_usd y el nuevo precio price_usd por unit. Las solicitudes anteriores a effective_at pagan el precio actual; nunca se modifica el precio de una generación después de enviarla. Vacío cuando no hay cambios programados.
warningsarray: Las respuestas de «Enviar una generación» y «Consultar un precio» incluyen estos avisos solo cuando hay información relevante: model_deprecated (con sunset_at y replacement) o price_change_scheduled para el nivel de la solicitud (con effective_at y el nuevo price_usd). Cada uno incluye un message legible y un info_url.

Solicitud

curl https://cheapergen.com/api/v1/models/bytedance/seedance-2.0-fast

Respuesta · 200 OK

{
  "id": "bytedance/seedance-2.0-fast",
  "object": "model",
  "…": "…",
  "deprecation": {
    "sunset_at": "2026-11-20T00:00:00.000Z",
    "replacement": [
      "bytedance/seedance-2.0-fast"
    ],
    "reason": "El desarrollador retirará este modelo.",
    "announced_at": "2026-10-21T09:30:00.000Z",
    "info_url": "https://cheapergen.com/changelog#cm2x7k9"
  },
  "upcoming_price_changes": [
    {
      "tier": "720p",
      "effective_at": "2026-11-04T00:00:00.000Z",
      "unit": "second",
      "current_price_usd": 0.08,
      "price_usd": 0.092,
      "change_pct": 15,
      "info_url": "https://cheapergen.com/changelog#cm2x8a1"
    }
  ]
}

Cabeceras HTTP Deprecation y Sunset#

Mientras la retirada de un modelo esté programada, las respuestas relacionadas —POST /run, POST /quote y GET /models/{vendor}/{model}— incluyen los encabezados estándar, para que los clientes HTTP y las puertas de enlace de API puedan registrarlos o generar alertas:

Cabeceras de respuesta

Deprecation: @1792575000
Sunset: Fri, 20 Nov 2026 00:00:00 GMT
Link: <https://cheapergen.com/changelog#cm2x7k9>; rel="deprecation"; type="text/html", <https://cheapergen.com/changelog#cm2x7k9>; rel="sunset"; type="text/html"

Deprecation (RFC 9745) es la hora en que se anunció la retirada, como marca de tiempo Unix; Sunset (RFC 8594) indica cuándo dejan de atenderse las solicitudes. Cambiar de modelo requiere una sola línea: envía la misma solicitud al endpoint del modelo de reemplazo (consulta su esquema de entrada por si hay opciones distintas).

A través de MCP, list_models y get_model incluyen los mismos campos deprecation y upcoming_price_changes, además de un notice de una línea, para que los agentes puedan avisar al usuario antes de depender de un modelo que se va a retirar.

Consultar un precio#

POST/api/v1/quote/{endpoint}Público · sin autenticación

Calcula el precio de una entrada sin ejecutarla. Solo se leen los campos que afectan al precio (resolución, duración, tamaño, cantidad de imágenes…); se ignoran los campos de contenido como prompt y las URL de referencia, y los campos omitidos usan sus valores predeterminados. available es false si el modelo no acepta generaciones temporalmente.

Los videos de referencia añaden segundos facturables. Para incluirlos, envía reference_video_durations (segundos, un número por clip) como estimación; /run mide los archivos reales y reserva ese precio. Consulta Facturación.

Solicitud

curl -X POST https://cheapergen.com/api/v1/quote/bytedance/seedance-2.0-fast/text-to-video \
  -H "Content-Type: application/json" \
  -d '{"aspect_ratio":"16:9","resolution":"720p","duration":5}'

Respuesta · 200 OK

{
  "amount_usd": 0.4494,
  "list_usd": 0.6048,
  "list_price_source": "official",
  "list_price_label": "Official",
  "discount_pct": 26,
  "available": true,
  "currency": "usd"
}

Envía tu clave de API para obtener tu precio. Si tu cuenta tiene uno —un precio de contrato o un Plan Pro o Max—, la cotización también incluye custom_price: true y standard_amount_usd (el precio habitual), además de volume_level (1 o 2) cuando lo fija el plan Pro (1) o Max (2).

Consultar tu cuenta#

GET/api/v1/accountSe requiere una clave de API

Devuelve tu saldo y la configuración de recarga automática. balance_usd es el importe disponible para gastar ahora; image_credit_usd es un crédito exclusivo para imágenes (por ejemplo, un crédito de bienvenida) que se aplica a modelos de imagen antes que tu saldo y nunca a video; reserved_usd es el importe reservado de tu saldo para las generaciones en curso. Consulta Facturación y créditos.

Solicitud

curl https://cheapergen.com/api/v1/account \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY"

Respuesta · 200 OK

{
  "object": "account",
  "email": "you@company.com",
  "balance_usd": 42.5,
  "image_credit_usd": 0,
  "reserved_usd": 1.2,
  "auto_topup": {
    "enabled": true,
    "threshold_usd": 10,
    "amount_usd": 50
  },
  "limits": {
    "unlimited": false,
    "concurrent_generations": 20,
    "in_flight": 3,
    "requests_per_second": 10,
    "burst": 20,
    "tier": null
  }
}

limits son los límites de la API de tu cuenta y cuántas de sus generaciones están en curso; si la cuenta no tiene límites, valen null, con unlimited: true. Consulta Límites de solicitudes.

Consulta tus precios#

GET/api/v1/account/pricingSe requiere una clave de API

Devuelve tu plan mensual, el nivel de volumen que te da acceso y tu precio propio por nivel, junto al precio estándar. Añade ?model={vendor}/{model} para un modelo. El pago por uso no requiere plan: en ese caso, plan es null y custom es false. Consulta Planes mensuales.

customboolean: true cuando un plan Pro o Max o un precio de contrato reduce alguno de tus precios.
planobject | null: Tu plan mensual: { "id", "status" }, por ejemplo, pro y active (starter, pro o max). null si no tienes uno.
volumeobject: level: 1 mientras Pro esté activo, 2 mientras Max esté activo; en los demás casos, null.
rulesarray: Tus precios de contrato, activos y programados: scope, status, discount_pct o unit_price_usd, starts_at, ends_at, y un description legible.
modelsarray: Cada modelo que cubre tu plan o una regla: id, name, unit y tiers; cada uno con price_usd (el tuyo), standard_price_usd, custom, volume_level (cuando lo fija el plan) y available.

Solicitud

curl "https://cheapergen.com/api/v1/account/pricing?model=bytedance/seedance-2.0-fast" \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY"

Respuesta · 200 OK

{
  "object": "customer_pricing",
  "custom": true,
  "plan": {
    "id": "pro",
    "status": "active"
  },
  "volume": {
    "level": 1
  },
  "rules": [],
  "models": [
    {
      "id": "bytedance/seedance-2.0-fast",
      "name": "Seedance 2.0 Fast",
      "unit": "second",
      "tiers": [
        "…"
      ]
    }
  ]
}

Subir un archivo#

POST/api/v1/uploadsSe requiere una clave de API

Sube un archivo para usar su URL como entrada: un fotograma inicial, una imagen, un video o un clip de audio de referencia. También puedes usar directamente cualquier URL pública HTTPS, sin subir el archivo.

Tipo	Formatos	Tamaño máximo
Imagen	PNG, JPEG, WebP, GIF	20 MB
Video	MP4, MOV	50 MB
Audio	MP3, WAV, M4A (actualmente los modelos aceptan MP3 o WAV)	15 MB

Carga directa (recomendada)#

Envía JSON con el filename, content_type y size del archivo, en bytes. Recibirás un upload_url de corta duración; envía los bytes sin procesar con PUT, exactamente según el valor devuelto de headers, y luego usa url como entrada. El archivo se envía directamente al almacenamiento, así que no hay límite de tamaño de solicitud además de los límites indicados arriba. La URL de carga caduca a los 15 minutos. size debe ser el tamaño exacto del archivo en bytes: envía con PUT exactamente esa cantidad de bytes y con Content-Length (sin cuerpo chunked ni en streaming). El almacenamiento responde 403 a cualquier otra cosa.

Solicitud

curl -X POST https://cheapergen.com/api/v1/uploads \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename":"choreo.mp4","content_type":"video/mp4","size":8421903}'

Respuesta · 201 Created

{
  "object": "upload",
  "method": "PUT",
  "upload_url": "https://storage.example.com/media/uploads/7f3k2m9q/0b8d2c5e1a7f4h6j9k3m.mp4?X-Amz-Algorithm=AWS4-HMAC-SHA256&…",
  "headers": {
    "Content-Type": "video/mp4"
  },
  "url": "https://cdn.cheapergen.com/uploads/7f3k2m9q/0b8d2c5e1a7f4h6j9k3m.mp4",
  "kind": "video",
  "content_type": "video/mp4",
  "bytes": 8421903,
  "expires_at": "2026-10-15T09:36:04.000Z"
}

Ahora, sube los bytes

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: video/mp4" \
  --data-binary @choreo.mp4

Carga multipart#

Otra opción es enviar multipart/form-data con un campo file para que guardemos el archivo por ti (201 Created con url). Esto hace pasar los bytes por nuestra API, donde el cuerpo de la solicitud está limitado a unos 4.5 MB; usa la carga directa para archivos más grandes. Si una implementación no admite la carga directa, la solicitud JSON devuelve 501 direct_upload_unavailable; usa multipart como alternativa.

Solicitud

curl -X POST https://cheapergen.com/api/v1/uploads \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY" \
  -F "file=@first-frame.png"

Respuesta · 201 Created

{
  "object": "upload",
  "url": "https://cdn.cheapergen.com/uploads/7f3k2m9q/0b8d2c5e1a7f4h6j9k3m.png",
  "kind": "image",
  "content_type": "image/png",
  "bytes": 1834221
}

Usar una imagen subida#

Pasa la URL devuelta en el campo image de un endpoint de imagen a video o de edición:

curl -X POST https://cheapergen.com/api/v1/run/bytedance/seedance-2.0-fast/image-to-video \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "La cámara se acerca mientras ella se vuelve y sonríe; el viento le mueve el cabello",
  "image_url": "https://cdn.cheapergen.com/uploads/7f3k2m9q/0b8d2c5e1a7f4h6j9k3m.png",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "duration": 5
}'

Referencia por modelo

Cada modelo tiene su propia página de la API, con el tipo, el valor predeterminado y los valores permitidos de cada campo, además de ejemplos listos para copiar y pegar. Empieza en lista de modelos.

¿Algo no está claro o falta información? Escribe a support@cheapergen.com; leemos todos los mensajes.