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

# Vidu Q4 Preview Videogenerierung

> Videos aus einem Startbild oder bis zu 15 Referenzbildern und 3 Referenz-Audioclips. 3–16 Sekunden, bis zu 4K, standardmäßig mit Ton.

<Info>
  Unterstützt Bild-zu-Video und Referenz-zu-Video, aber weder reine Textgenerierung noch Start-/Endbildpaare. Nach dem Absenden die Task-ID aus `data[0].task_id` lesen und Status und Ergebnis über die [Task-Abfrage](/de/api-reference/tasks/status) abrufen.
</Info>

## Generierungsmodi

`viduq4-preview` wählt den Modus anhand der Bilder, Rollen und Referenzaudios automatisch. Ein zusätzlicher Modusparameter ist nicht nötig.

| Eingabe | Modus |
| - | - |
| Nur `first_frame_image` oder ein Bild mit `role: "first_frame"` | Bild-zu-Video |
| Ein Bild ohne Rolle und ohne Referenzaudio | Bild-zu-Video |
| Rolle `reference_image` oder `reference` vorhanden, kein explizites Startbild | Referenz-zu-Video |
| Insgesamt 2–15 Bilder ohne explizites Startbild | Referenz-zu-Video |
| Referenzaudio und 1–15 Bilder ohne explizites Startbild | Referenz-zu-Video |

* **Bild-zu-Video**: Genau ein Startbild, Prompt optional, kein Referenzaudio.
* **Referenz-zu-Video**: 1–15 Referenzbilder, bis zu 3 Referenz-Audioclips, **Prompt erforderlich**. Bei nur einem Bild ohne Referenzaudio explizit `role: "reference_image"` setzen; sonst wird Bild-zu-Video verwendet.
* Ein explizites Startbild (`first_frame_image` oder `role: "first_frame"`) darf nicht mit anderen Bildern, Referenzbildrollen oder Referenzaudio kombiniert werden. Andernfalls HTTP 400.

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.apimart.ai/v1/videos/generations \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "viduq4-preview",
      "prompt": "Ein Mädchen dreht sich lächelnd um, ihr langes Haar weht im Wind und die Kamera nähert sich langsam",
      "image_urls": ["https://example.com/first-frame.png"],
      "duration": 5,
      "resolution": "1080p"
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.apimart.ai/v1/videos/generations",
      headers={"Authorization": "Bearer <token>"},
      json={
          "model": "viduq4-preview",
          "prompt": "Ein Mädchen dreht sich lächelnd um, ihr langes Haar weht im Wind und die Kamera nähert sich langsam",
          "image_urls": ["https://example.com/first-frame.png"],
          "duration": 5,
          "resolution": "1080p"
      }
  )
  response.raise_for_status()
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.apimart.ai/v1/videos/generations", {
    method: "POST",
    headers: {
      Authorization: "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "viduq4-preview",
      prompt: "Ein Mädchen dreht sich lächelnd um, ihr langes Haar weht im Wind und die Kamera nähert sich langsam",
      image_urls: ["https://example.com/first-frame.png"],
      duration: 5,
      resolution: "1080p"
    })
  });
  if (!response.ok) throw new Error(await response.text());
  console.log(await response.json());
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "code": 200,
    "data": [
      {
        "status": "submitted",
        "task_id": "task_01K..."
      }
    ]
  }
  ```
</ResponseExample>

## Request-Header

<ParamField header="Authorization" type="string" required>
  Bearer-Authentifizierung im Format `Bearer <token>`. `<token>` ist Ihr APIMart API Key.
</ParamField>

## Request-Parameter

<ParamField body="model" type="string" required>
  Muss exakt `viduq4-preview` in Kleinbuchstaben sein.
</ParamField>

<ParamField body="prompt" type="string">
  Prompt zur Videogenerierung, maximal 20.000 Zeichen.

  * Bild-zu-Video: Optional. Ohne Prompt erzeugt das Modell den Inhalt anhand des Startbilds.
  * Referenz-zu-Video: Erforderlich. Fehlt der Prompt, wird HTTP 400 zurückgegeben.
</ParamField>

<ParamField body="image_urls" type="string[]">
  Bildarray. Unterstützt öffentlich zugängliche Bild-URLs oder Base64 Data URLs wie `data:image/png;base64,...`.

  * Bild-zu-Video: Genau ein Bild als Startbild.
  * Referenz-zu-Video: Zusammen mit `image_with_roles` insgesamt 1–15 Bilder.

  Mit `image_with_roles` kombinierbar; die Anzahl wird summiert. Nicht mit `first_frame_image` oder einer expliziten `first_frame`-Rolle kombinieren. Bei einem Bild ohne Rolle hängt der Modus auch davon ab, ob Referenzaudio vorhanden ist.
</ParamField>

<ParamField body="image_with_roles" type="object[]">
  Array von Bildern mit Rollen. Ein Element für Bild-zu-Video; für Referenz-zu-Video insgesamt 1–15 Bilder zusammen mit `image_urls`.

  <Expandable title="Bildfelder anzeigen">
    <ParamField body="url" type="string" required>
      Öffentliche Bild-URL oder Base64 Data URL.
    </ParamField>

    <ParamField body="role" type="string">
      Bildrolle, unabhängig von Groß-/Kleinschreibung:

      * `first_frame`: Startbild für Bild-zu-Video.
      * `reference_image`: Referenzbild für Referenz-zu-Video; `reference` wird ebenfalls akzeptiert.
      * Nicht angegeben oder leer: Ohne Referenzaudio entscheidet die Gesamtzahl: ein Bild für Bild-zu-Video, mindestens zwei für Referenz-zu-Video. Mit Referenzaudio wird Referenz-zu-Video verwendet.

      Andere Werte wie `last_frame` geben synchron HTTP 400 zurück.
    </ParamField>
  </Expandable>

  Mit `image_urls` zur Angabe von Referenzbildern kombinierbar; Startbildrollen dürfen jedoch nicht mit Referenzmaterial gemischt werden.
</ParamField>

<ParamField body="first_frame_image" type="string">
  Nur für Bild-zu-Video. Öffentliche URL oder Base64 Data URL des Startbilds.

  Bei Verwendung dieses Feldes keine weiteren Bilder oder Referenzaudios angeben. Für Referenz-zu-Video `image_urls` oder `image_with_roles` verwenden.
</ParamField>

<ParamField body="audio_urls" type="string[]">
  Array von Referenzaudio-URLs, nur für Referenz-zu-Video. Zusammen mit `audio_url` maximal 3 Clips.

  MP3 erforderlich, je 3–12 Sekunden und maximal 50MB. Auch mit Referenzaudio sind mindestens ein Bild und ein `prompt` erforderlich.

  Ungültiges Audioformat oder ungültige Dauer führt während der Ausführung zum Fehlschlagen mit vollständiger Erstattung, nicht zu synchronem HTTP 400 beim Absenden.
</ParamField>

<ParamField body="audio_url" type="string">
  Einzelne Referenzaudio-URL. Gleiche Anforderungen wie `audio_urls`; beide Felder zusammen maximal 3 Clips.
</ParamField>

<ParamField body="aspect_ratio" type="string" default="16:9">
  Nur für Referenz-zu-Video. Unterstützt `1:1`, `9:16`, `16:9`, `3:4` und `4:3`; Standard: `16:9`.

  Bei Bild-zu-Video bestimmt das Startbild das Seitenverhältnis; dieser Parameter wird ignoriert.
</ParamField>

<ParamField body="size" type="string">
  Kompatibilitätsalias für `aspect_ratio` mit denselben Werten. Nur eines der beiden Felder verwenden. Bei Bild-zu-Video ohne Wirkung.
</ParamField>

<ParamField body="duration" type="integer" default="5">
  Videodauer in Sekunden. Unterstützt 3–16 Sekunden, nicht 1–2 Sekunden.
</ParamField>

<ParamField body="resolution" type="string" default="720p">
  Videoauflösung: `540p`, `720p`, `1080p`, `2K` oder `4K`, unabhängig von Groß-/Kleinschreibung.
</ParamField>

<ParamField body="audio" type="boolean" default="true">
  Ob das Video Dialoge und Soundeffekte enthalten soll.

  * `true`: Video mit Ton (Standard).
  * `false`: Stummes Video.

  Videos mit und ohne Ton kosten gleich viel.
</ParamField>

<ParamField body="seed" type="integer">
  Zufalls-Seed. Nicht angeben oder `0` übergeben für einen zufälligen Wert.
</ParamField>

## Anforderungen an Eingabedateien

* Bild-zu-Video: Genau ein Startbild erforderlich; kein Referenzaudio.
* Referenz-zu-Video: 1–15 Referenzbilder erforderlich; optional bis zu 3 Referenz-Audioclips.
* PNG, JPEG, JPG und WEBP unterstützt; maximal 50MB pro Bild.
* Bei Base64 muss der gesamte Request-Body kleiner als 20MB sein. Öffentliche URLs werden empfohlen.
* Bild-URLs müssen öffentlich zugänglich sein. Beispiel-URLs durch tatsächlich erreichbare Bild-URLs ersetzen.

<Warning>
  Beide Modi benötigen Bilder und unterstützen `last_frame_image` nicht. Parameterfehler wie die Kombination von Startbild und Referenzmaterial oder eine zu hohe Bild-/Audioanzahl geben beim Absenden HTTP 400 zurück, ohne Task-Erstellung oder Kosten. Ungültiges Referenzaudioformat oder ungültige Dauer führt während der Ausführung zum Fehlschlagen mit Erstattung.
</Warning>

## Request-Beispiele

### Nur Startbild, ohne Prompt

```json theme={null}
{
  "model": "viduq4-preview",
  "image_urls": ["https://example.com/first-frame.png"]
}
```

Standardmäßig entsteht ein 5 Sekunden langes Video in 720p mit Ton.

### Startbild mit expliziter Rolle und 4K-Ausgabe

```json theme={null}
{
  "model": "viduq4-preview",
  "prompt": "Die Kamera nähert sich langsam, während die Person natürlich lächelt",
  "image_with_roles": [
    {
      "url": "https://example.com/first-frame.png",
      "role": "first_frame"
    }
  ],
  "duration": 8,
  "resolution": "4K",
  "audio": true
}
```

### Stummes Video über das Startbildfeld

```json theme={null}
{
  "model": "viduq4-preview",
  "first_frame_image": "https://example.com/first-frame.png",
  "duration": 5,
  "resolution": "1080p",
  "audio": false
}
```

### Video aus mehreren Bildern und Referenzaudio

```json theme={null}
{
  "model": "viduq4-preview",
  "prompt": "Der Junge aus Bild 1 spricht mit dem Mädchen aus Bild 2 mit dem Inhalt des Referenzaudios, im Café aus Bild 3",
  "image_urls": [
    "https://example.com/boy.png",
    "https://example.com/girl.png",
    "https://example.com/cafe.png"
  ],
  "audio_urls": ["https://example.com/line.mp3"],
  "aspect_ratio": "16:9",
  "duration": 8,
  "resolution": "720p"
}
```

### Referenz-zu-Video mit einem einzelnen Bild

```json theme={null}
{
  "model": "viduq4-preview",
  "prompt": "Die Person aus dem Referenzbild betritt ein Café und winkt dem Personal zu",
  "image_with_roles": [
    {
      "url": "https://example.com/person.png",
      "role": "reference_image"
    }
  ],
  "aspect_ratio": "9:16",
  "duration": 5,
  "resolution": "1080p"
}
```

Dieses Beispiel enthält kein Referenzaudio und wählt Referenz-zu-Video explizit über die Rolle `reference_image`. Alle Bild- und Audio-URLs durch tatsächlich erreichbare URLs ersetzen.

## Antwort auf die Übermittlung

<ResponseField name="code" type="integer">
  Antwortstatuscode; `200` bedeutet Erfolg.
</ResponseField>

<ResponseField name="data" type="array">
  Ergebnis der Task-Übermittlung.

  <Expandable title="Task-Felder anzeigen">
    <ResponseField name="status" type="string">
      `submitted` bedeutet erfolgreiche Übermittlung, nicht abgeschlossene Videogenerierung.
    </ResponseField>

    <ResponseField name="task_id" type="string">
      Task-ID zur Abfrage von Status und Ergebnis.
    </ResponseField>
  </Expandable>
</ResponseField>

## Task-Ergebnisse abfragen

Alle 5–10 Sekunden abfragen und bei `completed` oder `failed` stoppen. Den einheitlichen Abfrage-Endpunkt verwenden:

```bash theme={null}
curl --request GET \
  --url https://api.apimart.ai/v1/tasks/task_01K... \
  --header 'Authorization: Bearer <token>'
```

Beispiel einer erfolgreichen Antwort (Video-URL ist ein Platzhalter):

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01K...",
    "status": "completed",
    "progress": 100,
    "result": {
      "videos": [
        {
          "url": ["https://example.com/generated-video.mp4"]
        }
      ]
    }
  }
}
```

| Status | Vorgehen |
| - | - |
| `pending` | In Warteschlange; weiter abfragen |
| `processing` | Wird generiert; weiter abfragen |
| `completed` | Erfolgreich; Videolinks aus dem Array `data.result.videos[0].url` lesen |
| `failed` | Fehlgeschlagen; Ursache aus `data.error.message` lesen, Abfragen stoppen; vollständige Erstattung |

Videolinks sind 24 Stunden gültig. Zeitnah herunterladen und speichern. Den Abschluss anhand von `status` bestimmen, nicht anhand fester Fortschrittswerte.

## Abrechnung

Abrechnung nach Dauer und Auflösung: Kosten = Dauer (Sekunden) × Sekundenpreis der Auflösung.

Die aktuellen Preise stehen unter [Modellpreise](https://apimart.ai/pricing). Bild-zu-Video und Referenz-zu-Video kosten gleich viel, mit oder ohne Ton. Referenzbilder und -audios verursachen keine zusätzlichen Kosten. Fehlgeschlagene Tasks werden automatisch vollständig erstattet.

## Häufige Parameterfehler

Folgende Fälle geben synchron HTTP 400 zurück, ohne Task-Erstellung oder Kosten:

| Problem | Vorgehen |
| - | - |
| Keine Bilder | Ein Startbild für Bild-zu-Video oder 1–15 Referenzbilder für Referenz-zu-Video angeben |
| Explizites Startbild mit anderen Bildern, Referenzrollen oder Referenzaudio gemischt | Für Bild-zu-Video nur ein Startbild behalten; für Referenz-zu-Video explizite Startbildfelder oder -rollen entfernen |
| Nicht unterstützte `role` wie `last_frame` | `first_frame`, `reference_image`, `reference` verwenden oder leer lassen |
| Mehr als 15 Referenzbilder | `image_urls` und `image_with_roles` zusammen auf maximal 15 begrenzen |
| Mehr als 3 Referenz-Audioclips | `audio_urls` und `audio_url` zusammen auf maximal 3 begrenzen |
| Fehlender `prompt` bei Referenz-zu-Video | Prompt mit maximal 20.000 Zeichen ergänzen |
| Nicht unterstütztes Referenz-Seitenverhältnis, etwa `21:9` | `1:1`, `9:16`, `16:9`, `3:4` oder `4:3` verwenden |
| `last_frame_image` angegeben | Feld entfernen; Start-/Endbildpaare werden nicht unterstützt |
| `duration` kleiner als 3 oder größer als 16 | Ganzzahl von 3 bis 16 Sekunden verwenden |
| Nicht unterstützte Auflösung wie `480p` oder `8K` | `540p`, `720p`, `1080p`, `2K` oder `4K` verwenden |

## Weitere Vidu-Modelle

Für Text-zu-Video oder Start-/Endbildpaare [Vidu Q3 Pro / Turbo](/de/api-reference/videos/vidu-q3-pro/generation) verwenden. Dieses Modell unterstützt bereits mehrere Referenzbilder; auch [Vidu Q3 Mix / Standard](/de/api-reference/videos/vidu-q3/generation) bietet Referenz-zu-Video. Für Clips von 1–2 Sekunden `viduq3-pro` wählen; dieses Modell benötigt mindestens 3 Sekunden.


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