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 Media Input Fields son los campos de la solicitud que contienen URL de medios: los campos de nivel superior cuyo nombre termina en _url o _urls, como image_url o image_urls, la url de cada elemento de video_list, y element_input_urls, element_input_video_urls y element_input_audio_urls de cada elemento de kling_elements. callback_url es un endpoint de entrega, no un Media Input Field. Cada valor de un Media Input Field puede ser una URL HTTPS pública o un data URI con el formato data:<mime>;base64,<data>, de hasta 10 MB por data URI. RunAPI guarda cada data URI como un File Upload temporal que caduca después de una hora y usa ese upload para la Task. Un data URI que no se puede guardar devuelve 422 con el código de error invalid_media_input.

Los endpoints de edición de GPT Image solo aceptan URL HTTPS en source_image_urls. Para enviar una imagen local a estos endpoints, cree primero un File Upload y pase la URL devuelta.

Para archivos de más de 10 MB, cree primero un File Upload con POST /api/v1/files y pase la URL devuelta. Un File Upload multipart o con origen URL acepta archivos de hasta 50 MB. Las URL de File Upload también caducan después de una hora, así que cree un nuevo File Upload para cada Task que empiece después de ese plazo.

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 Task, el status terminal, los campos de resultado específicos del endpoint y usage.cost como un importe float USD de esa Task. 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.

Los envelopes de Task de creación, processing y failed omiten usage.

Las tareas que requieren una liquidación final basada en los archivos multimedia permanecen en processing hasta que se registra su cargo final. El callback de finalización se envía solo después de esa liquidación; su usage.cost coincide con el de las consultas posteriores de la tarea. Los datos contables faltantes no se presentan como cero: la tarea permanece en processing mientras se concilian esos datos. Un cargo de cero confirmado se devuelve como usage.cost: 0.

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. Un callback completed comparte usage.cost con la respuesta de sondeo completed; los callbacks de creación, processing y failed omiten usage. 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.

UtilicePOST /api/v1/vidu/image_to_videoconmodel: "vidu-q4-image-to-video"yfirst_frame_image_url. UtilicePOST /api/v1/vidu/reference_to_videoconmodel: "vidu-q4-reference-to-video", unpromptque no esté en blanco y 1–15reference_image_urlsordenados. Recupere cada tarea conGETen su ruta de creación seguido de/:id. Las tareas completadas contienen una matrizvideosde URL de resultados. También puede proporcionarcallback_urlpara notificaciones de finalización.

Ambos puntos finales aceptan el número enteroduration_secondsde 3 a 16, por defecto 5, youtput_resolutionde540p,720p,1080p,2ko4k, por defecto720p.audioes un booleano JSON, por defectotrue; Elfalseexplícito desactiva el audio generado. Las indicaciones aceptan hasta 20.000 caracteres. El mensaje de imagen a vídeo es opcional y el primer fotograma determina su relación de aspecto. La referencia a video aceptaaspect_ratiode16:9,9:16,1:1,4:3o3:4, el valor predeterminado16:9y hasta 3reference_audio_urls.

Utilice URL de medios públicasHTTP(S). Las imágenes deben serJPG/JPEG,PNGoWEBP; la imagen del primer fotograma no debe tener más de 50 MB. Cada archivo de audio de referencia debe serMP3, tener entre 3 y 12 segundos de duración y no superar los 50 MB.RunAPIcomprueba los tipos de campos, los esquemas de URL y los recuentos de referencias. El proveedor de generación comprueba el formato, el tamaño y la duración del audio de los medios remotos de forma asincrónica. Los medios no válidos pueden hacer que la tarea falle a través del flujo normal de fallas y reembolsos.

Precios de imagen a vídeo. Precios de referencias a vídeo.