Zum Hauptinhalt springen
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 Seite beantragen. Nach dem Aufruf der Seite klicken Sie auf die Schaltfläche „Acquire“, wie im Bild gezeigt: 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: 
{
  "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: 
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"
}'

​
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: 
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)
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: 
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)
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

ParameterTypPflichtfeldBeschreibung
versionstringJaMuss auf "2.0" gesetzt werden
promptstringJaPrompt zur Videoerzeugung
modelstringNeinsora-2 (Standard) oder sora-2-pro
durationintegerNeinVideolänge: 4 (Standard), 8, 12 Sekunden
sizestringNeinAuflösung: 720x1280 (Standard), 1280x720, 1024x1792, 1792x1024
image_urlsarrayNeinArray von Referenzbild-URLs, nur das erste Bild wird verwendet, Bildgröße muss mit size übereinstimmen
callback_urlstringNeinURL für asynchrone Rückrufe

​
Grundlegendes Beispiel

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"
}'
Entsprechender Python-Code: 
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)
Entsprechender JavaScript-Code: 
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);
Das Rückgabeformat ist identisch zu 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"
    }
  ]
}

​
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): 
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)
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

ParameterVersion 1.0Version 2.0
version1.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/, die nach Aufruf eine Webhook-URL bereitstellt, wie im Bild gezeigt: 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: Der Inhalt lautet: 
{
    "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

{
  "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.