Integración en producción

Usa esta página como lista de comprobación antes de que usuarios reales o dinero real dependan de tu integración. Cada sección explica qué hacer, por qué importa y dónde están los detalles. Si todavía no has hecho una primera llamada, empieza por Configura tu cuenta y el inicio rápido.

Elige un modelo y un protocolo

• Elige un modelo que tu clave pueda llamar de verdad. Llama a GET /api/v1/models con tu clave de API y usa solo modelos que tengan enabled y available en true. Lee en esa misma respuesta el inputSchema del modelo (la lista de campos que acepta) y sus examples. La página de un modelo en el sitio web te dice qué puede hacer; no demuestra que tu clave pueda llamarlo en este momento. Consulta Modelos.
• Usa el punto de entrada correcto. Las tareas de imagen, video y otros medios usan la API de tareas bajo /api/v1 (createTask y después recordInfo o un callback). Los modelos de texto también se pueden llamar con clientes compatibles con OpenAI o Anthropic bajo /v1, o con clientes compatibles con Gemini bajo /v1beta. Consulta Texto y streaming.
• Autentícate solo con una clave de API. La cookie de inicio de sesión de la consola no es una credencial de API y nunca debe copiarse en el código.

Protege tus claves y tu saldo

• Deja la clave en tu servidor. Ponla en una variable de entorno (SPICY_API_KEY) de tu backend, nunca en código del navegador, en aplicaciones móviles ni en un repositorio público. Consulta Autenticación.
• Una clave por entorno y por servicio. Ponle a cada clave el nombre de lo que la usa (por ejemplo, «production-worker»), para poder revocar una sin detener las demás.
• Pon límites a la clave de producción: un límite diario pensado para un mal día, un presupuesto mensual, modelos permitidos y, para las llamadas desde el servidor, una lista de IP permitidas. Consulta las restricciones por clave. Al editar una clave, recuerda que un límite vacío significa que no hay límite.
• Revisa las fechas de caducidad. Una clave con fecha de caducidad deja de funcionar al final de ese día (UTC) y devuelve el mismo 401 que una clave revocada. Anota la fecha en tu calendario, o no pongas ninguna en un backend que vaya a funcionar mucho tiempo.
• No te quedes sin dinero a mitad de un lote. Una tarea rechazada por falta de saldo devuelve 40201 y nunca entra en la cola. Activa el Aviso de saldo bajo en Notificaciones y plantéate usar la recarga automática.
• Los límites del equipo también cuentan. Si tu clave pertenece a un equipo, los límites diario y mensual del equipo pueden detener tareas con 40202 aunque no se hayan alcanzado los límites de la propia clave, y todas las tareas se pagan con el saldo del propietario del equipo. Consulta Límites de gasto.
• Planifica la rotación de la clave de firma de webhooks. Rotar la clave en la consola no deja ningún periodo de solapamiento: la clave antigua deja de firmar de inmediato. Las entregas que todavía se están reintentando se firman con la clave nueva. Rota en un momento tranquilo, despliega la clave nueva en tu receptor enseguida y recupera con recordInfo lo que se haya perdido. Consulta Webhooks.

Prepara la entrada en tu servidor

• Valida contra el esquema actual. Respeta los tipos de campo, los valores permitidos y los requisitos condicionales de inputSchema, y vuelve a validar después de cambiar de modelo: cada modelo tiene el suyo.
• Envía los medios de una forma admitida. Usa una URL https:// accesible públicamente o una entrada Base64 admitida. Para archivos locales, pide una URL de subida, envía los bytes con PUT, llama a files/{fileId}/commit y pasa la URI spicy:// devuelta en el campo de entrada del modelo. Consulta Carga y descarga de medios.
• Usa cada archivo subido mientras siga vigente. Una URI spicy:// funciona hasta el expiresAt que indica la respuesta del commit (1 día de forma predeterminada). No pidas URL de subida en bloque si no las vas a usar: las que no se usan cuentan para un límite. Consulta Límites de solicitudes.

Cotiza antes de aceptar un cobro

• Muestra el precio antes de gastar dinero. Envía model, input y callBackUrl completos a POST /api/v1/jobs/quote. Muestra a la persona que paga estimatedCost, maxCharge, la moneda (USD) y expiresAt. Una cotización es gratuita: no crea ninguna tarea ni retiene fondos.
• Envía lo que se confirmó. Una cotización dura cinco minutos. Tras la confirmación, envía la misma solicitud a createTask añadiendo quoteId y expectedCost.
• Gestiona 40901. Significa que la cotización caducó, que la entrada cambió o que el precio cambió desde que se hizo la cotización. Pide una cotización nueva y muestra el importe nuevo; nunca aceptes en silencio uno más alto. Consulta Cotizaciones.
• Mantén los importes exactos. Los importes son cadenas decimales como "0.008". Guárdalos y súmalos con aritmética decimal, no de coma flotante. Consulta Facturación.

Guarda la operación de negocio

Tus propios registros son lo que te permite recuperarte cuando una llamada de red falla a medias.

• Guarda antes de enviar: tu propio ID de pedido u operación, una descripción breve de la solicitud que no contenga secretos ni prompts completos (lo justo para reconocerla más adelante) y el Idempotency-Key que vas a enviar.
• Guarda después de la aceptación: el taskId y el request_id de la respuesta.
• Reutiliza la clave de idempotencia para el mismo envío. Vuelve a enviar el Idempotency-Key original para la misma cuenta, la misma clave de API y la misma solicitud en menos de 24 horas; recibes la tarea original en lugar de un segundo cobro. Consulta Idempotencia.
• Trata un timeout como «desconocido», no como «fallido». Recupera el envío original con su clave de idempotencia antes de decidir crear uno nuevo. Consulta Diagnóstico y recuperación.
• Ten claro lo que cuesta un reintento. Reintentar una tarea que ya falló crea una tarea nueva, con las condiciones y los precios del momento.

Gestiona los callbacks y los resultados de forma fiable

• Verifica cada callback. Comprueba la firma y la marca de tiempo sobre los bytes originales de la solicitud antes de interpretarla; después, elimina duplicados y guarda el evento. Consulta Webhooks.
• Confirma la recepción rápido. Responde con un 2xx de inmediato y haz el trabajo lento en tu propia cola.
• Cuenta con duplicados y retrasos. Decide qué hacer a partir del state de la tarea, no del orden en que llegan los callbacks.
• Mantén el sondeo como respaldo. Si un callback se retrasa, lee recordInfo con pausas cada vez más largas en lugar de hacerlo cada segundo.
• Lee la señal correcta. HTTP 202 en createTask significa que la tarea se aceptó. state: "succeeded" significa que la generación terminó. settled: true significa que el cobro es definitivo.

Acota la concurrencia y conserva los resultados

• Limita las tareas en curso por cuenta y pon plazos a tus propias solicitudes. Cada tarea aceptada retiene fondos hasta que se liquida.
• Respeta Retry-After cuando recibas 429, y evita que muchos clientes sondeen sincronizados cada segundo. Consulta Límites de solicitudes.
• Guarda en caché los datos del catálogo por poco tiempo y de forma privada, y nunca trates una cotización como una lista de precios permanente.
• Archiva los resultados que necesites conservar. Los enlaces de descarga duran 20 minutos; los medios generados se guardan como máximo unos 14 días y las subidas, un día. Puedes acortar esos plazos o borrar antes el contenido de una tarea con POST /api/v1/jobs/purge. Acortar un ajuste de conservación también puede eliminar resultados de tareas que ya ejecutaste; consulta Conservación.
• No confíes en desconectarte para detener el trabajo. Una tarea aceptada sigue ejecutándose y no se puede cancelar.

Valida antes del lanzamiento

Empieza por las llamadas gratuitas: el catálogo (GET /api/v1/models), tu saldo (GET /api/v1/chat/credit) y una cotización. Después ejecuta una generación real pequeña a través de tu propio flujo de confirmación de costos; se cobra como cualquier otra tarea. Comprueba que tu integración gestiona cada uno de estos casos:

Registra request_id, taskId, la hora, el state y los importes. Mantén las claves de API y los prompts completos fuera de los registros generales.

Flujos relacionados

Cotizaciones y compatibilidad de protocolos · Catálogo de modelos y esquemas · Carga y descarga de medios · Webhooks · Errores · Diagnóstico y recuperación · Facturación · Conservación