Anleitung zur Integration der Gemini Videos Generation API

Dieser Artikel stellt die Anleitung zur Integration der Gemini Videos Generation API vor, mit der durch die Eingabe von Text-Prompts (sowie optionalen Referenzbildern) Google-Gemini-Videos (omni-flash) generiert werden können.

Antragsprozess

Um die Gemini Videos Generation API zu verwenden, rufen Sie zunächst in der Ace Data Cloud-Konsole Ihren API-Token ab und bewahren Sie ihn als Reserve auf.

Wenn Sie noch nicht angemeldet oder registriert sind, werden Sie automatisch zur Anmeldeseite weitergeleitet, um sich zu registrieren und anzumelden. Nach Abschluss kehren Sie automatisch zu dieser Seite zurück. Ein API-Token kann alle Dienste der Plattform aufrufen, ohne dass für jeden Dienst ein separater Antrag erforderlich ist. Bei der ersten Beantragung wird ein kostenloses Guthaben gewährt, das kostenlos getestet werden kann; bei unzureichendem Guthaben kann in der Konsole ein allgemeines Guthaben aufgeladen werden.

📘 Vollständige Dokumentation: Gemini Videos Generation API →

Grundlegende Verwendung

Lernen wir zunächst die grundlegende Verwendung kennen. Durch die Eingabe des Prompts prompt, des Modells model sowie des Seitenverhältnisses aspect_ratio kann das entsprechende Video generiert werden. Hier ist zu sehen, dass wir Request Headers festgelegt haben, einschließlich:

accept: In welchem Format die Antwortergebnisse empfangen werden sollen. Hier wird application/json angegeben, also das JSON-Format.
authorization: Der Schlüssel zum Aufrufen der API, der nach der Beantragung direkt über ein Dropdown ausgewählt werden kann.

Zusätzlich wurde der Request Body festgelegt, einschließlich:

prompt: Der Text-Prompt zur Beschreibung des gewünschten Videoinhalts, erforderlich.
model: Das Modell zur Videogenerierung. Derzeit wird nur omni-flash unterstützt, der Standardwert ist ebenfalls omni-flash.
aspect_ratio: Das Seitenverhältnis des generierten Videos. Es kann 16:9 (Querformat) oder 9:16 (Hochformat) gewählt werden, der Standardwert ist 16:9.
resolution: Die optionale Ausgabeauflösung. Es kann 720p oder 1080p gewählt werden, der Standardwert ist 720p.
image_urls: Optionales Array von Referenzbild-Links zur Steuerung der Videogenerierung; leere Einträge werden ignoriert. Bei der Videobearbeitung mit video_urls ist dieser Parameter erforderlich (mindestens ein Bild).
video_urls: Optionales Array von Referenzvideo-Links (maximal 1) für Videobearbeitung / Videoreferenz; bei Angabe muss gleichzeitig mindestens ein image_urls bereitgestellt werden.
callback_url: Asynchrone Callback-Adresse. Nach dem Festlegen gibt die API sofort task_id zurück und sendet bei Abschluss der Aufgabe das Ergebnis per POST an diese Adresse.
async: Optional. Wenn es auf true gesetzt wird, gibt die Schnittstelle sofort task_id zurück, ohne dass callback_url angegeben werden muss. Anschließend wird das Ergebnis durch Abfragen der entsprechenden Task-Abfrage-Schnittstelle abgerufen.

Klicken Sie zum Testen auf die Schaltfläche „Try“. Das erhaltene Ergebnis sieht etwa wie folgt aus:

{
  "success": true,
  "task_id": "9258c45f-bed9-4dde-81c2-a70a710a6904",
  "trace_id": "862d6aae-cec0-407f-9524-bc1be2291bcb",
  "data": [
    {
      "id": "dc4b7292-070c-49a8-8183-919bdf8ad59e",
      "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/9258c45f-bed9-4dde-81c2-a70a710a6904-418c13e0605f.mp4",
      "state": "succeeded",
      "aspect_ratio": "16:9",
      "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden"
    }
  ],
  "started_at": 1784112953.856,
  "finished_at": 1784113021.328,
  "elapsed": 67.472,
  "cost": {
    "amount": 1.932,
    "currency": "credit",
    "list_amount": 2.1
  }
}

Das Rückgabeergebnis enthält mehrere Felder, die wie folgt beschrieben werden:

success: Ob diese Anfrage zur Videogenerierung erfolgreich war.
task_id: Die ID dieser Videogenerierungsaufgabe.
trace_id: Die Tracking-ID dieser Anfrage, die zur Fehleranalyse verwendet wird.
data: Liste der generierten Videoergebnisse.
- id: Die eindeutige Kennung des generierten Videos.
- video_url: Die Link-Adresse des generierten Videos (bei state = pending ist sie null).
- state: Der Status der Videogenerierungsaufgabe; mögliche Werte sind pending / succeeded / failed.
- aspect_ratio: Das Seitenverhältnis dieses Videos, das mit dem Anfrageparameter übereinstimmt.
- prompt: Der zur Generierung dieses Videos verwendete Prompt.

Bei synchroner Rückgabe werden auf oberster Ebene auch Felder wie started_at, finished_at, elapsed (Dauer, Sekunden) sowie cost (Kosten dieser Anfrage, Einheit: Credit) hinzugefügt. Wir müssen nur das generierte Video über die Link-Adresse video_url in data im Ergebnis abrufen. Der entsprechende CURL-Code lautet wie folgt:

curl -X POST 'https://api.acedata.cloud/gemini/videos' \
-H 'authorization: Bearer ${bearer_token}' \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-d '{
  "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden",
  "model": "omni-flash",
  "aspect_ratio": "16:9"
}'

Der entsprechende Python-Code lautet wie folgt:

import requests

url = "https://api.acedata.cloud/gemini/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden",
    "model": "omni-flash",
    "aspect_ratio": "16:9"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Bild-zu-Video

Wenn Sie ein Video auf Basis von Referenzbildern generieren möchten, können Sie in image_urls einen oder mehrere Bild-Links übergeben, um die Videogenerierung zu steuern:

{
  "prompt": "The woman slowly turns around and smiles at the camera, gentle breeze",
  "model": "omni-flash",
  "aspect_ratio": "9:16",
  "image_urls": [
    "https://cdn.acedata.cloud/assets/examples/nanobanana/e44bfceb-1458-4b4b-9d10-21024678f1a3-5ccb6e83b402.png"
  ]
}

Videobearbeitung / Referenzvideo (Video eingeben, Video generieren)

Es wird unterstützt, direkt „ein Video einzugeben und ein neues Video zu generieren“: Übergeben Sie in video_urls einen Referenzvideo-Link (maximal 1) und stellen Sie gleichzeitig in image_urls mindestens ein Referenzbild bereit (zwingende Anforderung der vorgelagerten Schnittstelle). Beschreiben Sie dann mit prompt den gewünschten Bearbeitungseffekt (Stil ändern, Szene wechseln, Elemente hinzufügen oder entfernen usw.). Nachfolgend finden Sie ein vollständiges reales Beispiel — ein sonniges Strandvideo wird in eine verschneite Winterszene geändert, während die Anordnung von Strand, Palmen und Booten beibehalten wird. Die Videobearbeitung dauert länger (in diesem Beispiel etwa 6,5 Minuten), daher wird sie mit async: true asynchron übermittelt:

{
  "prompt": "Turn this sunny tropical beach into a snowy winter scene with heavy falling snow and overcast sky; keep the same beach, palm trees and boat layout.",
  "model": "omni-flash",
  "aspect_ratio": "9:16",
  "resolution": "720p",
  "image_urls": [
    "https://cdn.acedata.cloud/99289603bd.png"
  ],
  "video_urls": [
    "https://cdn.acedata.cloud/assets/examples/seedance/dd3dc063-3383-4f29-bedc-e771a096758c-044e05281a2a.mp4"
  ],
  "async": true
}

Nach der Übermittlung gibt die API sofort die task_id zurück:

{
  "task_id": "cd68b4ee-de70-4c94-ac69-997a3fed0284"
}

Verwenden Sie anschließend diese task_id als id, um die Gemini Tasks API abzufragen. Nach Abschluss der Aufgabe können Sie das neu generierte Video abrufen (dies ist das tatsächliche Rückgabeergebnis dieses Beispiels):

{
  "success": true,
  "task_id": "cd68b4ee-de70-4c94-ac69-997a3fed0284",
  "trace_id": "5b22104b-5a6d-4a4f-8063-69acae1dc1c6",
  "data": [
    {
      "id": "e125d316-3d26-4c65-9413-55baf6be46b8",
      "video_url": "https://cdn.acedata.cloud/assets/examples/sora/cd68b4ee-de70-4c94-ac69-997a3fed0284-c5603ef983da.mp4",
      "state": "succeeded",
      "aspect_ratio": "9:16",
      "prompt": "Turn this sunny tropical beach into a snowy winter scene with heavy falling snow and overcast sky; keep the same beach, palm trees and boat layout."
    }
  ],
  "started_at": 1784084482.914,
  "finished_at": 1784084877.09,
  "elapsed": 394.176,
  "cost": {
    "amount": 1.932,
    "currency": "credit",
    "list_amount": 2.1
  }
}

Für ein Ergebnis mit höherer Auflösung können Sie resolution auf 1080p setzen (die übrigen Parameter bleiben unverändert).

Hinweis: Die Eingabe-/Ausgabe-Medienlinks im Beispiel sind allesamt echte Generierungsergebnisse. Die von der Plattform generierten Video- und Bildlinks haben eine Aufbewahrungsfrist und werden nach Ablauf ungültig. Laden Sie sie nach Erhalt der Ergebnisse bitte zeitnah herunter und speichern Sie sie in Ihrem eigenen Speicher.

Achtung: Es ist höchstens 1 Referenzvideo erlaubt; außerdem muss beim Bereitstellen von video_urls mindestens ein image_urls-Bild bereitgestellt werden, andernfalls wird der folgende Parameterfehler zurückgegeben:

{
  "success": false,
  "error": {
    "code": "bad_request",
    "message": "image_urls (at least one reference image) is required when video_urls is provided."
  }
}

Asynchroner Callback

Die Videogenerierung benötigt eine gewisse Verarbeitungszeit. Wenn Sie nicht auf eine lange Verbindung warten möchten, können Sie callback_url übergeben. In diesem Fall gibt die API sofort die task_id zurück und sendet nach Abschluss der Aufgabe das Endergebnis per POST an diese Adresse:

{
  "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden",
  "model": "omni-flash",
  "aspect_ratio": "16:9",
  "callback_url": "https://your-domain.com/callback/gemini"
}

Das sofort zurückgegebene Ergebnis lautet wie folgt:

{
  "task_id": "04a043bd-6b23-4b4e-945c-ce48158c3eee"
}

Aufgabenergebnis abfragen

Wenn ein asynchroner Callback verwendet wurde oder Sie den Aufgabenstatus aktiv abfragen möchten, können Sie über die Gemini Tasks API (POST https://api.acedata.cloud/gemini/tasks) anhand der task_id den neuesten Status und das Ergebnis der Aufgabe abfragen. Übergeben Sie im Request-Body die beim Erstellen des Videos zurückgegebene task_id als id:

{
  "id": "04a043bd-6b23-4b4e-945c-ce48158c3eee"
}

Das nach Abschluss der Aufgabe zurückgegebene Ergebnis sieht ähnlich wie folgt aus. Die Struktur von response.data entspricht derjenigen bei der synchronen Generierung (während der Generierung ist state pending und video_url null):

{
  "id": "04a043bd-6b23-4b4e-945c-ce48158c3eee",
  "type": "videos",
  "request": {
    "model": "omni-flash",
    "prompt": "A time-lapse of clouds over snow mountains at sunrise",
    "aspect_ratio": "16:9",
    "async": true
  },
  "response": {
    "success": true,
    "task_id": "04a043bd-6b23-4b4e-945c-ce48158c3eee",
    "data": [
      {
        "id": "486ebd5a-6a4b-406c-84ae-33835de4fe19",
        "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
        "state": "succeeded",
        "aspect_ratio": "16:9",
        "prompt": "A time-lapse of clouds over snow mountains at sunrise"
      }
    ],
    "elapsed": 96.716,
    "cost": {
      "amount": 1.932,
      "currency": "credit",
      "list_amount": 2.1
    }
  }
}

Fehlerbehandlung

Wenn bei einer Anfrage ein Problem auftritt, gibt die API den entsprechenden Fehlercode und eine Beschreibung zurück. Häufige Fälle sind:

400: Die Anfrageparameter sind fehlerhaft, zum Beispiel fehlt prompt oder der Wert von aspect_ratio ist ungültig.
401: Authentifizierung fehlgeschlagen, das Token ist ungültig oder stimmt nicht mit der API überein.
403: Unzureichendes Guthaben oder der Prompt wurde aufgrund der Inhaltsprüfung abgelehnt.
500: Interner Serverfehler oder die Upstream-Generierung ist fehlgeschlagen.

Erste Schritte

KI Chat

KI Bild

KI Video

KI Audio

Web & Daten

CAPTCHA

Identität

Coding

Weitere Anleitungen

Anleitung zur Integration der Gemini Videos Generation API

Antragsprozess

Grundlegende Verwendung

Bild-zu-Video

Videobearbeitung / Referenzvideo (Video eingeben, Video generieren)

Asynchroner Callback

Aufgabenergebnis abfragen

Fehlerbehandlung

​Antragsprozess

​Grundlegende Verwendung

​Bild-zu-Video

​Videobearbeitung / Referenzvideo (Video eingeben, Video generieren)

​Asynchroner Callback

​Aufgabenergebnis abfragen

​Fehlerbehandlung

Antragsprozess

Grundlegende Verwendung

Bild-zu-Video

Videobearbeitung / Referenzvideo (Video eingeben, Video generieren)

Asynchroner Callback

Aufgabenergebnis abfragen

Fehlerbehandlung