Inicio rápido

Elija un modelo y un endpoint en el Catálogo y envíe las entradas requeridas por el endpoint. Este ejemplo inicia una Tarea de texto a imagen con Flux 2:

Una solicitud asíncrona aceptada devuelve 202 Accepted con un identificador de tarea:

Guarde id junto con el registro de su aplicación. Es el identificador estable que se usa para el sondeo, el soporte y la reconciliación de devoluciones de llamada.

Los endpoints de creación de tareas aceptan un encabezado opcional Idempotency-Key con un valor opaco de hasta 512 caracteres. Genera un valor por cada tarea lógica y consérvalo con la solicitud hasta saber si fue aceptada.

Si un tiempo de espera o un fallo de conexión deja el resultado desconocido, reintente la misma solicitud de creación de Task con la misma clave. RunAPI devuelve el Task original en lugar de crear y cobrar por uno nuevo. Reutilizar una clave con una solicitud de creación de Task diferente devuelve 409 Conflict. Genere una nueva clave para un Task intencionalmente nuevo y no use X-Client-Request-Id como esta clave.

Los endpoints síncronos lentos normalmente mantienen la conexión abierta y devuelven la misma respuesta terminal que antes. No se requieren cambios de sondeo para las integraciones existentes.

Para un presupuesto de conexión intencionalmente más corto, envíe Prefer: wait=N. Si la tarea aún está en ejecución después de ese presupuesto explícito, RunAPI devuelve 202 Accepted con el mismo id de tarea, una URL opaca Location para recuperación y Retry-After con el retraso de consulta sugerido. Siga Location exactamente en lugar de construir una URL de resultado. Un resultado de tarea completada preserva el estado HTTP terminal, los encabezados permitidos, el tipo de contenido y el cuerpo; decodifique response.body según response.content_type, que no siempre es JSON.

Agrega el identificador de la tarea a la misma ruta del endpoint:

Continúe mientras status sea processing. Use un retroceso acotado entre solicitudes en lugar de consultar continuamente. Una Tarea se vuelve terminal cuando su estado es completed o failed.

Una respuesta completed incluye el id de la tarea, el status terminal y los campos de resultado específicos del endpoint. Conserva el resultado que necesitas y deja de hacer polling. Consulta la Referencia de la API del endpoint para conocer la estructura exacta del resultado en lugar de asumir que todos los endpoints de medios devuelven los mismos campos.

Una respuesta failed incluye el id de la tarea, el status terminal y un error generado por RunAPI cuando está disponible. Deja de hacer polling, registra el identificador y el error, y reintenta solo cuando tu aplicación haya clasificado el fallo como transitorio. Un reintento crea un nuevo identificador de tarea.

Agrega una callback_url HTTPS pública a la solicitud de creación cuando quieras que RunAPI envíe los eventos de devolución de llamada documentados para ese endpoint:

Cada cuerpo de devolución de llamada coincide con un evento del ciclo de vida en la Referencia de la API del endpoint y omite los detalles de facturación exclusivos del sondeo. Las devoluciones de llamada terminales incluyen los mismos campos de resultado que las respuestas de sondeo terminales; algunos endpoints también envían devoluciones de llamada processing documentadas. Devuelva una respuesta HTTP exitosa rápidamente y mantenga el sondeo disponible para la reconciliación cuando la entrega se retrase o su manejador de devoluciones de llamada no esté disponible.

Lea Devoluciones de llamada para crear un secreto de devolución de llamada, verificar firmas y gestionar los reintentos de forma segura.