Sora Videos Generation API Integración

Sora Video Generation API guide - Ace Data Cloud

Este documento presentará la integración del Sora Videos Generation API, a través del cual se pueden ingresar parámetros personalizados para generar videos oficiales de Sora. Esta API admite dos modos de versión:

• Versión 1 (modo clásico): admite parámetros como duration (10/15/25 segundos), orientation (horizontal/vertical), size (pequeño/grande), imágenes de referencia image_urls, video de personaje character_url, entre otros.
• Versión 2 (modo colaborador): admite parámetros como seconds (4/8/12 segundos), resolución a nivel de píxel size (por ejemplo, 1280x720), imágenes de referencia input_reference, entre otros.

​

Proceso de Solicitud

Para utilizar el Sora Videos Generation API, primero dirígete a Ace Data Cloud Console para obtener tu API Token, que debes guardar como respaldo.

Si aún no has iniciado sesión o registrado, serás redirigido automáticamente a la página de inicio de sesión que te invitará a registrarte e iniciar sesión, y una vez completado, regresarás automáticamente a la página actual.

Un API Token es suficiente para acceder a todos los servicios de la plataforma, no es necesario solicitar uno por cada servicio. La primera solicitud incluirá un crédito gratuito para que puedas probar; si el crédito es insuficiente, puedes recargar el saldo general en la consola.

📘 Documentación completa: Sora Videos Generation API →

​

Uso Básico (Versión 1)

Primero, comprende la forma básica de uso de la Versión 1, que consiste en ingresar la palabra clave prompt, un array de enlaces de imágenes de referencia image_urls y el modelo model, para obtener el resultado procesado. El contenido específico es el siguiente:

Aquí podemos ver que hemos configurado los Request Headers, que incluyen:

• accept: el formato de respuesta que deseas recibir, aquí se establece como application/json, es decir, en formato JSON.
• authorization: la clave para llamar a la API, que puedes seleccionar directamente después de solicitarla.

Además, se configuró el Request Body, que incluye:

• model: el modelo para generar el video, admite sora-2 (modo estándar) y sora-2-pro (modo de alta definición). El sora-2-pro puede soportar videos con duration de 25 segundos, mientras que el sora-2 solo admite 10 y 15 segundos.
• size: la claridad del video, small es claridad estándar, large es claridad HD (solo Versión 1).
• duration: la duración del video, admite 10, 15 y 25 segundos, donde 25 segundos solo es compatible con sora-2-pro (solo Versión 1).
• orientation: la dirección del marco, admite landscape (horizontal), portrait (vertical) (solo Versión 1).
• image_urls: array de enlaces de imágenes de referencia, utilizado para generar video a partir de imágenes (solo Versión 1).
• character_url: enlace del video del personaje, no se pueden incluir personas reales en el video (solo Versión 1).
• character_start/character_end: segundos de inicio y fin de la aparición del personaje, con un rango de diferencia de 1-3 segundos (solo Versión 1).
• prompt: palabra clave (requerido).
• callback_url: URL para la devolución de llamada asíncrona de resultados.
• async: opcional, si se establece en true, la interfaz devuelve inmediatamente task_id, sin necesidad de proporcionar callback_url, y luego se puede consultar el resultado a través de la interfaz de consulta de tareas correspondiente.
• version: versión de la API, "1.0" (por defecto) o "2.0".

Después de seleccionar, se puede observar que a la derecha también se generó el código correspondiente, como se muestra en la imagen:

Haciendo clic en el botón «Try» se puede realizar una prueba, como se muestra en la imagen anterior, y aquí 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://platform.cdn.acedata.cloud/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 devuelto tiene varios campos, que se describen a continuación:

• success, el estado de la tarea de generación de video en este momento.
• task_id, el ID de la tarea de generación de video en este momento.
• trace_id, el ID de seguimiento de la generación de video en este momento.
• data, la lista de resultados de la tarea de generación de video en este momento.
  • id, el ID del video de la tarea de generación de video en este momento.
  • video_url, el enlace del video de la tarea de generación de video en este momento.
  • state, el estado de la tarea de generación de video en este momento.

Podemos ver que hemos obtenido información satisfactoria del video, solo necesitamos obtener el video de Sora generado a partir de la dirección del enlace de video en data.

Además, si deseas generar el código de integración correspondiente, puedes copiarlo directamente, por ejemplo, el código de CURL es el siguiente:

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": "gato corriendo en el río",
  "model": "sora-2"
}'

​

Tarea de Video a partir de Imágenes (Versión 1)

Si deseas realizar una tarea de video a partir de imágenes, primero el parámetro image_urls debe incluir enlaces de imágenes de referencia, lo que te permitirá especificar el siguiente contenido:

• image_urls: array de enlaces de imágenes de referencia utilizados en esta tarea de video a partir de imágenes. Ten en cuenta que no se pueden enviar imágenes de personas reales con rostros, ya que esto podría causar que la tarea falle.

Un ejemplo de llenado es el siguiente:

Una vez completado, se generó automáticamente el siguiente código:

El 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": "gato corriendo por el río",
    "model": "sora-2",
    "image_urls": ["https://cdn.acedata.cloud/11wfp4.png"]
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Al hacer clic en ejecutar, se puede ver que se obtiene un resultado inmediato, como se muestra a continuación:

{
  "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://platform.cdn.acedata.cloud/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 puede ver que el efecto generado es un video creado a partir de imágenes, el resultado es similar al anterior.

​

Tarea de generación de video de personajes (Versión 1)

Si se desea realizar una tarea de generación de video de personajes, primero el parámetro character_url debe recibir el enlace del video necesario para crear el personaje, tenga en cuenta que el video no debe contener personas reales, de lo contrario fallará, se puede especificar el siguiente contenido:

• character_url: enlace del video necesario para crear el personaje, tenga en cuenta que el video no debe contener personas reales, de lo contrario fallará.

Ejemplo de llenado a continuación:

Una vez completado, se generó 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": "gato corriendo por el río",
    "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 hacer clic en ejecutar, se puede ver que se obtiene un resultado inmediato, como se muestra a continuación:

{
  "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://platform.cdn.acedata.cloud/20251101/bee4eeeb4c4660b46dac4548a1ffbc.mp4",
      "state": "succeeded"
    }
  ]
}

Se puede ver que el efecto generado es un video de generación de personajes, el resultado es similar al anterior.

​

Modo Versión 2.0

Además del modo Versión 1.0 mencionado anteriormente, esta API también admite el modo Versión 2.0, que se puede habilitar configurando el parámetro version como "2.0". El modo Versión 2.0 admite una duración de video más corta y un control de resolución a nivel de píxel.

​

Descripción de parámetros de la Versión 2.0

Parámetro	Tipo	¿Es obligatorio?	Descripción
version	string	Sí	Configurado como "2.0"
prompt	string	Sí	Palabra clave para generar el video
model	string	No	sora-2 (predeterminado) o sora-2-pro
duration	integer	No	Duración del video: 4 (predeterminado), 8, 12 segundos
size	string	No	Resolución: 720x1280 (predeterminado), 1280x720, 1024x1792, 1792x1024
image_urls	array	No	Array de URL de imágenes de referencia, solo se usa la primera imagen, el tamaño de la imagen debe coincidir con el parámetro size
callback_url	string	No	URL de 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": "gato corriendo por el río",
  "model": "sora-2",
  "duration": 8,
  "size": "1280x720"
}'

Código correspondiente en Python:

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": "gato corriendo por el río",
    "model": "sora-2",
    "seconds": 8,
    "size": "1280x720"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Código correspondiente en JavaScript:

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: 'gato corriendo por el río',
    model: 'sora-2',
    seconds: 8,
    size: '1280x720'
  })
});
const data = await response.json();
console.log(data);

El formato de resultado devuelto es el mismo que el 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 el modo de Versión 2.0, se puede pasar imágenes de referencia a través del parámetro image_urls para guiar la generación de video (solo se utiliza 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": "una persona caminando por un hermoso jardín",
    "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: Las dimensiones de la imagen de referencia deben coincidir con el parámetro size, por ejemplo, si size es 1280x720, las dimensiones de la imagen de referencia deben ser 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 (predeterminado)	2.0
prompt	✅	✅
model	✅ sora-2 / sora-2-pro	✅ sora-2 / sora-2-pro
duration	✅ 10/15/25 segundos	✅ 4/8/12 segundos
orientation	✅ paisaje/retrato	❌
size	✅ pequeño/grande	✅ 720x1280/1280x720/1024x1792/1792x1024
image_urls	✅ múltiples imágenes de referencia	✅ solo se utiliza la primera
character_url	✅	❌
callback_url	✅	✅

​

Callback asíncrono

Debido a que el tiempo de generación de la API de Sora Videos es relativamente largo, aproximadamente 1-2 minutos, si la API no responde durante mucho tiempo, la solicitud HTTP mantendrá la conexión, lo que provocará un consumo adicional de recursos del sistema, por lo que esta API también ofrece soporte para callbacks asíncronos.

El flujo general es: cuando el cliente inicia la solicitud, especifica un campo adicional callback_url, después de que el cliente inicia la solicitud de API, la API devolverá inmediatamente un resultado que contiene un campo de información task_id, que representa el ID de la tarea actual. Cuando la tarea se completa, el resultado del video generado se enviará al callback_url especificado por el cliente en formato JSON POST, que también incluye el campo task_id, de modo que el resultado de la tarea se pueda asociar mediante el ID.

A continuación, entenderemos cómo operar específicamente a través de un ejemplo.

Primero, el callback de Webhook es un servicio que puede recibir solicitudes HTTP, los desarrolladores deben reemplazarlo con la URL de su propio servidor HTTP. Aquí, para facilitar la demostración, se utiliza un sitio web de ejemplo de Webhook público https://webhook.site/, al abrir este sitio se obtiene una URL de Webhook, como se muestra en la imagen:

Copie esta URL y úsela como Webhook, el ejemplo aquí es https://webhook.site/eb238c4f-da3b-47a5-a922-a93aa5405daa.

A continuación, podemos establecer el campo callback_url en la URL de Webhook anterior, al mismo tiempo que llenamos los parámetros correspondientes, el contenido específico se muestra en la imagen:

Al hacer clic en ejecutar, se puede observar que se obtiene inmediatamente un resultado, como se muestra a continuación:

{
  "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea"
}

Después de un momento, podemos observar el resultado del video generado en https://webhook.site/eb238c4f-da3b-47a5-a922-a93aa5405daa, como se muestra en la imagen:

El contenido es el siguiente:

{
    "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://platform.cdn.acedata.cloud/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 puede ver que en el resultado hay un campo task_id, los otros campos son similares a los mencionados anteriormente, a través de este campo se puede realizar la asociación de tareas.

​

Manejo de errores

Al llamar a la API, si se encuentra con un error, la API devolverá el código de error y la información correspondiente. Por ejemplo:

• 400 token_mismatched: Solicitud incorrecta, posiblemente debido a parámetros faltantes o inválidos.
• 400 api_not_implemented: Solicitud incorrecta, posiblemente debido a 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, ha superado el límite de tasa.
• 500 api_error: Error interno del servidor, algo salió mal en el servidor.

​

Ejemplo de respuesta de error

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "la recuperación falló"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​

Conclusión

A través de este documento, usted ha aprendido cómo utilizar la API de Generación de Videos Sora para generar videos mediante la entrada de palabras clave y imágenes de referencia. Esperamos que este documento le ayude a integrar y utilizar mejor esta API. Si tiene alguna pregunta, no dude en ponerse en contacto con nuestro equipo de soporte técnico.