Saltar al contenido principal
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. Al ingresar a la página, haga clic en el botón “Acquire”, como se muestra en la imagen: 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: 
{
  "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: 
curl -X POST 'https://api.acedata.cloud/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: 
import requests

url = "https://api.acedata.cloud/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.acedata.cloud/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: 
import requests

url = "https://api.acedata.cloud/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.acedata.cloud/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ámetroTipoObligatorioDescripción
versionstringSíConfigurar a "2.0"
promptstringSíTexto para generar el video
modelstringNosora-2 (por defecto) o sora-2-pro
durationintegerNoDuración del video: 4 (por defecto), 8, 12 segundos
sizestringNoResolución: 720x1280 (por defecto), 1280x720, 1024x1792, 1792x1024
image_urlsarrayNoArreglo de URLs de imágenes de referencia, solo se usa la primera imagen, la dimensión debe coincidir con size
callback_urlstringNoURL para callback asíncrono

​
Ejemplo básico

curl -X POST 'https://api.acedata.cloud/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: 
import requests

url = "https://api.acedata.cloud/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: 
const response = await fetch('https://api.acedata.cloud/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: 
{
  "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.acedata.cloud/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): 
import requests

url = "https://api.acedata.cloud/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.acedata.cloud/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ámetroVersión 1.0Versión 2.0
version1.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/, que al abrirlo genera una URL de webhook, como se muestra: 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: Contenido: 
{
    "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

{
  "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.