> ## 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. # Sora Videos Generation API Integrationsanleitung > Sora Video Generation 集成指南 - XHuoAPI Dieser Artikel beschreibt die Integrationsanleitung für die Sora Videos Generation API. Mit dieser API können Sie benutzerdefinierte Parameter eingeben, um offizielle Sora-Videos zu generieren. Die API unterstützt zwei Versionsmodi: * **Version 1 (klassischer Modus)**: Unterstützt Parameter wie `duration` (10/15/25 Sekunden), `orientation` (Querformat/Hochformat), `size` (small/large Auflösung), Referenzbilder `image_urls`, Charakter-**###** `character_url` usw. * **Version 2 (Partner-Modus)**: Unterstützt `seconds` (4/8/12 Sekunden), pixelgenaue Auflösung `size` (z.B. 1280x720), Referenzbild `input_reference` usw. ## Antragsprozess Um die API zu nutzen, müssen Sie zunächst den entsprechenden Dienst auf der [Sora Videos Generation API](https://api.xhuoapi.ai/documents/99a24421-2e22-4028-8201-e19cb834b67e) Seite beantragen. Nach dem Aufruf der Seite klicken Sie auf die Schaltfläche „Acquire“, wie im Bild gezeigt: ![](https://cdn.xhuoapi.ai/q6ytrc.png) Wenn Sie noch nicht angemeldet oder registriert sind, werden Sie automatisch zur Anmeldeseite weitergeleitet, um sich zu registrieren und anzumelden. Nach der Anmeldung kehren Sie automatisch zur aktuellen Seite zurück. Bei der ersten Beantragung erhalten Sie ein kostenloses Kontingent, mit dem Sie die API kostenlos nutzen können. ## Grundlegende Nutzung (Version 1) Zuerst lernen wir die grundlegende Nutzung von Version 1 kennen: Sie geben den Prompt `prompt`, ein Array von Referenzbild-URLs `image_urls` und das Modell `model` ein, um das Ergebnis zu erhalten. Die Details sind wie folgt:

Hier sehen wir, dass wir die Request Headers setzen, darunter: * `accept`: Das gewünschte Antwortformat, hier `application/json` für JSON-Format. * `authorization`: Der API-Schlüssel, der nach Beantragung direkt ausgewählt werden kann. Außerdem wird der Request Body gesetzt mit: * `model`: Das Modell zur Videoerzeugung, unterstützt `sora-2` (Standardmodus) und `sora-2-pro` (HD-Modus). `sora-2-pro` unterstützt Videos mit `duration` von 25 Sekunden, `sora-2` nur 10 oder 15 Sekunden. * `size`: Videoauflösung, `small` für Standardauflösung, `large` für HD-Auflösung (nur Version 1). * `duration`: Videolänge, unterstützt 10, 15, 25 Sekunden, wobei 25 Sekunden nur von `sora-2-pro` unterstützt werden (nur Version 1). * `orientation`: Bildformat, unterstützt `landscape` (Querformat), `portrait` (Hochformat) (nur Version 1). * `image_urls`: Array von Referenzbild-URLs für Bild-zu-Video (nur Version 1). * `character_url`: Charakter-**###** URL, im Video dürfen keine realen Personen erscheinen (nur Version 1). * `character_start`/`character_end`: Start- und Endzeitpunkt des Charakters in Sekunden, Differenz 1-3 Sekunden (nur Version 1). * `prompt`: Prompt (Pflichtfeld). * `callback_url`: URL für asynchrone Rückrufe. * `version`: API-Version, `"1.0"` (Standard) oder `"2.0"`. Nach Auswahl sehen Sie, dass rechts der entsprechende Code generiert wird, wie im Bild gezeigt:

Klicken Sie auf die Schaltfläche „Try“, um den Test durchzuführen. Im obigen Beispiel erhalten wir folgendes Ergebnis: ```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" } ] } ``` Die Antwort enthält mehrere Felder, die wie folgt erklärt werden: * `success`: Status der Videoerzeugungsaufgabe. * `task_id`: ID der Videoerzeugungsaufgabe. * `trace_id`: Tracking-ID der Videoerzeugung. * `data`: Ergebnisliste der Videoerzeugungsaufgabe. * `id`: Video-ID der Aufgabe. * `video_url`: Video-URL der Aufgabe. * `state`: Status der Aufgabe. Sie sehen, dass wir die gewünschten Video-Informationen erhalten haben. Sie können das generierte Sora-Video über die Video-URL im Feld `data` abrufen. Wenn Sie den entsprechenden Integrationscode generieren möchten, können Sie diesen direkt kopieren, zum Beispiel CURL-Code: ```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" }' ``` ## Bild-zu-Video-Aufgabe (Version 1) Für eine Bild-zu-Video-Aufgabe muss der Parameter `image_urls` mit Referenzbild-URLs übergeben werden, um folgende Inhalte zu spezifizieren: * `image_urls`: Array von Referenzbild-URLs für die Bild-zu-Video-Aufgabe. Bitte keine echten Personenbilder mit Gesichtern übermitteln, da dies zum Fehlschlag der Aufgabe führen kann. Beispielausfüllung:

Nach dem Ausfüllen wird der Code automatisch generiert:

Der entsprechende Code lautet: ```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) ``` Nach Ausführung erhalten Sie sofort ein Ergebnis: ``` { "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" } ] } ``` Das Ergebnis zeigt, dass das Video erfolgreich aus dem Bild generiert wurde, ähnlich wie oben beschrieben. ## Charakter-Video-Erzeugungsaufgabe (Version 1) Für eine Charakter-Video-Erzeugungsaufgabe muss der Parameter `character_url` mit der Video-URL des zu erstellenden Charakters übergeben werden. Das Video darf keine realen Personen enthalten, sonst schlägt die Aufgabe fehl. Folgende Inhalte können so spezifiziert werden: * `character_url`: Video-URL für die Charaktererstellung, das Video darf keine realen Personen enthalten, sonst schlägt die Aufgabe fehl. Beispielausfüllung:

Nach dem Ausfüllen wird der Code automatisch generiert:

Der entsprechende Code lautet: ```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) ``` Nach Ausführung erhalten Sie sofort ein Ergebnis: ``` { "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" } ] } ``` Das Ergebnis zeigt, dass das Video erfolgreich mit Charaktererzeugung generiert wurde, ähnlich wie oben beschrieben. ## Version 2.0 Modus Neben dem oben beschriebenen Version 1.0 Modus unterstützt die API auch den Version 2.0 Modus, der durch Setzen des Parameters `version` auf `"2.0"` aktiviert wird. Version 2.0 unterstützt kürzere Videolängen und pixelgenaue Auflösungskontrolle. ### Parameterbeschreibung Version 2.0 | Parameter | Typ | Pflichtfeld | Beschreibung | | -------------- | ------- | ----------- | -------------------------------------------------------------------------------------------------------- | | `version` | string | Ja | Muss auf `"2.0"` gesetzt werden | | `prompt` | string | Ja | Prompt zur Videoerzeugung | | `model` | string | Nein | `sora-2` (Standard) oder `sora-2-pro` | | `duration` | integer | Nein | Videolänge: `4` (Standard), `8`, `12` Sekunden | | `size` | string | Nein | Auflösung: `720x1280` (Standard), `1280x720`, `1024x1792`, `1792x1024` | | `image_urls` | array | Nein | Array von Referenzbild-URLs, nur das erste Bild wird verwendet, Bildgröße muss mit `size` übereinstimmen | | `callback_url` | string | Nein | URL für asynchrone Rückrufe | ### Grundlegendes Beispiel ```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" }' ``` Entsprechender Python-Code: ```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) ``` Entsprechender JavaScript-Code: ```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); ``` Das Rückgabeformat ist identisch zu 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" } ] } ``` ### Verwendung von Referenzbildern (Version 2.0) Im Version 2.0 Modus können Sie über den Parameter `image_urls` Referenzbilder zur Steuerung der Videoerzeugung übergeben (nur das erste Bild wird verwendet): ```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) ``` > **Hinweis**: Die Größe des Referenzbildes sollte mit dem Parameter `size` übereinstimmen, z.B. bei `size` = `1280x720` sollte das Bild 1280×720 Pixel groß sein. ### Parametervergleich Version 1.0 und Version 2.0 | Parameter | Version 1.0 | Version 2.0 | | --------------- | ------------------------ | --------------------------------------- | | `version` | 1.0 (Standard) | 2.0 | | `prompt` | ✅ | ✅ | | `model` | ✅ sora-2 / sora-2-pro | ✅ sora-2 / sora-2-pro | | `duration` | ✅ 10/15/25 Sekunden | ✅ 4/8/12 Sekunden | | `orientation` | ✅ landscape/portrait | ❌ | | `size` | ✅ small/large | ✅ 720x1280/1280x720/1024x1792/1792x1024 | | `image_urls` | ✅ mehrere Referenzbilder | ✅ nur das erste Bild | | `character_url` | ✅ | ❌ | | `callback_url` | ✅ | ✅ | ## Asynchrone Rückrufe Da die Generierung von Videos mit der Sora Videos Generation API relativ lange dauert (ca. 1-2 Minuten), hält die HTTP-Anfrage bei langer Wartezeit die Verbindung offen, was zu zusätzlichem Ressourcenverbrauch führen kann. Daher unterstützt die API auch asynchrone Rückrufe. Der Ablauf ist folgender: Der Client gibt beim API-Aufruf zusätzlich das Feld `callback_url` an. Die API antwortet sofort mit einem Ergebnis, das die `task_id` enthält, welche die aktuelle Aufgabe identifiziert. Nach Abschluss der Aufgabe sendet die API das Ergebnis per POST-JSON an die angegebene `callback_url`, inklusive der `task_id`, sodass die Aufgabe eindeutig zugeordnet werden kann. Im Folgenden ein Beispiel zur Veranschaulichung. Zunächst ist der Webhook ein Dienst, der HTTP-Anfragen empfangen kann. Entwickler sollten die URL ihres eigenen HTTP-Servers angeben. Zur Demonstration verwenden wir die öffentliche Webhook-Beispielseite [https://webhook.site/](https://webhook.site/), die nach Aufruf eine Webhook-URL bereitstellt, wie im Bild gezeigt: ![](https://cdn.xhuoapi.ai/cjjfly.png) Kopieren Sie diese URL, z.B. `https://webhook.site/eb238c4f-da3b-47a5-a922-a93aa5405daa`, und verwenden Sie sie als Webhook. Dann setzen wir das Feld `callback_url` auf diese Webhook-URL und füllen die übrigen Parameter aus, wie im Bild gezeigt:

Nach Ausführung erhalten wir sofort ein Ergebnis: ``` { "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea" } ``` Nach kurzer Zeit können wir auf `https://webhook.site/eb238c4f-da3b-47a5-a922-a93aa5405daa` das Ergebnis der Videoerzeugung sehen, wie im Bild gezeigt: ![](https://cdn.xhuoapi.ai/0j7nra.png) Der Inhalt lautet: ```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" } ] } ``` Sie sehen, dass das Ergebnis ein Feld `task_id` enthält. Die anderen Felder sind wie oben beschrieben. Über dieses Feld kann die Aufgabe eindeutig zugeordnet werden. ## Fehlerbehandlung Wenn bei der API-Nutzung Fehler auftreten, gibt die API entsprechende Fehlercodes und Informationen zurück, z.B.: * `400 token_mismatched`: Ungültige Anfrage, möglicherweise fehlende oder ungültige Parameter. * `400 api_not_implemented`: Ungültige Anfrage, möglicherweise fehlende oder ungültige Parameter. * `401 invalid_token`: Nicht autorisiert, ungültiger oder fehlender Authentifizierungstoken. * `429 too_many_requests`: Zu viele Anfragen, Sie haben das Limit überschritten. * `500 api_error`: Interner Serverfehler, ein Fehler auf dem Server ist aufgetreten. ### Beispiel für Fehlerantwort ```json theme={null} { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## Fazit Mit diesem Dokument haben Sie gelernt, wie Sie die Sora Videos Generation API nutzen können, um durch Eingabe von Prompts und Referenzbildern Videos zu generieren. Wir hoffen, dass Ihnen diese Anleitung bei der Integration und Nutzung der API hilft. Bei Fragen wenden Sie sich bitte jederzeit an unser technisches Support-Team.