API do Sora 2 com Python: guia completo com exemplos

primeiros passos com a API da OpenAI

Para começar, precisamos criar uma conta na OpenAI e uma chave de API. Para isso, acesse a página de chaves de API e clique em "Create new secret key" no canto superior direito.

Essa chave é usada para fazer requisições à API da OpenAI. Armazene-a em um arquivo chamado .env na mesma pasta onde você escrever seus scripts em Python. Mantenha essa chave em sigilo, pois qualquer pessoa pode usá-la para interagir com a API pela sua conta.

Cole a chave de API no arquivo .env neste formato:

OPENAI_API_KEY=<paste_api_key_here>

Vale lembrar que o uso da API é pago, portanto é necessário adicionar créditos à sua conta antes de conseguir gerar vídeos com o Sora 2. Para referência, aqui está o preço por segundo do Sora 2:

gerando um vídeo com o Sora 2 em Python

Todo o código deste tutorial pode ser encontrado neste repositório no GitHub.

Para se comunicar com a API da OpenAI usando Python, vamos usar o pacote openai. Como o Sora é novo na API, é preciso uma versão recente do pacote.

Use este comando para instalar (ou atualizar a versão caso já esteja instalada):

pip install --upgrade openai

Crie um novo script chamado generate_video.py na mesma pasta do arquivo .env que criamos antes.

O primeiro passo é importar os pacotes necessários. Vamos usar:

• os: pacote nativo usado para interagir com o sistema operacional;
• openai: o pacote oficial da OpenAI para interagir com a API;
• dotenv: pacote que facilita carregar variáveis de ambiente do arquivo .env. Aqui, usamos para carregar a chave da API da OpenAI.

import os
from openai import OpenAI 
from dotenv import load_dotenv

Em seguida, carregamos o arquivo .env:

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

Com a chave em memória, inicializamos o cliente da OpenAI, que permite fazer requisições à API. Usamos a biblioteca os para carregar a chave:

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

Por fim, usamos a função videos.create do cliente para gerar um vídeo:

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

Ao solicitar a geração, o vídeo não é entregue imediatamente, pois o processo leva algum tempo. Isso significa que a variável video não é o vídeo em si, mas um objeto com informações sobre o job de geração.

Por isso imprimimos o identificador do vídeo. É essa a informação que vamos usar para:

1. Acompanhar o progresso da geração.
2. Baixar o vídeo.

Vamos explicar esses dois passos em detalhes abaixo.

Aqui está o resultado que obtive:

acompanhando o progresso do vídeo

Podemos consultar o status de um job informando seu identificador para a função videos.retrieve(), assim:

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

Precisamos esperar o progresso chegar a 100% para conseguir baixar o vídeo. Para facilitar, criamos a função wait_for_video_to_finish(), que monitora o status do job até ele concluir:

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")

A função tem três parâmetros:

• video_id: o identificador do vídeo que queremos acompanhar;
• poll_interval: quantos segundos esperar entre cada consulta;
• timeout: o tempo máximo de espera, em segundos.

Essa função verifica periodicamente o status do vídeo até concluir ou o tempo limite ser atingido.

baixando o vídeo

Agora que já conseguimos acompanhar a geração, precisamos de uma forma de baixar o vídeo quando terminar. Usamos para isso a função videos.download_content().

Aqui vai uma função que faz isso:

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)

workflow completo de geração de vídeo com o Sora

Podemos juntar esses passos para montar um fluxo de geração com o 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)

definindo tamanho e duração do vídeo

O script acima usa apenas um prompt de texto para gerar o vídeo. No entanto, a API do OpenAI Sora 2 oferece outras opções, como:

• model: o modelo usado para gerar o vídeo. Por padrão, é o sora-2.
• resolution: o tamanho do vídeo. Por padrão, é 720x1280.
• duration: a duração, em segundos. Por padrão, o vídeo tem 4 segundos.

Aqui está uma tabela com todos os valores possíveis, dependendo do modo (os valores em negrito são os padrões):

Para facilitar o uso do script, podemos usar o pacote nativo argparse para permitir que o usuário defina cada parâmetro.

Veja um exemplo de como definir os argumentos prompt e model com 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 carregar os argumentos, chamamos o método parse_args(), assim:

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

O script generate_video_pipeline.py no GitHub reúne todas as partes que vimos em um script capaz de gerar vídeos com o Sora 2.

Veja um exemplo de como executá-lo no terminal com 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 foi o resultado:

dicas de prompt para a API do Sora 2

A OpenAI fornece um guia completo de prompts para o Sora 2.

As ideias fundamentais para construir um bom prompt para o Sora 2 são:

• Equilibre detalhe e liberdade: prompts específicos dão controle; prompts simples estimulam a criatividade.
• Defina parâmetros na API: especifique o modelo (sora-2 ou sora-2-pro), a resolução e a duração do clipe.
• Pense em planos: descreva enquadramento, iluminação, sujeito e uma ação clara por plano.
• Seja visual e concreto: “asfalto molhado sob luzes de néon” é melhor que “uma rua bonita”.
• Mantenha o movimento simples: uma ação do sujeito + um movimento de câmera funciona melhor.
• Iluminação: defina qualidade, direção e paleta de cores para consistência.
• Use referências visuais: adicione uma imagem para ancorar estilo e composição.
• Diálogo: falas curtas e naturais; bem identificadas; em número limitado por clipe.
• Itere com Remix: ajuste um elemento por vez (iluminação, lente, paleta) para controle fino.

Eles sintetizam essas ideias no seguinte template 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.]

Fornecer prompts longos direto no terminal é trabalhoso. Para melhorar a experiência, podemos ajustar o script para, caso o prompt termine com .txt, assumir que o usuário está passando o caminho de um arquivo de texto com o prompt. 

Veja como atualizar o script para suportar isso:

...
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 testar, criei um arquivo na mesma pasta chamado prompt.txt com o seguinte 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 gerar o vídeo, passamos o prompt.txt no parâmetro --prompt:

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

Aqui está o vídeo:

Percebemos que o resultado não seguiu o prompt à risca. Pela minha experiência com modelos de vídeo em IA, costumo obter resultados melhores criando vários vídeos mais simples e depois unindo-os na edição. 

Mas, para fazer isso, precisamos garantir consistência entre os clipes. Podemos conseguir isso fornecendo uma imagem de referência ao modelo. É isso que vamos aprender agora.

gerando vídeos com o Sora 2 a partir de imagens

Para gerar um vídeo com base em uma imagem, usamos o parâmetro input_reference.

Veja como carregar uma imagem e passá-la como referência para o modelo:

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)

O script generate_video_with_reference.py no GitHub traz um exemplo completo disso. Ao executá-lo com a imagem de referência, o resultado foi este:

Para a imagem de referência funcionar, ela precisa ter o mesmo tamanho solicitado para a geração do vídeo.

Podemos usar o pacote Pillow para redimensionar automaticamente a imagem de referência antes de enviá-la ao modelo. Note, porém, que se a proporção da imagem original for muito diferente, haverá distorção e a qualidade do vídeo pode cair bastante.

Para instalar, use o comando:

pip install Pillow

O script sora.py traz uma implementação da função generate_video() que adapta o código anterior para redimensionar a imagem caso ela seja fornecida.

O script generate_video_pipeline_reference.py mostra como adicionar o parâmetro de referência ao script de geração.

Aqui está um exemplo gerado a partir de uma foto usando o recurso de redimensionamento automático que acabamos de implementar:

usando referências em vídeo

O script que construímos já está pronto para lidar com referências em vídeo além de imagens. Porém, sempre que tentei gerar um vídeo fornecendo outro vídeo como referência, recebi um erro:

Video inpaint is not available for your organization

Segundo o fórum da OpenAI, esse parece ser um problema comum, o que indica que o recurso ainda não está disponível na API para todo mundo. Teremos que esperar mais um pouco para usar.

outras limitações

Ao trabalhar com o Sora 2, muitas vezes me deparei com situações em que o Sora recusava gerar o vídeo, informando que o sistema de moderação bloqueou a solicitação:

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

Entendo que esses sistemas precisam de uma moderação rigorosa, pois muito dano pode ser causado se os usuários puderem gerar qualquer tipo de vídeo. No entanto, sinto que o algoritmo de moderação ainda precisa ser refinado, pois bloqueou a maioria das minhas solicitações, o que me forçou a abandonar a ideia original.

As fotos que tentei transformar em vídeo não tinham conteúdo sensível nem problemas de direitos autorais, já que todas as imagens são minhas. O erro também não informa o motivo do bloqueio.

Esse problema ocorreu com muita frequência, tornando impossível criar algo significativo.

conclusão

O Sora 2 abre novas possibilidades empolgantes para geração de vídeo com IA e, com sua disponibilidade via API da OpenAI, integrar essas ferramentas de ponta ao seu fluxo de trabalho em Python ficou ao alcance de desenvolvedores de todos os perfis.

Seguindo este tutorial, você agora tem uma base sólida para criar vídeos personalizados com prompts simples, ajustar os resultados com parâmetros avançados e usar imagens de referência para maior consistência. À medida que a API evoluir, mais recursos — incluindo capacidades robustas de vídeo para vídeo — devem chegar, ampliando seu kit criativo.

Seja para brincar com prompts criativos, montar storyboards complexos ou desenvolver apps multimídia de próxima geração, o Sora 2 é uma forma poderosa de dar vida às suas ideias. Também recomendo conferir nosso guia sobre o novo modelo SAM3 da Meta.