> ## Documentation Index > Fetch the complete documentation index at: https://docs.sunra.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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: ```bash theme={null} 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`: ```json theme={null} { "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 ```bash theme={null} 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: ```json theme={null} { "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: ```bash theme={null} 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: ```bash theme={null} 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: ```bash theme={null} 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: ```json theme={null} { "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: ```json theme={null} { "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: ```bash theme={null} 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: ```bash theme={null} 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.