> ## Documentation Index > Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt > Use this file to discover all available pages before exploring further. # Instructions d’intégration de l’API de génération de vidéos Sora > Sora Video Generation 集成指南 - XHuoAPI 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](https://api.xhuoapi.ai/documents/99a24421-2e22-4028-8201-e19cb834b67e). Une fois sur la page, cliquez sur le bouton « Acquire », comme illustré ci-dessous : ![](https://cdn.xhuoapi.ai/q6ytrc.png) 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 : ```json theme={null} { "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 : ```shell theme={null} curl -X POST 'https://api.xhuoapi.ai/v1/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 : ```python theme={null} import requests url = "https://api.xhuoapi.ai/v1/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.xhuoapi.ai/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 : ```python theme={null} import requests url = "https://api.xhuoapi.ai/v1/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.xhuoapi.ai/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ètre | Type | Obligatoire | Description | | -------------- | ------- | ----------- | --------------------------------------------------------------------------------------------------------------- | | `version` | string | Oui | Doit être réglé sur `"2.0"` | | `prompt` | string | Oui | Mot-clé pour générer la vidéo | | `model` | string | Non | `sora-2` (par défaut) ou `sora-2-pro` | | `duration` | integer | Non | Durée vidéo : `4` (par défaut), `8`, `12` secondes | | `size` | string | Non | Résolution : `720x1280` (par défaut), `1280x720`, `1024x1792`, `1792x1024` | | `image_urls` | array | Non | Tableau d’URL d’images de référence, seule la première image est utilisée, la taille doit correspondre à `size` | | `callback_url` | string | Non | URL pour rappel asynchrone | ### Exemple de base ```shell theme={null} curl -X POST 'https://api.xhuoapi.ai/v1/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 : ```python theme={null} import requests url = "https://api.xhuoapi.ai/v1/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 : ```javascript theme={null} const response = await fetch('https://api.xhuoapi.ai/v1/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 : ```json theme={null} { "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.xhuoapi.ai/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) : ```python theme={null} import requests url = "https://api.xhuoapi.ai/v1/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.xhuoapi.ai/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ètre | Version 1.0 | Version 2.0 | | --------------- | --------------------- | --------------------------------------- | | `version` | 1.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/](https://webhook.site/), qui fournit une URL webhook comme illustré : ![](https://cdn.xhuoapi.ai/cjjfly.png) 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é : ![](https://cdn.xhuoapi.ai/0j7nra.png) Contenu : ```json theme={null} { "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 ```json theme={null} { "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.