Cola

Para las solicitudes que tardan más de unos segundos, típicas en aplicaciones de IA, hemos desarrollado un sistema de colas. Este sistema te ofrece un control detallado para gestionar los aumentos de tráfico, cancelar solicitudes si es necesario y supervisar el estado de tu solicitud en la cola. También elimina la necesidad de manejar solicitudes HTTP de larga duración.

Endpoints de la Cola

Puedes acceder a todas las funciones de la cola a través de los siguientes endpoints:

Endpoint	Método	Descripción
api.sunra.ai/v1/queue/{model-id}	POST	Agrega una solicitud a la cola
api.sunra.ai/v1/queue/requests/{request_id}/status	GET	Recupera el estado de una solicitud
api.sunra.ai/v1/queue/requests/{request_id}/status/stream	GET	Transmite el estado hasta su finalización
api.sunra.ai/v1/queue/requests/{request_id}	GET	Obtiene la respuesta de una solicitud
api.sunra.ai/v1/queue/requests/{request_id}/cancel	PUT	Cancela una solicitud

Por ejemplo, para enviar una solicitud usando curl y agregarla a la cola:

curl -X POST \
  https://api.sunra.ai/v1/queue/black-forest-labs/flux-1.1-pro/text-to-image \
  -H "Authorization: Key $SUNRA_KEY" \
  -d '{"prompt": "A Studio Ghibli-inspired seaside town with colorful houses, laundry flapping, and cats sleeping on windowsills."}'

Aquí hay una respuesta de muestra que incluye el request_id:

{
  "request_id": "pd_vXW7VwPN2MbTwT8bzpWrYU5Y",
  "response_url": "https://api.sunra.ai/v1/queue/requests/pd_vXW7VwPN2MbTwT8bzpWrYU5Y",
  "status_url": "https://api.sunra.ai/v1/queue/requests/pd_vXW7VwPN2MbTwT8bzpWrYU5Y/status",
  "cancel_url": "https://api.sunra.ai/v1/queue/requests/pd_vXW7VwPN2MbTwT8bzpWrYU5Y/cancel"
}

La carga útil incluye el request_id y proporciona URLs para verificar el estado, cancelar o recuperar la respuesta, agilizando tu flujo de trabajo sin necesidad de desarrollar endpoints adicionales.

Estado de la Solicitud

Para monitorear el progreso de tu solicitud, usa el endpoint proporcionado con tu ID de solicitud único. Esto te permite rastrear el estado, la posición en la cola o recuperar la respuesta una vez que esté lista.

Uso del Endpoint

curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}/status

Respuesta de Ejemplo

Cuando tu solicitud está en la cola, recibirás una respuesta como esta:

{
  "status": "IN_QUEUE",
  "metrics": {},
  "queue_position": 0,
  "response_url": "https://api.sunra.ai/v1/queue/requests/pd_hvTNHJPSZj4KgtzytfTGsySf",
  "status_url": "https://api.sunra.ai/v1/queue/requests/pd_hvTNHJPSZj4KgtzytfTGsySf/status",
  "cancel_url": "https://api.sunra.ai/v1/queue/requests/pd_hvTNHJPSZj4KgtzytfTGsySf/cancel"
}

Posibles Estados

Tu solicitud puede estar en uno de tres estados:

IN_QUEUE: Indica que la solicitud está esperando ser procesada.
- queue_position: Muestra tu lugar en la cola.
- response_url: URL para recuperar la respuesta una vez que se complete el procesamiento.
IN_PROGRESS: La solicitud se está procesando actualmente.
- logs: Registros detallados (si están habilitados) que muestran los pasos del procesamiento.
- response_url: Dónde estará disponible la respuesta final.
COMPLETED: El procesamiento ha finalizado.
- logs: Registros que detallan todo el proceso.
- response_url: Enlace directo a tu respuesta completada.

Habilitando los Registros

Los registros proporcionan información sobre el procesamiento de la solicitud. Están deshabilitados por defecto, pero se pueden habilitar con un parámetro de consulta:

curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}/status?logs=1

Cada entrada de registro incluye:

message: Descripción del evento.
level: Gravedad (p. ej., INFO, ERROR).
source: Origen del registro.
timestamp: Hora en que se generó el registro.

Monitoreo en Tiempo Real

Para actualizaciones continuas, usa el endpoint de transmisión:

curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}/status/stream

Esto proporciona actualizaciones de estado en tiempo real en formato text/event-stream hasta que se complete la solicitud.

Webhooks

Si prefieres ser notificado en lugar de hacer polling, pasa un parámetro de consulta webhook al enviar una solicitud. Sunra hará un POST con el resultado final a esa URL una vez que la solicitud alcance un estado terminal, por lo que no necesitas mantener una conexión abierta ni programar polling.

Habilitando Webhooks

Añade un parámetro de consulta webhook codificado en URL al endpoint de envío:

curl -X POST \
  "https://api.sunra.ai/v1/queue/black-forest-labs/flux-1.1-pro/text-to-image?webhook=https%3A%2F%2Fexample.com%2Fsunra-webhook" \
  -H "Authorization: Key $SUNRA_KEY" \
  -d '{"prompt": "Un pueblo costero inspirado en Studio Ghibli con casas coloridas, ropa colgada al viento y gatos durmiendo en los alféizares."}'

Codifica la URL del webhook (por ejemplo, https%3A%2F%2F...) y asegúrate de que Sunra pueda alcanzarla; se recomienda encarecidamente HTTPS. La respuesta de envío no cambia: sigues recibiendo un request_id y las mismas URL de estado/cancelación/respuesta.

Cuándo se dispara el Webhook

Sunra llama a tu webhook solo en eventos terminales:

succeeded — la solicitud finalizó y la salida está incluida en el payload.
failed — la solicitud tuvo un error y los detalles del error están incluidos en el payload.

Los estados intermedios (IN_QUEUE, IN_PROGRESS) no disparan un webhook. Si también necesitas actualizaciones de progreso, combina el webhook con los endpoints de streaming o polling descritos arriba.

Formato de la Solicitud

Sunra envía una solicitud POST a tu URL de webhook con:

Header	Value
`Content-Type`	`application/json`
`User-Agent`	`Sunra-AI-Webhook/1.0`

Tu endpoint debe responder con un código de estado 2xx en menos de 5 segundos. Confirma rápido y traslada el trabajo pesado a un job en segundo plano: las respuestas lentas se tratan como fallos y disparan reintentos.

Payload

Un evento exitoso:

{
  "id": "pd_vXW7VwPN2MbTwT8bzpWrYU5Y",
  "object": "prediction",
  "model": "black-forest-labs/flux-1.1-pro",
  "model_endpoint": "text-to-image",
  "status": "succeeded",
  "input": {
    "prompt": "Un pueblo costero inspirado en Studio Ghibli..."
  },
  "output": {
    "images": [
      { "url": "https://..." }
    ]
  },
  "created_at": "2026-04-28T12:00:00.000Z",
  "completed_at": "2026-04-28T12:00:08.123Z"
}

Un evento fallido reemplaza output por error. El contenido exacto de error varía según el tipo de fallo — el ejemplo siguiente muestra una forma común:

{
  "id": "pd_vXW7VwPN2MbTwT8bzpWrYU5Y",
  "object": "prediction",
  "model": "black-forest-labs/flux-1.1-pro",
  "model_endpoint": "text-to-image",
  "status": "failed",
  "input": {
    "prompt": "Un pueblo costero inspirado en Studio Ghibli..."
  },
  "error": {
    "code": "EXAMPLE_ERROR_CODE",
    "message": "Mensaje de error legible"
  },
  "created_at": "2026-04-28T12:00:00.000Z",
  "completed_at": "2026-04-28T12:00:08.123Z"
}

Campo	Descripción
`id`	El `request_id` devuelto al enviar. Úsalo para deduplicar reintentos.
`object`	Siempre `"prediction"`.
`model`	El propietario y nombre del modelo (por ejemplo, `black-forest-labs/flux-1.1-pro`).
`model_endpoint`	El slug del endpoint (por ejemplo, `text-to-image`).
`status`	`"succeeded"` o `"failed"`.
`input`	El cuerpo de la solicitud original que enviaste.
`output`	Presente en `succeeded`. El mismo cuerpo de respuesta devuelto por el endpoint de resultados.
`error`	Presente en `failed`. Un objeto que describe el fallo; su estructura depende del tipo de fallo.
`created_at`	Marca de tiempo ISO 8601 de cuándo se creó la solicitud.
`completed_at`	Marca de tiempo ISO 8601 de cuándo la solicitud alcanzó el estado terminal.

Comportamiento de Reintentos

La entrega del webhook es al-menos-una-vez. Si tu endpoint excede el tiempo de espera (5 s) o devuelve un estado distinto a 2xx, Sunra reintenta con backoff exponencial — hasta 3 reintentos con retrasos comenzando en 10 segundos y limitados a 30 segundos. Después del último reintento, el fallo se registra y no se realizan más intentos. Como los reintentos pueden entregar el mismo evento más de una vez, tu manejador debe ser idempotente — usa el campo id como clave de deduplicación.

Buenas Prácticas

Usa HTTPS y verifica que el tráfico llegue al endpoint que esperas.
Responde 2xx inmediatamente y procesa el payload de forma asíncrona.
Trata la entrega como al-menos-una-vez y deduplica por id.
Combina los webhooks con los endpoints de polling o streaming si necesitas actualizaciones de progreso antes del evento terminal.

Cancelando Solicitudes

Si tu solicitud todavía está en cola, puedes cancelarla con:

curl -X PUT https://api.sunra.ai/v1/queue/requests/{request_id}/cancel

Recuperando Respuestas

Una vez que tu solicitud esté COMPLETED, recupera la respuesta usando:

curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}

Este endpoint también proporciona registros para su revisión.

Integración Simplificada con el Cliente de Sunra

El cliente de Sunra automatiza el seguimiento del estado, simplificando el desarrollo de aplicaciones con las funciones de Sunra.

Límites de Tasa

Para garantizar un uso justo y la estabilidad del sistema, nuestros endpoints de API están sujetos a los siguientes límites de tasa:

Tipo de Endpoint	Límite de Tasa	Límite de Ráfaga
Enviar a la Cola	10 solicitudes/segundo	100 solicitudes/minuto
Todos los demás Endpoints	100 solicitudes/segundo	1,800 solicitudes/minuto

Si excedes estos límites, recibirás una respuesta 403 Forbidden. Recomendamos implementar un mecanismo de reintento con retroceso exponencial para manejar estos casos.

Descripción general

Multimodal

LLM

Bibliotecas de cliente

Endpoints de la Cola

Estado de la Solicitud

Uso del Endpoint

Respuesta de Ejemplo

Posibles Estados

Habilitando los Registros

Monitoreo en Tiempo Real

Webhooks

Habilitando Webhooks

Cuándo se dispara el Webhook

Formato de la Solicitud

Payload

Comportamiento de Reintentos

Buenas Prácticas

Cancelando Solicitudes

Recuperando Respuestas

Integración Simplificada con el Cliente de Sunra

Límites de Tasa

​Endpoints de la Cola

​Estado de la Solicitud

​Uso del Endpoint

​Respuesta de Ejemplo

​Posibles Estados

​Habilitando los Registros

​Monitoreo en Tiempo Real

​Webhooks

​Habilitando Webhooks

​Cuándo se dispara el Webhook

​Formato de la Solicitud

​Payload

​Comportamiento de Reintentos

​Buenas Prácticas

​Cancelando Solicitudes

​Recuperando Respuestas

​Integración Simplificada con el Cliente de Sunra

​Límites de Tasa

Endpoints de la Cola

Estado de la Solicitud

Uso del Endpoint

Respuesta de Ejemplo

Posibles Estados

Habilitando los Registros

Monitoreo en Tiempo Real

Webhooks

Habilitando Webhooks

Cuándo se dispara el Webhook

Formato de la Solicitud

Payload

Comportamiento de Reintentos

Buenas Prácticas

Cancelando Solicitudes

Recuperando Respuestas

Integración Simplificada con el Cliente de Sunra

Límites de Tasa