Passer au contenu principal
Ce document présente les instructions d’intégration de l’API de génération de vidéos Sora, qui permet de générer des vidéos officielles Sora en entrant des paramètres personnalisés. Cette API prend en charge deux modes de version :
  • Version 1 (mode classique) : prend en charge les paramètres duration (10/15/25 secondes), orientation (paysage/portrait), size (small/large résolution), images de référence image_urls, lien de personnage character_url, etc.
  • Version 2 (mode partenaire) : prend en charge les paramètres seconds (4/8/12 secondes), résolution en pixels size (par exemple 1280x720), images de référence input_reference, etc.

​
Processus de demande

Pour utiliser l’API, vous devez d’abord faire une demande de service sur la page correspondante de Sora Videos Generation API. Une fois sur la page, cliquez sur le bouton « Acquire », comme illustré ci-dessous : Si vous n’êtes pas encore connecté ou inscrit, vous serez automatiquement redirigé vers la page de connexion pour vous inscrire et vous connecter. Après connexion, vous serez ramené automatiquement à cette page. Lors de la première demande, un quota gratuit est offert, vous permettant d’utiliser l’API gratuitement.

​
Utilisation de base (Version 1)

Commençons par comprendre l’utilisation de base de la Version 1, qui consiste à fournir un mot-clé prompt, un tableau de liens d’images de référence image_urls et un modèle model pour obtenir le résultat traité. Le détail est le suivant :

Ici, nous configurons les en-têtes de requête (Request Headers), notamment :
  • accept : format de réponse souhaité, ici application/json (format JSON).
  • authorization : clé d’API pour appeler l’API, sélectionnable dans la liste déroulante après demande.
Le corps de la requête (Request Body) comprend :
  • model : modèle de génération vidéo, supporte sora-2 (mode standard) et sora-2-pro (mode HD). sora-2-pro supporte une duration de 25 secondes, tandis que sora-2 supporte seulement 10 et 15 secondes.
  • size : résolution vidéo, small pour résolution standard, large pour HD (uniquement Version 1).
  • duration : durée de la vidéo, supporte 10, 15, 25 secondes, 25 secondes uniquement avec sora-2-pro (uniquement Version 1).
  • orientation : orientation de l’image, supporte landscape (paysage), portrait (portrait) (uniquement Version 1).
  • image_urls : tableau de liens d’images de référence, utilisé pour la génération vidéo à partir d’image (uniquement Version 1).
  • character_url : lien de personnage, la vidéo ne doit pas contenir de personnes réelles (uniquement Version 1).
  • character_start/character_end : secondes de début et fin d’apparition du personnage, plage de 1 à 3 secondes (uniquement Version 1).
  • prompt : mot-clé (obligatoire).
  • callback_url : URL pour le rappel asynchrone des résultats.
  • version : version de l’API, "1.0" (par défaut) ou "2.0".
Après sélection, le code correspondant est généré à droite, comme illustré :

Cliquez sur le bouton « Try » pour tester. Comme montré ci-dessus, nous obtenons le résultat suivant : 
{
  "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://filesystem.site/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"
    }
  ]
}
Les champs retournés sont :
  • success : état de la tâche de génération vidéo.
  • task_id : ID de la tâche de génération vidéo.
  • trace_id : ID de suivi de la tâche.
  • data : liste des résultats de la tâche.
    • id : ID de la vidéo générée.
    • video_url : URL de la vidéo générée.
    • state : état de la tâche.
Nous obtenons donc les informations vidéo souhaitées, il suffit de récupérer la vidéo Sora via le lien dans data. Pour générer le code d’intégration correspondant, vous pouvez copier directement, par exemple le code CURL : 
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": "cat running on the river",
  "model": "sora-2"
}'

​
Tâche de génération vidéo à partir d’images (Version 1)

Pour une tâche de génération vidéo à partir d’images, le paramètre image_urls doit contenir les liens des images de référence, permettant de spécifier :
  • image_urls : tableau de liens d’images de référence utilisées pour la génération vidéo. Ne pas fournir d’images réelles contenant des visages humains, cela pourrait entraîner l’échec de la tâche.
Exemple de saisie :

Le code généré automatiquement est :

Code correspondant : 
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": "cat running on the river",
    "model": "sora-2",
    "image_urls": ["https://cdn.acedata.cloud/11wfp4.png"]
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
Après exécution, un résultat immédiat est obtenu : 
{
  "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://filesystem.site/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"
    }
  ]
}
Le résultat montre que la génération vidéo à partir d’image a fonctionné, similaire à l’exemple précédent.

​
Tâche de génération vidéo de personnage (Version 1)

Pour une tâche de génération vidéo de personnage, le paramètre character_url doit contenir le lien vidéo nécessaire à la création du personnage. La vidéo ne doit pas contenir de personnes réelles, sinon la tâche échouera. Les paramètres sont :
  • character_url : lien vidéo pour créer le personnage, sans personnes réelles dans la vidéo.
Exemple de saisie :

Le code généré automatiquement est :

Code correspondant : 
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": "cat running on the river",
    "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)
Après exécution, un résultat immédiat est obtenu : 
{
  "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://filesystem.site/cdn/20251101/bee4eeeb4c4660b46dac4548a1ffbc.mp4",
      "state": "succeeded"
    }
  ]
}
Le résultat montre que la génération vidéo de personnage a fonctionné, similaire à l’exemple précédent.

​
Mode Version 2.0

En plus du mode Version 1.0, cette API prend également en charge le mode Version 2.0, activé en réglant le paramètre version à "2.0". Le mode Version 2.0 supporte des durées vidéo plus courtes et un contrôle de résolution au niveau pixel.

​
Description des paramètres Version 2.0

ParamètreTypeObligatoireDescription
versionstringOuiDoit être réglé sur "2.0"
promptstringOuiMot-clé pour générer la vidéo
modelstringNonsora-2 (par défaut) ou sora-2-pro
durationintegerNonDurée vidéo : 4 (par défaut), 8, 12 secondes
sizestringNonRésolution : 720x1280 (par défaut), 1280x720, 1024x1792, 1792x1024
image_urlsarrayNonTableau d’URL d’images de référence, seule la première image est utilisée, la taille doit correspondre à size
callback_urlstringNonURL pour rappel asynchrone

​
Exemple de base

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": "cat running on the river",
  "model": "sora-2",
  "duration": 8,
  "size": "1280x720"
}'
Code Python correspondant : 
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": "cat running on the river",
    "model": "sora-2",
    "seconds": 8,
    "size": "1280x720"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
Code JavaScript correspondant : 
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: 'cat running on the river',
    model: 'sora-2',
    seconds: 8,
    size: '1280x720'
  })
});
const data = await response.json();
console.log(data);
Le format de réponse est identique à celui de la Version 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"
    }
  ]
}

​
Utilisation d’images de référence (Version 2.0)

En mode Version 2.0, vous pouvez passer des images de référence via le paramètre image_urls pour guider la génération vidéo (seule la première image est utilisée) : 
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": "a person walking through a beautiful garden",
    "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)
Remarque : la taille de l’image de référence doit correspondre au paramètre size. Par exemple, si size est 1280x720, l’image doit mesurer 1280×720 pixels.

​
Comparaison des paramètres Version 1.0 et Version 2.0

ParamètreVersion 1.0Version 2.0
version1.0 (par défaut)2.0
prompt✅✅
model✅ sora-2 / sora-2-pro✅ sora-2 / sora-2-pro
duration✅ 10/15/25 secondes✅ 4/8/12 secondes
orientation✅ landscape/portrait❌
size✅ small/large✅ 720x1280/1280x720/1024x1792/1792x1024
image_urls✅ plusieurs images✅ seule la première image
character_url✅❌
callback_url✅✅

​
Rappel asynchrone

La génération vidéo avec l’API Sora Videos Generation prend environ 1 à 2 minutes. Si l’API ne répond pas rapidement, la requête HTTP reste ouverte, consommant des ressources système supplémentaires. C’est pourquoi l’API propose également un support de rappel asynchrone. Le processus est le suivant : le client envoie la requête en spécifiant un champ callback_url. L’API retourne immédiatement un résultat contenant un task_id représentant l’ID de la tâche. Une fois la tâche terminée, le résultat de la vidéo générée est envoyé en POST JSON à l’URL callback_url du client, incluant également le champ task_id pour associer le résultat à la tâche. Voyons un exemple concret. Tout d’abord, un webhook est un service pouvant recevoir des requêtes HTTP. Le développeur doit remplacer par l’URL de son propre serveur HTTP. Pour la démonstration, nous utilisons un site public de webhook https://webhook.site/, qui fournit une URL webhook comme illustré : Copiez cette URL, par exemple https://webhook.site/eb238c4f-da3b-47a5-a922-a93aa5405daa, qui servira de webhook. Ensuite, configurez le champ callback_url avec cette URL et remplissez les autres paramètres, comme illustré :

Après exécution, un résultat immédiat est obtenu : 
{
  "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea"
}
Après un court délai, vous pouvez observer le résultat de la génération vidéo sur https://webhook.site/eb238c4f-da3b-47a5-a922-a93aa5405daa, comme montré : Contenu : 
{
    "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://filesystem.site/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"
        }
    ]
}
Le champ task_id permet d’associer les résultats à la tâche correspondante.

​
Gestion des erreurs

Lors de l’appel à l’API, en cas d’erreur, l’API retourne un code d’erreur et un message correspondant, par exemple :
  • 400 token_mismatched : Requête incorrecte, paramètres manquants ou invalides.
  • 400 api_not_implemented : Requête incorrecte, paramètres manquants ou invalides.
  • 401 invalid_token : Non autorisé, jeton d’autorisation invalide ou manquant.
  • 429 too_many_requests : Trop de requêtes, limite de fréquence dépassée.
  • 500 api_error : Erreur interne du serveur.

​
Exemple de réponse d’erreur

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​
Conclusion

Ce document vous a permis de comprendre comment utiliser l’API Sora Videos Generation pour générer des vidéos à partir de mots-clés et d’images de référence. Nous espérons que ce guide vous aidera à intégrer et utiliser cette API efficacement. Pour toute question, n’hésitez pas à contacter notre équipe de support technique.