> ## Documentation Index > Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt > Use this file to discover all available pages before exploring further. # Instrucciones para la integración de la API de generación de videos Sora > Sora Video Generation 集成指南 - XHuoAPI Este documento presenta las instrucciones para la integración de la API de generación de videos Sora. A través de esta API, se pueden ingresar parámetros personalizados para generar videos oficiales de Sora. Esta API soporta dos modos de versión: * **Versión 1 (modo clásico)**: soporta parámetros como `duration` (10/15/25 segundos), `orientation` (horizontal/vertical), `size` (small/large resolución), imágenes de referencia `image_urls`, enlace de personaje `character_url`, entre otros. * **Versión 2 (modo para socios)**: soporta `seconds` (4/8/12 segundos), resolución a nivel de píxel `size` (por ejemplo, 1280x720), imágenes de referencia `input_reference`, entre otros parámetros. ## Proceso de solicitud Para usar la API, primero debe solicitar el servicio correspondiente en la página [Sora Videos Generation API](https://api.xhuoapi.ai/documents/99a24421-2e22-4028-8201-e19cb834b67e). Al ingresar a la página, haga clic en el botón "Acquire", como se muestra en la imagen: ![](https://cdn.xhuoapi.ai/q6ytrc.png) Si aún no ha iniciado sesión o registrado, será redirigido automáticamente a la página de inicio de sesión para registrarse o ingresar. Tras iniciar sesión o registrarse, volverá automáticamente a esta página. Al solicitar por primera vez, se otorgará un crédito gratuito para usar la API sin costo. ## Uso básico (Versión 1) Primero, conozca la forma básica de uso de la Versión 1, que consiste en ingresar el prompt `prompt`, un arreglo de URLs de imágenes de referencia `image_urls` y el modelo `model` para obtener el resultado procesado. El contenido específico es el siguiente:

Aquí configuramos los encabezados de la solicitud (Request Headers), que incluyen: * `accept`: el formato de respuesta deseado, aquí se usa `application/json` para formato JSON. * `authorization`: la clave para llamar a la API, que puede seleccionarse tras la solicitud. Además, configuramos el cuerpo de la solicitud (Request Body), que incluye: * `model`: modelo para generar el video, soporta `sora-2` (modo estándar) y `sora-2-pro` (modo HD). `sora-2-pro` soporta videos de 25 segundos, mientras que `sora-2` solo 10 o 15 segundos (solo Versión 1). * `size`: resolución del video, `small` para estándar, `large` para HD (solo Versión 1). * `duration`: duración del video, soporta 10, 15 o 25 segundos; 25 segundos solo para `sora-2-pro` (solo Versión 1). * `orientation`: orientación del video, soporta `landscape` (horizontal) y `portrait` (vertical) (solo Versión 1). * `image_urls`: arreglo de URLs de imágenes de referencia para generación de video a partir de imágenes (solo Versión 1). * `character_url`: enlace de personaje, el video no debe contener personas reales (solo Versión 1). * `character_start`/`character_end`: segundos de inicio y fin de aparición del personaje, rango de 1 a 3 segundos (solo Versión 1). * `prompt`: prompt o texto de entrada (obligatorio). * `callback_url`: URL para callback asíncrono. * `version`: versión de la API, `"1.0"` (por defecto) o `"2.0"`. Al seleccionar, se genera el código correspondiente a la derecha, como se muestra:

Haga clic en el botón "Try" para probar. Como en la imagen, obtuvimos el siguiente resultado: ```json theme={null} { "success": true, "task_id": "6bf7fb83-5814-4e3e-a4ad-bfa0c26c0b33", "trace_id": "96166698-4b66-478d-a26b-77a7269c9e01", "data": [ { "id": "sora-2:task_01k7770rgsevxsmtpbn7xnm5gh", "video_url": "https://filesystem.site/gptimage/vg-assets/assets%2Ftask_01k7770rgsevxsmtpbn7xnm5gh%2Ftask_01k7770rgsevxsmtpbn7xnm5gh_genid_0bf958d3-cae7-4298-b7b6-99ae439a1ea6_25_10_10_14_06_975715%2Fvideos%2F00000%2Fsrc.mp4?st=2025-10-10T12%3A30%3A38Z&se=2025-10-16T13%3A30%3A38Z&sks=b&skt=2025-10-10T12%3A30%3A38Z&ske=2025-10-16T13%3A30%3A38Z&sktid=a48cca56-e6da-484e-a814-9c849652bcb3&skoid=8ebb0df1-a278-4e2e-9c20-f2d373479b3a&skv=2019-02-02&sv=2018-11-09&sr=b&sp=r&spr=https%2Chttp&sig=jigY6Z5qp8%2BTXYobaW0EAJ4%2Fbx6G7t6V1P0iyDeUq48%3D&az=oaivgprodscus", "state": "succeeded" } ] } ``` El resultado contiene varios campos, que se describen a continuación: * `success`: estado de la tarea de generación de video. * `task_id`: ID de la tarea de generación de video. * `trace_id`: ID de seguimiento de la tarea. * `data`: lista de resultados de la tarea. * `id`: ID del video generado. * `video_url`: URL del video generado. * `state`: estado de la tarea. Como se observa, obtuvimos la información del video generado, solo debe usar la URL en `data` para obtener el video de Sora generado. Además, si desea generar el código de integración correspondiente, puede copiarlo directamente. Por ejemplo, el código CURL es: ```shell theme={null} curl -X POST 'https://api.xhuoapi.ai/v1/sora/videos' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "size": "large", "duration": 15, "orientation": "landscape", "prompt": "cat running on the river", "model": "sora-2" }' ``` ## Tarea de generación de video a partir de imágenes (Versión 1) Para realizar una tarea de generación de video a partir de imágenes, debe pasar el parámetro `image_urls` con las URLs de las imágenes de referencia, especificando lo siguiente: * `image_urls`: arreglo de URLs de imágenes de referencia para la tarea de generación de video a partir de imágenes. No se deben enviar imágenes con rostros reales, ya que podría causar fallo en la tarea. Ejemplo de llenado:

Después de llenar, se genera automáticamente el siguiente código:

Código correspondiente: ```python theme={null} import requests url = "https://api.xhuoapi.ai/v1/sora/videos" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "size": "large", "duration": 15, "orientation": "landscape", "prompt": "cat running on the river", "model": "sora-2", "image_urls": ["https://cdn.xhuoapi.ai/11wfp4.png"] } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` Al ejecutar, se obtiene inmediatamente un resultado como el siguiente: ``` { "success": true, "task_id": "dd392ff0-dcb7-4c7a-afd0-9bd4f65c803a", "trace_id": "04fd151c-e942-4c1c-a6ab-9a1b1fe54172", "data": [ { "id": "sora-2:task_01k777af4hfmg9g7yfvwsc6zws", "video_url": "https://filesystem.site/gptimage/vg-assets/assets%2Ftask_01k777af4hfmg9g7yfvwsc6zws%2Ftask_01k777af4hfmg9g7yfvwsc6zws_genid_92bae0c5-1703-4a5f-9d9f-c9ed2f9e7176_25_10_10_14_12_924695%2Fvideos%2F00000%2Fsrc.mp4?st=2025-10-10T12%3A37%3A32Z&se=2025-10-16T13%3A37%3A32Z&sks=b&skt=2025-10-10T12%3A37%3A32Z&ske=2025-10-16T13%3A37%3A32Z&sktid=a48cca56-e6da-484e-a814-9c849652bcb3&skoid=aa5ddad1-c91a-4f0a-9aca-e20682cc8969&skv=2019-02-02&sv=2018-11-09&sr=b&sp=r&spr=https%2Chttp&sig=5j4dibeaSsDmEka5c%2B9CKHZhRPdqfClQ0tIh03TWXsM%3D&az=oaivgprodscus", "state": "succeeded" } ] } ``` Se observa que el resultado es un video generado a partir de imágenes, similar al ejemplo anterior. ## Tarea de generación de video con personaje (Versión 1) Para realizar una tarea de generación de video con personaje, debe pasar el parámetro `character_url` con el enlace del video para crear el personaje. Es importante que el video no contenga personas reales, de lo contrario fallará la tarea. Se puede especificar lo siguiente: * `character_url`: enlace del video para crear el personaje, sin personas reales para evitar fallos. Ejemplo de llenado:

Después de llenar, se genera automáticamente el siguiente código:

Código correspondiente: ```python theme={null} import requests url = "https://api.xhuoapi.ai/v1/sora/videos" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "size": "small", "duration": 10, "orientation": "landscape", "prompt": "cat running on the river", "character_url": "https://cdn.xhuoapi.ai/pdidf5.mp4", "model": "sora-2", "character_end": 3, "character_start": 1 } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` Al ejecutar, se obtiene inmediatamente un resultado como el siguiente: ``` { "success": true, "task_id": "d9bf5461-29b5-47fd-be90-1fe9197df259", "trace_id": "b7992643-9207-40d6-956b-7577728acc67", "data": [ { "id": "sora-2:task_01k8ykrztefavaypw6xanw305b", "video_url": "https://filesystem.site/cdn/20251101/bee4eeeb4c4660b46dac4548a1ffbc.mp4", "state": "succeeded" } ] } ``` Se observa que el resultado es un video generado con personaje, similar al ejemplo anterior. ## Modo Versión 2.0 Además del modo Versión 1.0, esta API también soporta el modo Versión 2.0, que se activa configurando el parámetro `version` a `"2.0"`. El modo Versión 2.0 soporta videos de duración más corta y control de resolución a nivel de píxel. ### Descripción de parámetros de la Versión 2.0 | Parámetro | Tipo | Obligatorio | Descripción | | -------------- | ------- | ----------- | ---------------------------------------------------------------------------------------------------------------- | | `version` | string | Sí | Configurar a `"2.0"` | | `prompt` | string | Sí | Texto para generar el video | | `model` | string | No | `sora-2` (por defecto) o `sora-2-pro` | | `duration` | integer | No | Duración del video: `4` (por defecto), `8`, `12` segundos | | `size` | string | No | Resolución: `720x1280` (por defecto), `1280x720`, `1024x1792`, `1792x1024` | | `image_urls` | array | No | Arreglo de URLs de imágenes de referencia, solo se usa la primera imagen, la dimensión debe coincidir con `size` | | `callback_url` | string | No | URL para callback asíncrono | ### Ejemplo básico ```shell theme={null} curl -X POST 'https://api.xhuoapi.ai/v1/sora/videos' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "version": "2.0", "prompt": "cat running on the river", "model": "sora-2", "duration": 8, "size": "1280x720" }' ``` Código Python correspondiente: ```python theme={null} import requests url = "https://api.xhuoapi.ai/v1/sora/videos" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "version": "2.0", "prompt": "cat running on the river", "model": "sora-2", "seconds": 8, "size": "1280x720" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` Código JavaScript correspondiente: ```javascript theme={null} const response = await fetch('https://api.xhuoapi.ai/v1/sora/videos', { method: 'POST', headers: { 'accept': 'application/json', 'authorization': 'Bearer {token}', 'content-type': 'application/json' }, body: JSON.stringify({ version: '2.0', prompt: 'cat running on the river', model: 'sora-2', seconds: 8, size: '1280x720' }) }); const data = await response.json(); console.log(data); ``` El formato de respuesta es igual al de la Versión 1: ```json theme={null} { "success": true, "task_id": "6bf7fb83-5814-4e3e-a4ad-bfa0c26c0b33", "trace_id": "96166698-4b66-478d-a26b-77a7269c9e01", "data": [ { "id": "c0cc8dad-0954-421f-be8d-02eb063b3263", "video_url": "https://platform.cdn.xhuoapi.ai/sora/xxxxx.mp4", "state": "succeeded" } ] } ``` ### Uso de imágenes de referencia (Versión 2.0) En modo Versión 2.0, puede pasar imágenes de referencia con el parámetro `image_urls` para guiar la generación del video (solo se usa la primera imagen): ```python theme={null} import requests url = "https://api.xhuoapi.ai/v1/sora/videos" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "version": "2.0", "prompt": "a person walking through a beautiful garden", "model": "sora-2", "duration": 4, "size": "1280x720", "image_urls": ["https://cdn.xhuoapi.ai/11wfp4.png"] } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` > **Nota**: La dimensión de la imagen de referencia debe coincidir con el parámetro `size`. Por ejemplo, si `size` es `1280x720`, la imagen debe tener tamaño 1280×720. ### Comparación de parámetros entre Versión 1.0 y Versión 2.0 | Parámetro | Versión 1.0 | Versión 2.0 | | --------------- | --------------------- | --------------------------------------- | | `version` | 1.0 (por defecto) | 2.0 | | `prompt` | ✅ | ✅ | | `model` | ✅ sora-2 / sora-2-pro | ✅ sora-2 / sora-2-pro | | `duration` | ✅ 10/15/25 segundos | ✅ 4/8/12 segundos | | `orientation` | ✅ landscape/portrait | ❌ | | `size` | ✅ small/large | ✅ 720x1280/1280x720/1024x1792/1792x1024 | | `image_urls` | ✅ múltiples imágenes | ✅ solo la primera imagen | | `character_url` | ✅ | ❌ | | `callback_url` | ✅ | ✅ | ## Callback asíncrono Debido a que la generación de videos con la API Sora Videos Generation puede tardar entre 1 y 2 minutos, si la API no responde en mucho tiempo, la conexión HTTP se mantiene abierta, consumiendo recursos del sistema. Por ello, la API también soporta callbacks asíncronos. El flujo es: el cliente envía la solicitud con un campo adicional `callback_url`. La API responde inmediatamente con un resultado que incluye un `task_id` que representa la tarea actual. Cuando la tarea termina, el resultado del video generado se envía mediante un POST JSON al `callback_url` especificado por el cliente, incluyendo también el campo `task_id`, para relacionar el resultado con la tarea. A continuación, un ejemplo de cómo operar. Primero, el webhook callback es un servicio que puede recibir solicitudes HTTP. El desarrollador debe reemplazarlo por la URL de su servidor HTTP. Para la demostración, usamos un sitio público de webhook [https://webhook.site/](https://webhook.site/), que al abrirlo genera una URL de webhook, como se muestra: ![](https://cdn.xhuoapi.ai/cjjfly.png) Copie esta URL para usarla como webhook. En este ejemplo es `https://webhook.site/eb238c4f-da3b-47a5-a922-a93aa5405daa`. Luego, configure el campo `callback_url` con esta URL y rellene los demás parámetros, como se muestra:

Al ejecutar, se obtiene inmediatamente un resultado como: ``` { "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea" } ``` Después de un momento, puede observar el resultado de la generación en `https://webhook.site/eb238c4f-da3b-47a5-a922-a93aa5405daa`, como se muestra: ![](https://cdn.xhuoapi.ai/0j7nra.png) Contenido: ```json theme={null} { "success": true, "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea", "trace_id": "fb751e1e-4705-49ea-9fd4-5024b7865ea2", "data": [ { "id": "sora-2:task_01k777hjrbfrgs2060q5zvf2a5", "video_url": "https://filesystem.site/gptimage/vg-assets/assets%2Ftask_01k777hjrbfrgs2060q5zvf2a5%2Ftask_01k777hjrbfrgs2060q5zvf2a5_genid_b8e2e5d1-a579-49ca-a21c-cb3869685cce_25_10_10_14_15_147334%2Fvideos%2F00000%2Fsrc.mp4?st=2025-10-10T12%3A38%3A49Z&se=2025-10-16T13%3A38%3A49Z&sks=b&skt=2025-10-10T12%3A38%3A49Z&ske=2025-10-16T13%3A38%3A49Z&sktid=a48cca56-e6da-484e-a814-9c849652bcb3&skoid=aa5ddad1-c91a-4f0a-9aca-e20682cc8969&skv=2019-02-02&sv=2018-11-09&sr=b&sp=r&spr=https%2Chttp&sig=p4aMqXqkP%2FI1IhOVGCB9JL8vUUvfNBBF12ESpKhKXOk%3D&az=oaivgprodscus", "state": "succeeded" } ] } ``` Se observa que el resultado contiene el campo `task_id` y otros campos similares a los anteriores, lo que permite relacionar la tarea y su resultado. ## Manejo de errores Al llamar a la API, si ocurre un error, la API devuelve un código e información de error. Por ejemplo: * `400 token_mismatched`: Solicitud incorrecta, posiblemente por parámetros faltantes o inválidos. * `400 api_not_implemented`: Solicitud incorrecta, posiblemente por parámetros faltantes o inválidos. * `401 invalid_token`: No autorizado, token de autorización inválido o faltante. * `429 too_many_requests`: Demasiadas solicitudes, se ha excedido el límite de tasa. * `500 api_error`: Error interno del servidor. ### Ejemplo de respuesta de error ```json theme={null} { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## Conclusión Con este documento, ha aprendido cómo usar la API de generación de videos Sora para crear videos mediante prompts y referencias de imágenes. Esperamos que esta guía le ayude a integrar y usar mejor esta API. Si tiene alguna pregunta, no dude en contactar a nuestro equipo de soporte técnico.