API Sora 2 avec Python : guide complet avec exemples

Premiers pas avec l’API OpenAI

Pour commencer, il faut créer un compte OpenAI et une clé d’API. Pour cela, rendez-vous sur leur page des clés d’API et cliquez sur « Create new secret key » en haut à droite.

Cette clé sert à effectuer des requêtes vers l’API OpenAI. Nous la stockons dans un fichier nommé .env dans le dossier où nous écrivons nos scripts Python. Veillez à garder cette clé secrète, car n’importe qui pourrait l’utiliser pour interagir avec l’API via votre compte.

Collez la clé API dans le fichier .env au format suivant :

OPENAI_API_KEY=<paste_api_key_here>Propulsé par

Notez que l’utilisation de l’API n’est pas gratuite ; il est donc nécessaire d’alimenter votre compte avant d’être en mesure de générer des vidéos avec Sora 2. À titre indicatif, voici le tarif par seconde de Sora 2 :

Générer une vidéo Sora 2 avec Python

L’intégralité du code de ce tutoriel est disponible dans ce dépôt GitHub.

Pour communiquer avec l’API OpenAI en Python, nous utiliserons le paquet openai. Notez que Sora étant récent sur l’API, il faut une version récente du paquet.

Utilisez cette commande pour l’installer (ou mettre à jour la version existante) :

pip install --upgrade openaiPropulsé par

Créez un nouveau script nommé generate_video.py dans le même dossier que le fichier .env créé plus haut.

La première étape consiste à importer les paquets nécessaires. Voici ceux que nous allons utiliser :

• os : un module standard pour interagir avec le système d’exploitation ;
• openai : le paquet officiel OpenAI pour interagir avec leur API ;
• dotenv : un paquet qui facilite le chargement des variables d’environnement depuis le fichier .env. Ici, on l’utilise pour charger la clé API OpenAI.

import os
from openai import OpenAI 
from dotenv import load_dotenvPropulsé par

Ensuite, chargeons le fichier .env :

load_dotenv()
API_KEY = os.getenv("OPENAI_API_KEY")Propulsé par

Avec la clé API en mémoire, nous pouvons initialiser le client OpenAI, qui nous permet d’envoyer des requêtes à l’API OpenAI. Nous utilisons la bibliothèque os pour charger la clé API :

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

Enfin, nous utilisons la fonction videos.create du client pour générer une vidéo :

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

Lors d’une demande de génération, la vidéo n’est pas fournie immédiatement car le processus prend du temps. Cela signifie que la variable video ne contient pas la vidéo elle‑même, mais un objet décrivant la tâche de génération.

C’est pour cela que nous avons affiché l’identifiant de la vidéo. Cette information sera nécessaire pour :

1. Suivre l’avancement de la génération.
2. Récupérer la vidéo.

Nous détaillons ces deux étapes ci‑dessous.

Voici le résultat que j’ai obtenu :

Suivre l’avancement

Nous pouvons récupérer le statut d’une tâche en fournissant son identifiant à la fonction videos.retrieve(), comme ceci :

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

Il faut attendre que la progression atteigne 100 % pour pouvoir télécharger la vidéo. Pour plus de confort, créons une fonction wait_for_video_to_finish() qui surveille l’état d’une tâche jusqu’à son achèvement :

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")Propulsé par

La fonction prend trois paramètres :

• video_id : l’identifiant de la vidéo à suivre.
• poll_interval : le nombre de secondes à attendre entre deux vérifications.
• timeout : le délai maximal d’attente, en secondes.

Cette fonction vérifie périodiquement le statut de la vidéo jusqu’à son achèvement ou l’expiration du délai.

Télécharger la vidéo

Maintenant que nous savons suivre la génération, il nous faut un moyen de la télécharger une fois terminée. Pour cela, on utilise la fonction videos.download_content().

Voici une fonction qui s’en charge :

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)Propulsé par

Workflow complet de génération Sora

Assemblons ces étapes pour construire un workflow de génération de vidéo avec 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)Propulsé par

Définir la taille et la durée de la vidéo

Le script ci‑dessus se contente d’un prompt texte pour générer la vidéo. Cependant, l’API OpenAI Sora 2 propose d’autres options, telles que :

• model : le modèle utilisé pour générer la vidéo. Par défaut : sora-2.
• resolution : la taille de la vidéo. Par défaut : 720x1280.
• duration : la durée en secondes. Par défaut : 4 secondes.

Voici un tableau récapitulant les valeurs possibles selon le mode (en gras : les valeurs par défaut) :

Pour faciliter l’usage du script, nous pouvons utiliser le module standard argparse afin de permettre à l’utilisateur de renseigner la valeur de chaque paramètre.

Voici un exemple pour définir les arguments prompt et model avec 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).",
)Propulsé par

Pour charger les arguments, on appelle la méthode parse_args() :

args = parser.parse_args()
prompt = args.prompt
model = args.modelPropulsé par

Le script generate_video_pipeline.py dans le dépôt GitHub réunit toutes les briques vues ici dans un script capable de générer des vidéos avec Sora 2.

Exemple d’exécution en terminal avec des paramètres précis :

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

Voici le résultat :

Conseils de prompt pour l’API Sora 2

OpenAI propose un guide de prompt complet pour Sora 2.

Les principes clés pour rédiger un bon prompt Sora 2 sont :

• Équilibrer précision et liberté : des prompts précis donnent du contrôle ; des prompts simples favorisent la créativité.
• Définir les paramètres dans l’API : indiquez explicitement le modèle (sora-2 ou sora-2-pro), la résolution et la durée du clip.
• Raisonner en plans : décrivez le cadrage, la lumière, le sujet et une action claire par plan.
• Être visuel et concret : « Asphalte mouillé sous néons » est plus parlant que « une belle rue ».
• Garder des mouvements simples : une action de sujet + un mouvement caméra fonctionne le mieux.
• Lumière : définissez qualité, direction et palette de couleurs pour la cohérence.
• Utiliser des références d’images : ajoutez un visuel d’appui pour ancrer le style et la composition.
• Dialogue : répliques courtes et naturelles ; étiquetées clairement ; en nombre limité par clip.
• Itérer avec Remix : ajustez un élément à la fois (lumière, focale, palette) pour un contrôle fin.

Ils condensent ces idées dans le modèle de prompt suivant :

[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.]Propulsé par

Saisir de longs prompts dans le terminal n’est pas pratique. Pour améliorer l’expérience, adaptons notre script : si le prompt se termine par .txt, le script suppose que l’utilisateur fournit le chemin d’un fichier texte contenant le prompt.

Voici comment mettre à jour le script pour le prendre en charge :

...
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)
...Propulsé par

Pour tester, j’ai créé dans le même dossier un fichier prompt.txt avec le prompt suivant :

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.”Propulsé par

Pour générer la vidéo, nous passons prompt.txt au paramètre --prompt :

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

Voici la vidéo :

On constate que le résultat ne suit pas entièrement le prompt. D’expérience avec les modèles vidéo IA, j’obtiens de meilleurs résultats en réalisant plusieurs vidéos plus simples puis en les assemblant.

Pour cela, il faut toutefois assurer la cohérence entre les clips. On peut y parvenir en fournissant une image de référence au modèle. C’est ce que nous allons voir maintenant.

Générer des vidéos Sora 2 à partir d’images

Pour générer une vidéo à partir d’une image, nous utilisons le paramètre input_reference.

Voici un extrait de code montrant comment charger une image et la fournir au modèle en référence :

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)Propulsé par

Le script generate_video_with_reference.py dans le dépôt GitHub propose un exemple complet et fonctionnel. Exécuté sur l’image de référence, nous avons obtenu ceci :

Pour que l’image de référence fonctionne, elle doit avoir la même taille que celle demandée pour la génération de la vidéo.

Nous pouvons utiliser le paquet Pillow pour redimensionner automatiquement l’image de référence avant de la fournir au modèle. Notez cependant que si le ratio d’origine est très différent, l’image sera déformée et la vidéo risque d’être décevante.

Pour l’installer, utilisez la commande :

pip install PillowPropulsé par

Le script sora.py propose une implémentation de la fonction generate_video() qui adapte notre code pour redimensionner l’image si elle est fournie.

Le script generate_video_pipeline_reference.py montre comment nous pouvons ajouter le paramètre de référence au script de génération.

Voici un exemple généré à partir d’une photo avec la fonction de redimensionnement automatique que nous venons d’ajouter :

Utiliser des références vidéo

Le script que nous avons construit peut gérer des références vidéo aussi bien qu’image. Toutefois, à chaque tentative de génération avec une vidéo en référence, j’ai obtenu l’erreur suivante :

Video inpaint is not available for your organizationPropulsé par

D’après leur forum, il semble que ce soit un problème courant, ce qui indique que cette fonctionnalité n’est pas encore disponible pour tout le monde via l’API. Il faudra patienter encore un peu.

Autres limitations

En travaillant avec Sora 2, je me suis souvent heurté à des refus de génération, le système indiquant que la requête avait été bloquée par la modération :

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

Je comprends la nécessité d’une modération stricte, car l’on peut causer beaucoup de tort si l’on laisse générer n’importe quel contenu. Néanmoins, l’algorithme me paraît perfectible : il a bloqué la plupart de mes requêtes, m’obligeant à abandonner mon idée initiale.

Les photos que j’ai essayé de transformer en vidéos ne contenaient pas de contenu sensible ni de problèmes de droits ; toutes les images m’appartiennent. Le message d’erreur n’indique pas non plus la raison du blocage.

Ce problème est survenu très fréquemment, rendant impossible la création de quelque chose de réellement exploitable.

Conclusion

Sora 2 ouvre des perspectives enthousiasmantes pour la génération vidéo par l’IA et, grâce à sa disponibilité via l’API OpenAI, l’intégration de ces outils de pointe dans vos workflows Python devient accessible à des développeurs de tous horizons.

En suivant ce tutoriel, vous disposez désormais d’une base solide pour créer des vidéos personnalisées à partir de prompts, affiner vos résultats avec des paramètres avancés et exploiter des images de référence pour davantage de cohérence. À mesure que l’API évoluera, d’autres fonctionnalités — y compris des capacités robustes de vidéo‑à‑vidéo — viendront enrichir votre boîte à outils créative.

Que vous expérimentiez des prompts ludiques, construisiez des storyboards complexes ou développiez des applications multimédias de nouvelle génération, Sora 2 offre un puissant moyen de donner vie à vos idées. Nous vous recommandons aussi de consulter notre guide sur le nouveau modèle SAM3 de Meta.