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:
EndpointMétodoDescripción
api.sunra.ai/v1/queue/{model-id}POSTAgrega una solicitud a la cola
api.sunra.ai/v1/queue/requests/{request_id}/statusGETRecupera el estado de una solicitud
api.sunra.ai/v1/queue/requests/{request_id}/status/streamGETTransmite el estado hasta su finalización
api.sunra.ai/v1/queue/requests/{request_id}GETObtiene la respuesta de una solicitud
api.sunra.ai/v1/queue/requests/{request_id}/cancelPUTCancela 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.

​
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 EndpointLímite de TasaLímite de Ráfaga
Enviar a la Cola10 solicitudes/segundo100 solicitudes/minuto
Todos los demás Endpoints100 solicitudes/segundo1,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.