Sora 2-API met Python: een complete gids met voorbeelden

Aan de slag met de OpenAI API

Om te beginnen moeten we een OpenAI-account en een API-sleutel aanmaken. Ga hiervoor naar hun API-sleutelpagina en klik rechtsboven op "Create new secret key".

Deze sleutel gebruik je om verzoeken naar de OpenAI API te sturen. We slaan hem op in een bestand met de naam .env in de map waar we onze Python-scripts schrijven. Zorg ervoor dat je de sleutel geheim houdt, want iedereen kan er via jouw account de API mee gebruiken.

Plak de API-sleutel in het .env-bestand in het volgende formaat:

OPENAI_API_KEY=<paste_api_key_here>

Let op: het gebruik van de API is niet gratis, dus je moet je account opwaarderen voordat je video’s kunt genereren met Sora 2. Ter referentie, hier is de prijs per seconde van Sora 2:

Een Sora 2-video genereren met Python

Alle code voor deze tutorial is te vinden in deze GitHub-repository.

Om met Python met de OpenAI API te communiceren, gebruiken we het pakket openai. Omdat Sora nieuw is in de API, hebben we een recente versie van het pakket nodig.

We kunnen deze opdracht gebruiken om het te installeren (of de huidige versie te upgraden als die al is geïnstalleerd):

pip install --upgrade openai

Maak een nieuw script met de naam generate_video.py in dezelfde map als het eerder gemaakte .env-bestand.

De eerste stap is het importeren van de benodigde pakketten. Dit gebruiken we:

• os: Een ingebouwd pakket om met het besturingssysteem te communiceren;
• openai: Het officiële OpenAI-pakket om met hun API te communiceren;
• dotenv: Een ingebouwd pakket dat het laden van omgevingsvariabelen uit het .env-bestand vergemakkelijkt. In dit geval gebruiken we het om de OpenAI API-sleutel te laden.

import os
from openai import OpenAI 
from dotenv import load_dotenv

Vervolgens laden we het .env-bestand:

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

Met de API-sleutel in het geheugen kunnen we de OpenAI-client initialiseren, waarmee we verzoeken naar de OpenAI API kunnen sturen. We gebruiken de bibliotheek os om de API-sleutel te laden:

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

Tot slot gebruiken we de functie videos.create van de client om een video te genereren:

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

Wanneer we om videogeneratie vragen, krijgen we niet meteen een video, omdat het genereren best wat tijd kost. Dat betekent dat de variabele video niet de video zelf is, maar een object met informatie over de videogeneratie-taak.

Daarom hebben we de video-identificatie afgedrukt. Deze informatie hebben we nodig om:

1. De voortgang van de videogeneratie te volgen.
2. De video op te halen.

Beide stappen leggen we hieronder in detail uit.

Dit is het resultaat dat ik kreeg:

Voortgang van de video volgen

We kunnen de status van een taak ophalen door de taak-ID aan de functie videos.retrieve() te geven, zoals hier:

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

We moeten wachten tot de voortgang 100% is voordat we de video kunnen downloaden. Voor het gemak bouwen we een functie, wait_for_video_to_finish(), die de status van een taak bijhoudt totdat deze is voltooid:

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

De functie heeft drie parameters:

• video_id: De identifier van de video die we willen volgen.
• poll_interval: Hoeveel seconden we tussen elke check wachten.
• timeout: Het maximale aantal seconden dat we wachten.

Deze functie controleert periodiek de status van de video totdat deze voltooid is of de polltijd is verstreken.

De video downloaden

Nu we het generatieproces van de video kunnen volgen, hebben we alleen nog een manier nodig om hem te downloaden zodra hij klaar is. Dat kan met de functie videos.download_content().

Hier is een functie die dat doet:

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)

Volledige Sora-videogeneratieworkflow

We kunnen deze stappen combineren tot een workflow voor videogeneratie met 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)

De videomaat en -duur instellen

Het script hierboven gebruikt alleen een tekstprompt om de video te genereren. De OpenAI Sora 2-API biedt echter ook andere opties, zoals:

• model: Het model dat wordt gebruikt om de video te genereren. Standaard is dit sora-2.
• resolution: De grootte van de video. Standaard is de videomaat 720x1280.
• duration: Het aantal seconden dat de video duurt. Standaard is de video 4 seconden lang.

Hier is een tabel met alle mogelijke waarden per modus (de vetgedrukte waarden zijn de standaardwaarden):

Om het script makkelijker te gebruiken, kunnen we het ingebouwde pakket argparse benutten zodat de gebruiker de waarde van elke parameter kan opgeven.

Hier is een voorbeeld van hoe je de argumenten prompt en model instelt met 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).",
)

Om de argumenten te laden, roepen we de methode parse_args() aan, zoals hier:

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

Het generate_video_pipeline.py-script in de GitHub-repository zet alle onderdelen die we leerden bij elkaar tot een script dat video’s kan genereren met Sora 2.

Hier is een voorbeeld van hoe je het in de terminal uitvoert met specifieke parameters:

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

Dit was het resultaat:

Sora 2-API prompthulp

OpenAI biedt een complete promptgids voor Sora 2.

De belangrijkste ideeën voor een goede Sora 2-prompt zijn:

• Balans tussen detail en vrijheid: Specifieke prompts geven controle; eenvoudige geven ruimte voor creativiteit.
• Stel parameters in de API in: Definieer expliciet model (sora-2 of sora-2-pro), resolutie en cliplengte.
• Denk in shots: Beschrijf kadrering, belichting, onderwerp en één duidelijke actie per shot.
• Wees visueel en concreet: “Natte asfalt onder neonlichten” werkt beter dan “een mooie straat”.
• Houd de beweging simpel: Eén subjectactie + één camerabeweging werkt het best.
• Licht: Definieer lichtkwaliteit, -richting en kleurenpalet voor consistentie.
• Gebruik referentieafbeeldingen: Voeg een visuele input toe om stijl en compositie te verankeren.
• Dialoog: Korte, natuurlijke zinnen; duidelijk gelabeld; beperkt per clip.
• Itereren met Remix: Pas telkens één element aan (belichting, lens, palet) voor precieze controle.

Ze vatten deze ideeën samen in de volgende prompttemplate:

[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.]

Lange prompts in de terminal opgeven is onhandig. Om de gebruikerservaring te verbeteren, kunnen we ons script aanpassen zodat, als de prompt eindigt op .txt, het script ervan uitgaat dat de gebruiker het pad naar een tekstbestand met de prompt doorgeeft. 

Zo kunnen we het script bijwerken om dit te ondersteunen:

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

Om het te testen, heb ik in dezelfde map een bestand gemaakt met de naam prompt.txt met de volgende 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.”

Om de video te genereren, geven we prompt.txt door aan de parameter --prompt:

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

Hier is de video:

We zien dat de prompt niet volledig is gevolgd. Uit mijn ervaring met AI-videomodellen haal ik betere resultaten door meerdere eenvoudigere video’s te maken en die aan elkaar te monteren. 

Maar om dat te doen, moeten ze wel consistent zijn. Dat kunnen we bereiken door een referentieafbeelding aan het model te geven. Dat leer je hierna.

Sora 2-video’s genereren op basis van afbeeldingen

Om een video op basis van een afbeelding te genereren, gebruiken we de parameter input_reference.

Hier is een codefragment dat laat zien hoe je een afbeelding laadt en als referentie aan het model doorgeeft:

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)

Het script generate_video_with_reference.py in de GitHub-repository geeft hiervan een volledig werkend voorbeeld. Uitgevoerd op de referentieafbeelding kregen we dit:

Opdat de referentieafbeelding werkt, moet deze dezelfde afmetingen hebben als die welke is aangevraagd voor de videogeneratie.

We kunnen het pakket Pillow gebruiken om de referentieafbeelding automatisch te resizen voordat we die aan het model geven. Let er wel op dat als de beeldverhouding van de originele afbeelding heel anders is, deze vervormd raakt en de video waarschijnlijk niet erg goed wordt.

Installeer het met de opdracht:

pip install Pillow

Het script sora.py bevat een implementatie voor de functie generate_video() die de code van eerder aanpast om de afbeelding te resizen als die is meegegeven.

Het script generate_video_pipeline_reference.py laat zien hoe we de referentieparameter aan het videogeneratiescript kunnen toevoegen.

Hier is een voorbeeld dat is gegenereerd vanuit een foto met de zojuist geïmplementeerde auto-resizefunctie:

Videoreferenties gebruiken

Het script dat we hier hebben gebouwd, is klaar om zowel video- als afbeeldingsreferenties te verwerken. Telkens als ik echter probeerde een video te genereren met een andere video als referentie, kreeg ik een foutmelding:

Video inpaint is not available for your organization

Volgens hun forum lijkt dit een veelvoorkomend probleem, wat erop wijst dat deze functie nog niet voor iedereen via de API beschikbaar is. We zullen nog even moeten wachten voordat we het kunnen gebruiken.

Andere beperkingen

Tijdens mijn werk met Sora 2 liep ik vaak tegen problemen aan waarbij Sora weigerde de video te genereren, met de melding dat het verzoek door het moderatiesysteem was geblokkeerd:

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

Ik begrijp dat deze systemen strenge moderatie nodig hebben, omdat er veel schade kan worden aangericht als gebruikers zomaar elke gewenste video kunnen genereren. Toch heb ik het gevoel dat het moderatie-algoritme verfijnd moet worden, want het blokkeerde het merendeel van mijn verzoeken, waardoor ik mijn oorspronkelijke idee moest laten varen.

De foto’s die ik probeerde om te zetten naar video’s bevatten geen gevoelige inhoud of auteursrechtproblemen, omdat alle beelden van mij zijn. De foutmelding geeft ook geen informatie over de reden van de blokkade.

Dit gebeurde zo vaak dat het onmogelijk werd om iets zinvols te maken.

Conclusie

Sora 2 opent spannende nieuwe mogelijkheden voor AI-gestuurde videogeneratie, en dankzij de beschikbaarheid via de OpenAI API is het integreren van deze geavanceerde tools in je Python-workflow nu toegankelijk voor ontwikkelaars met uiteenlopende achtergronden.

Door deze tutorial te volgen, heb je nu een stevige basis om aangepaste video’s te maken met simpele prompts, je resultaten te verfijnen met geavanceerde parameters en afbeeldingsreferenties te benutten voor meer consistentie. Naarmate de API zich verder ontwikkelt, komen er nog meer functies beschikbaar — waaronder robuuste video-naar-video-mogelijkheden — waarmee je creatieve gereedschapskist verder wordt uitgebreid.

Of je nu experimenteert met speelse prompts, complexe storyboards bouwt of next-gen multimedia-apps ontwikkelt, Sora 2 biedt een krachtige manier om je ideeën tot leven te brengen. Ik raad ook onze gids voor Meta’s nieuwe SAM3-model aan.