API de Sora 2 con Python: guía completa con ejemplos

Primeros pasos con la API de OpenAI

Para empezar, necesitamos crear una cuenta de OpenAI y una clave de API. Para ello, ve a su página de claves de API y haz clic en "Create new secret key" en la esquina superior derecha.

Esta clave se usa para hacer solicitudes a la API de OpenAI. La guardamos en un archivo llamado .env en la carpeta donde escribimos nuestros scripts de Python. Asegúrate de mantener la clave en secreto, porque cualquiera podría usarla para interactuar con la API desde tu cuenta.

Pega la clave de API en el archivo .env con el siguiente formato:

OPENAI_API_KEY=<paste_api_key_here>

Ten en cuenta que usar la API no es gratis, así que es necesario añadir saldo a tu cuenta antes de poder generar vídeos con Sora 2. Como referencia, aquí tienes el precio por segundo de Sora 2:

Generar un vídeo con Sora 2 y Python

Todo el código de este tutorial se puede encontrar en este repositorio de GitHub.

Para comunicarte con la API de OpenAI usando Python, utilizaremos el paquete openai. Ten en cuenta que, como Sora es nuevo en la API, necesitamos una versión reciente del paquete.

Podemos usar este comando para instalarlo (o actualizar la versión actual si ya está instalado):

pip install --upgrade openai

Crea un nuevo script llamado generate_video.py en la misma carpeta que el archivo .env que creamos antes.

El primer paso es importar los paquetes necesarios. Esto es lo que usaremos:

• os: Paquete incorporado para interactuar con el sistema operativo;
• openai: Paquete oficial de OpenAI para interactuar con su API;
• dotenv: Paquete que facilita la carga de variables de entorno desde el archivo .env. En este caso, lo usamos para cargar la clave de la API de OpenAI.

import os
from openai import OpenAI 
from dotenv import load_dotenv

A continuación, cargamos el archivo .env:

load_dotenv()
API_KEY = os.getenv("OPENAI_API_KEY")

Con la clave de API cargada en memoria, podemos inicializar el cliente de OpenAI, que nos permite hacer solicitudes a la API de OpenAI. Usamos la librería os para cargar la clave:

client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

Por último, usamos la función videos.create del cliente para generar un vídeo:

video = client.videos.create(
    prompt="A cat and a dog dancing",
)
print(video.id)

Cuando solicitamos la generación del vídeo, no lo recibimos al instante porque tarda un buen rato en generarse. Esto significa que la variable video no es el vídeo en sí, sino un objeto con información sobre el trabajo de generación.

Por eso imprimimos el identificador del vídeo. Esta es la información que necesitaremos para:

1. Seguir el progreso de la generación.
2. Recuperar el vídeo.

A continuación explicamos ambos pasos en detalle.

Este fue el resultado que obtuve:

Seguimiento del progreso del vídeo

Podemos consultar el estado de un trabajo pasando su identificador a la función videos.retrieve(), así:

job = client.videos.retrieve(job_id)
status = job.status
progress = job.progress
print(f"Status: {status}, {progress}%")

Tenemos que esperar a que el progreso llegue al 100% para poder descargar el vídeo. Para mayor comodidad, construimos una función, wait_for_video_to_finish(), que monitoriza el estado del trabajo hasta que finaliza:

def wait_for_video_to_finish(video_id, poll_interval=5, timeout=600):
    """
    Poll status until the video is ready or timeout is reached.
    Returns the final job info.
    """
    client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
    elapsed = 0  # Keep track of the elapsed time
    while elapsed < timeout:
        job = client.videos.retrieve(video_id)
        status = job.status
        progress = job.progress
        print(f"Status: {status}, {progress}%")
        if status == "completed":
            return job
        if status == "failed":
            raise RuntimeError(f"Failed to generate the video: {job.error.message}") 
        time.sleep(poll_interval)
        elapsed += poll_interval
    raise RuntimeError("Polling timed out")

La función tiene tres parámetros:

• video_id: Identificador del vídeo que queremos seguir.
• poll_interval: Segundos de espera entre cada consulta.
• timeout: Número máximo de segundos a esperar.

Esta función comprueba periódicamente el estado del vídeo hasta que finaliza o se agota el tiempo de espera.

Descargar el vídeo

Ahora que podemos hacer el seguimiento del proceso de generación, solo falta una forma de descargarlo cuando termine. Podemos hacerlo con la función videos.download_content().

Aquí tienes una función que lo hace:

def download_video(video_id):
    client = get_client()
    response = client.videos.download_content(
        video_id=video_id,
    )
    video_bytes = response.read()
    with open(f"{video_id}.mp4", "wb") as f:
        f.write(video_bytes)

Flujo completo de generación de vídeo con Sora

Podemos unir estos pasos para construir un flujo de generación de vídeo con Sora:

prompt = "A cat and a dog dancing"
video = client.videos.create(
    prompt="A cat and a dog dancing",
)
video_id = video.id
print(f"Started generating video with id {video_id}")
wait_for_video_to_finish(video_id)
download_video(video_id)

Configurar el tamaño y la duración del vídeo

El script anterior usa solo un prompt de texto para generar el vídeo. Sin embargo, la API de OpenAI Sora 2 ofrece otras opciones, como:

• model: El modelo usado para generar el vídeo. Por defecto es sora-2.
• resolution: El tamaño del vídeo. Por defecto, 720x1280.
• duration: Duración del vídeo en segundos. Por defecto, 4 segundos.

Aquí tienes una tabla con todos los valores posibles según el modo (en negrita, los valores por defecto):

Para facilitar el uso del script, podemos utilizar el paquete incorporado argparse para que el usuario indique el valor de cada parámetro.

Así puedes definir los argumentos prompt y model con argparse:

parser = argparse.ArgumentParser()
parser.add_argument(
    "--prompt", # Name of the argument
    required=True, # Specify that the argument is required
    help="The video prompt.", # Helper text
)
parser.add_argument(
    "--model",
    default="sora-2", # Specify a default value for the argument
    choices=["sora-2", "sora-2-pro"], # Specify a list of possible values for the argument
    help="Model to use (sora-2 or sora-2-pro).",
)

Para cargar los argumentos, llamamos al método parse_args() así:

args = parser.parse_args()
prompt = args.prompt
model = args.model

El script generate_video_pipeline.py del repositorio de GitHub reúne todo lo aprendido en un script que puede generar vídeos con Sora 2.

Aquí tienes un ejemplo de cómo ejecutarlo en la terminal con parámetros específicos:

python generate_video_pipeline.py --prompt "A family of dogs driving a car" --model sora-2-pro  --size 1280x720 --seconds 8

Este fue el resultado:

Consejos de prompt para la API de Sora 2

OpenAI ofrece una guía completa de prompts para Sora 2.

Las ideas fundamentales para crear un buen prompt en Sora 2 son:

• Equilibra detalle y libertad: los prompts específicos te dan control; los simples fomentan la creatividad.
• Configura parámetros en la API: define modelo (sora-2 o sora-2-pro), resolución y duración del clip de forma explícita.
• Pensar en planos: describe encuadre, iluminación, sujeto y una acción clara por plano.
• Sé visual y concreto: "asfalto mojado bajo luces de neón" supera a "una calle bonita".
• Mantén el movimiento simple: una acción del sujeto + un movimiento de cámara funciona mejor.
• Iluminación: define calidad, dirección y paleta de color para mantener la coherencia.
• Usa referencias de imagen: añade una entrada visual para anclar estilo y composición.
• Diálogos: líneas cortas y naturales; etiquetadas con claridad; limitadas por clip.
• Itera con Remix: ajusta un elemento (iluminación, lente, paleta) cada vez para un control preciso.

Reúnen estas ideas en la siguiente plantilla de prompt:

[Prose scene description in plain language. Describe characters, costumes, scenery, weather and other details. Be as descriptive to generate a video that matches your vision.]
Cinematography:
Camera shot: [framing and angle, e.g. wide establishing shot, eye level]
Mood: [overall tone, e.g. cinematic and tense, playful and suspenseful, luxurious anticipation]
Actions:
- [Action 1: a clear, specific beat or gesture]
- [Action 2: another distinct beat within the clip]
- [Action 3: another action or dialogue line]
Dialogue:
[If the shot has dialogue, add short natural lines here or as part of the actions list. Keep them brief so they match the clip length.]

Escribir prompts largos en la terminal es engorroso. Para mejorar la experiencia, podemos cambiar el script para que, si el prompt termina en .txt, el script asuma que el usuario está proporcionando la ruta a un archivo de texto con el prompt. 

Así podemos actualizar el script para admitirlo:

...
args = parser.parse_args()
prompt = args.prompt
if prompt.endswith(".txt"):
    with open(prompt, "rt") as f:
        prompt = f.read()
video_id = generate_video(prompt, args.model, args.size, args.seconds)
...

Para probarlo, creé un archivo en la misma carpeta llamado prompt.txt con el siguiente prompt:

A polite green alien wearing a beret struggles to order croissants in broken French at a bustling Paris café.

Cinematography:
Camera shot: eye-level shot, warm morning light
Mood: whimsical and awkward
Actions:
The alien studies the pastry display, fascinated.
It points to the baguette, then accidentally eats the napkin.
The waiter shrugs, unfazed, and brings it another napkin.
Dialogue:
Alien (content): “Très… chewy.”

Para generar el vídeo, pasamos prompt.txt en el parámetro --prompt:

python generate_video_pipeline.py --prompt prompt.txt --model sora-2-pro  --size 1280x720 --seconds 8

Aquí está el vídeo:

Vemos que no siguió el prompt al pie de la letra. Por mi experiencia con modelos de vídeo de IA, suelo obtener mejores resultados creando varios clips más sencillos y uniéndolos después. 

Para hacerlo, eso sí, necesitamos que sean consistentes. Podemos lograrlo proporcionando una imagen de referencia al modelo. Eso es lo que vamos a aprender ahora.

Generar vídeos con Sora 2 a partir de imágenes

Para generar un vídeo a partir de una imagen, usamos el parámetro input_reference.

Aquí tienes un fragmento de código sobre cómo cargar una imagen y pasársela al modelo como referencia:

f = open("image_reference.jpeg", "rb")

# Generate the video
video = client.videos.create(
    prompt="The two people walk away from each other.",
    input_reference=f
)

f.close()

wait_for_video_to_finish(video.id)
download_video(video.id)

El script generate_video_with_reference.py del repositorio de GitHub ofrece un ejemplo totalmente funcional. Al ejecutarlo con la imagen de referencia, obtuve esto:

Para que la imagen de referencia funcione, debe tener el mismo tamaño que el solicitado para la generación del vídeo.

Podemos usar el paquete Pillow para redimensionar automáticamente la imagen de referencia antes de proporcionársela al modelo. Ten en cuenta, no obstante, que si la relación de aspecto de la imagen original es muy diferente, se distorsionará y es probable que el vídeo no quede bien.

Para instalarlo, usa el comando:

pip install Pillow

El script sora.py incluye una implementación de la función generate_video() que adapta el código anterior para redimensionar la imagen si se proporciona una.

El script generate_video_pipeline_reference.py muestra cómo podemos añadir el parámetro de referencia al script de generación.

Aquí tienes un ejemplo generado a partir de una foto usando la función de autoajuste que acabamos de implementar:

Usar referencias de vídeo

El script que hemos construido está listo para manejar referencias de vídeo además de imágenes. Sin embargo, cada vez que intenté generar un vídeo proporcionando otro vídeo como referencia, obtuve un error:

Video inpaint is not available for your organization

Según su foro, parece que es un problema habitual, lo que apunta a que esta función aún no está disponible para todo el mundo en la API. Tocará esperar un poco más para poder usarla.

Otras limitaciones

Mientras trabajaba con Sora 2, a menudo me encontré con problemas en los que Sora rechazaba generar el vídeo indicando que el sistema de moderación había bloqueado la solicitud:

RuntimeError: Video generation failed: Your request was blocked by our moderation system.

Entiendo que estos sistemas requieren una moderación estricta porque se puede causar mucho daño si se permite generar cualquier tipo de vídeo. Aun así, creo que el algoritmo de moderación necesita afinarse, porque bloqueó la mayoría de mis solicitudes y me obligó a abandonar mi idea original.

Las fotos que intenté transformar en vídeo no tenían contenido sensible ni problemas de derechos, ya que todas las imágenes son mías. Además, el error no aporta información sobre el motivo del bloqueo.

Este problema fue muy frecuente, haciendo imposible crear algo significativo.

Conclusión

Sora 2 abre nuevas posibilidades para la generación de vídeo con IA y, gracias a su disponibilidad a través de la API de OpenAI, integrar estas herramientas punteras en tu flujo de trabajo con Python está ahora al alcance de desarrolladores de todos los perfiles.

Siguiendo este tutorial, ya tienes una base sólida para crear vídeos personalizados con prompts sencillos, afinar resultados con parámetros avanzados y usar imágenes de referencia para lograr mayor consistencia. A medida que la API evolucione, llegarán más funciones —incluidas capacidades sólidas de vídeo a vídeo— que ampliarán tu caja de herramientas creativa.

Tanto si estás experimentando con prompts divertidos, construyendo storyboards complejos o desarrollando apps multimedia de nueva generación, Sora 2 es una forma potente de dar vida a tus ideas. También te recomiendo consultar nuestra guía sobre el nuevo modelo SAM3 de Meta.