> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Anleitung zur Integration der Gemini Videos Generation API

> Gemini AI API guide - Ace Data Cloud

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](https://platform.acedata.cloud/console/applications) Ihren API-Token ab und bewahren Sie ihn als Reserve auf.

![](https://cdn.acedata.cloud/dvc3cg.jpg)

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](https://platform.acedata.cloud/console/coin) ein allgemeines Guthaben aufgeladen werden.

> 📘 Vollständige Dokumentation: [Gemini Videos Generation API →](https://platform.acedata.cloud/documents/gemini-videos)

## 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:

```json theme={null}
{
  "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:

```shell theme={null}
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:

```python theme={null}
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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "task_id": "cd68b4ee-de70-4c94-ac69-997a3fed0284"
}
```

Verwenden Sie anschließend diese `task_id` als `id`, um die [Gemini Tasks API](https://platform.acedata.cloud/documents/gemini-tasks) abzufragen. Nach Abschluss der Aufgabe können Sie das neu generierte Video abrufen (dies ist das tatsächliche Rückgabeergebnis dieses Beispiels):

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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](https://platform.acedata.cloud/documents/gemini-tasks) (`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`:

```json theme={null}
{
  "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`):

```json theme={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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.