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

# Wan3.0 Videogenerierung

>  - All-in-one-Referenzvideomodell Alibaba Cloud Wanxiang 3.0 (einheitlicher Einstieg)
- Text-to-Video / erstes Einzelbild / erstes+letztes Einzelbild / multimodale Referenz / Datei- oder Link-Referenz
- Auflösung 480P / 720P / 1080P, Dauer 2–30 Sekunden
- Unterstützt Bilder, Video, Audio, Dokumente und öffentliche Webseiten als Referenzen 

```bash cURL theme={null}
curl --request POST \
  --url https://gccai.heqingsong.uk/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "wan3.0-video",
    "prompt": "A kitten runs across a moonlit rooftop, neon lights of the city flicker in the distance, cinematic quality, smooth camera move.",
    "resolution": "720P",
    "size": "16:9",
    "duration": 5
  }'
```

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

url = "https://gccai.heqingsong.uk/v1/videos/generations"

payload = {
    "model": "wan3.0-video",
    "prompt": "A kitten runs across a moonlit rooftop, neon lights of the city flicker in the distance, cinematic quality, smooth camera move.",
    "resolution": "720P",
    "size": "16:9",
    "duration": 5,
}

headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json",
}

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

print(response.json())
```

```javascript JavaScript theme={null}
const url = "https://gccai.heqingsong.uk/v1/videos/generations";

const payload = {
  model: "wan3.0-video",
  prompt: "A kitten runs across a moonlit rooftop, neon lights of the city flicker in the distance, cinematic quality, smooth camera move.",
  resolution: "720P",
  size: "16:9",
  duration: 5,
};

const headers = {
  Authorization: "Bearer <token>",
  "Content-Type": "application/json",
};

fetch(url, {
  method: "POST",
  headers: headers,
  body: JSON.stringify(payload),
})
  .then((response) => response.json())
  .then((data) => console.log(data))
  .catch((error) => console.error("Error:", error));
```

```go Go theme={null}
package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
)

func main() {
    url := "https://gccai.heqingsong.uk/v1/videos/generations"

    payload := map[string]interface{}{
        "model":      "wan3.0-video",
        "prompt":     "A kitten runs across a moonlit rooftop",
        "resolution": "720P",
        "size":       "16:9",
        "duration":   5,
    }

    jsonData, _ := json.Marshal(payload)
    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
    req.Header.Set("Authorization", "Bearer <token>")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := ioutil.ReadAll(resp.Body)
    fmt.Println(string(body))
}
```

```json 200 theme={null}
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01J9HA7JPQ9A0Z6JZ3V8M9W6PZ"
    }
  ]
}
```

```json 400 theme={null}
{
  "error": {
    "code": 400,
    "message": "Ungültige Anfrageparameter",
    "type": "invalid_request_error"
  }
}
```

```json 401 theme={null}
{
  "error": {
    "code": 401,
    "message": "Authentifizierung fehlgeschlagen, bitte API-Schlüssel prüfen",
    "type": "authentication_error"
  }
}
```

```json 402 theme={null}
{
  "error": {
    "code": 402,
    "message": "Unzureichendes Kontoguthaben, bitte aufladen und erneut versuchen",
    "type": "payment_required"
  }
}
```

```json 429 theme={null}
{
  "error": {
    "code": 429,
    "message": "Zu viele Anfragen, bitte später erneut versuchen",
    "type": "rate_limit_error"
  }
}
```

## Autorisierung

**Authorization** `string` *required*

Alle Endpunkte erfordern eine Bearer-Token-Authentifizierung

API-Key über die [Seite zur API-Key-Verwaltung](https://gccai.heqingsong.uk/keys) abrufen:

```
Authorization: Bearer YOUR_API_KEY
```

## Generierungsmodi

Modellname ist **`wan3.0-video`** oder **`wan3.0-video-prime`** (gleiche Parameter). Der Modus ergibt sich aus den Anfragefeldern:

| Modus | Typische Eingaben |
| - | - |
| Text-to-Video | nur `prompt` |
| Erstes-Einzelbild-Video | ein Eintrag in `image_urls` (Frame-Familie) |
| Erstes + letztes Einzelbild | zwei Einträge in `image_urls` oder `image_with_roles` mit `first_frame` / `last_frame` |
| Referenzvideo | Referenzbilder / Videos / Audio; Prompt kann Labels im Stil „图1 / 视频1 / 音频1“ nutzen |
| Datei- / Seitenreferenz | `file_url` oder `link_url` (`prompt` optional) |

## Anfrageparameter

### Grundlagen

**model** `string` *required*

Name des Videogenerierungsmodells. Zulässige Werte:

* `wan3.0-video`
* `wan3.0-video-prime`

Beide Modelle verwenden exakt dieselben Anfrageparameter.

**nsfw\_check** `boolean` (default: false)

Legt fest, ob der Inhalt vor dem Absenden des Videoauftrags moderiert wird.

* `true`: Prompts und Eingabebilder mit `omni-moderation-latest` prüfen
* `false` oder nicht angegeben: keine Moderationsanfrage und damit keine zusätzlichen Moderationskosten oder Verzögerung (Standard)

**prompt** `string`

Textbeschreibung. **Erforderlich, sofern** keine Medienfelder angegeben sind (mindestens Prompt oder Medien).

* Max. **20.000** Zeichen; Überschuss wird ohne Fehler automatisch abgeschnitten
* Im Referenzmodus mit „图N / 视频N / 音频N“ auf Assets verweisen; Indizes folgen der Reihenfolge **innerhalb jedes Medientyps**

**resolution** `string` (default: 1080P)

Ausgabeauflösung (Groß-/Kleinschreibung egal)

* `480P`
* `720P`
* `1080P` (**Standard**, höchster Preis)

> [!WARNING]
>
> Ohne `resolution` wird mit **1080P** abgerechnet. Bei Kostenbewusstsein explizit `480P` oder `720P` übergeben.

**size** `string` (default: adaptive)

Seitenverhältnis. `aspect_ratio` wird ebenfalls akzeptiert.

* `adaptive` (Standard)
* `16:9` / `4:3` / `1:1` / `3:4` / `9:16`

**duration** `integer` (default: 5)

Dauer in Sekunden:

* `2`–`30`: feste Ausgabelänge (Standard `5`)
* `-1`: Dauer **bestimmt das Modell**

> [!NOTE]
>
> Bei Referenzvideo-Eingabe: Gesamtdauer der Eingabevideos + Ausgabe ≤ 30 Sekunden. Bei `duration: -1` muss die vom Modell gewählte Länge dieses Limit ebenfalls einhalten.

**audio** `boolean` (default: true)

Ob die Ausgabe eine Audiospur enthält. Standard `true`. **Preis ist mit und ohne Audio gleich.**

**seed** `integer`

Zufalls-Seed im Bereich `[0, 2147483647]`

**watermark** `boolean` (default: false)

Ob ein Wasserzeichen hinzugefügt wird. Standard `false`

**generation\_type** `string`

Wie bloße `image_urls` klassifiziert werden:

* `frame` — Familie erstes/letztes Einzelbild
* `reference` — Referenzfamilie

Ohne Angabe automatische Klassifikation (siehe gegenseitige Ausschlussregeln).

### Medieneingaben

**image\_urls** `string[]`

Array von Bild-URLs. Rollenzuweisung folgt den gegenseitigen Ausschlussregeln.

Nur öffentliche URLs.

**image\_with\_roles** `object[]`

Bilder mit expliziten Rollen. Jedes Element:

* `url`: Bildadresse
* `role`: `first_frame` / `last_frame` / `reference_image` (übliche Aliase akzeptiert)

**video\_urls** `string[]`

Referenzvideos, bis zu **5** Clips; je 1–15 s, **gesamt ≤ 15 s**

**audio\_urls** `string[]`

Referenzaudio, bis zu **5** Clips; je 1–15 s, **gesamt ≤ 15 s**

**audio\_url** `string`

Einzelnes Referenzaudio (Einzelwertform von `audio_urls`)

**file\_url** `string`

URL des Referenzdokuments, höchstens **1**. **Nicht zusammen mit `link_url`.**

Formate u. a. docx / doc / xlsx / xls / pptx / ppt / pdf / txt / key / pages / numbers / md, ≤100 MB, ≤50 Seiten.

**link\_url** `string`

Öffentliche Webseiten-URL, höchstens **1**. Nur Seiten ohne Login. **Nicht zusammen mit `file_url`.**

## Gegenseitiger Ausschluss von Medienfamilien

Medien gehören zu einer von zwei Familien und **dürfen nicht gemischt werden** (Validierung vor Submit → 400, kein Task, keine Abrechnung):

| Familie | Mitglieder | Bedeutung |
| - | - | - |
| **Frame-Familie** | `first_frame`, `last_frame` | Strenges erstes / letztes Einzelbild des Videos |
| **Referenzfamilie** | `reference_image`, `reference_video`, `reference_audio`, `file`, `link` | Modell interpretiert Inhalte frei |

### Zuordnung bloßer `image_urls`

1. Wenn `generation_type` gesetzt → diesen verwenden (`frame` / `reference`)
2. Sonst, wenn die Anfrage bereits Eingaben der Referenzfamilie hat (`video_urls` / `audio_urls` / `audio_url` / `file_url` / `link_url`) → als `reference_image` behandeln
3. Sonst → Frame-Familie: erstes Element `first_frame`, zweites `last_frame` (wie bei `wan2.7`)

Für explizite Steuerung `image_with_roles` verwenden.

### Medienlimits und Formate

| Typ | Limits |
| - | - |
| Erstes / letztes Einzelbild | je ≤ 1 |
| Referenzbilder | ≤ 10 |
| Referenzvideo | ≤ 5 Clips, je 1–15 s, gesamt ≤15 s; mp4/mov; Kante 240–4096 px, Seitenverhältnis ≤8:1, ≤100 MB |
| Referenzaudio | ≤ 5 Clips, je 1–15 s, gesamt ≤15 s; wav/mp3; ≤15 MB |
| Bilder | JPEG/JPG/PNG (kein Alpha) / BMP / WEBP; Kante 240–8000 px, Seitenverhältnis ≤8:1, ≤20 MB |
| Dokumente | ≤100 MB, ≤50 Seiten |
| Webseiten | Öffentliche, login-freie URLs |

## Anfragebeispiele

### Text-to-Video

```json theme={null}
{
  "model": "wan3.0-video",
  "prompt": "A kitten runs across a moonlit rooftop, neon lights of the city flicker in the distance, cinematic quality, smooth camera move.",
  "resolution": "720P",
  "size": "16:9",
  "duration": 5
}
```

### Erstes-Einzelbild-Video

```json theme={null}
{
  "model": "wan3.0-video",
  "prompt": "The person in the frame starts freestyle rapping, camera slowly pushes in",
  "image_urls": ["https://example.com/first.png"],
  "resolution": "720P",
  "duration": 5
}
```

### Erstes + letztes Einzelbild

```json theme={null}
{
  "model": "wan3.0-video",
  "prompt": "Smile gradually becomes laughter, background light shifts from cool to warm",
  "image_urls": [
    "https://example.com/first.png",
    "https://example.com/last.jpg"
  ],
  "duration": 5
}
```

Oder mit `image_with_roles`:

```json theme={null}
{
  "model": "wan3.0-video",
  "prompt": "Smile gradually becomes laughter",
  "image_with_roles": [
    {"url": "https://example.com/first.png", "role": "first_frame"},
    {"url": "https://example.com/last.jpg", "role": "last_frame"}
  ],
  "duration": 5
}
```

### Multimodale Referenz

```json theme={null}
{
  "model": "wan3.0-video",
  "prompt": "视频1抱着图1，在图3的椅子上弹奏一支舒缓的乡村民谣，并说道：\"今天的阳光真好。\"",
  "generation_type": "reference",
  "image_urls": [
    "https://example.com/object1.jpg",
    "https://example.com/object2.png",
    "https://example.com/chair.png"
  ],
  "video_urls": ["https://example.com/role.mp4"],
  "resolution": "480P",
  "duration": 5
}
```

> Bei vorhandenen `video_urls` werden bloße `image_urls` automatisch als Referenzbilder klassifiziert; `generation_type: "reference"` macht die Absicht klarer.

### Datei-Referenzvideo

`prompt` kann weggelassen werden; die Generierung wird vom Dokumentinhalt gesteuert:

```json theme={null}
{
  "model": "wan3.0-video",
  "file_url": "https://example.com/glass.pptx",
  "resolution": "480P",
  "duration": 10
}
```

### Webseiten-Referenzvideo

```json theme={null}
{
  "model": "wan3.0-video",
  "prompt": "Turn this article into a short educational video",
  "link_url": "https://example.com/article/123",
  "duration": 15
}
```

## Abrechnung

**Pro Sekunde × Auflösung** (an offizielle Listenpreise angelehnt). Audio an/aus ändert den Preis nicht:

| Auflösung | Einzelpreis | 5 s | 30 s |
| - | - | - | - |
| 480P | **¥0.30** / s | ¥1.50 | ¥9.00 |
| 720P | **¥0.60** / s | ¥3.00 | ¥18.00 |
| 1080P | **¥1.20** / s | ¥6.00 | ¥36.00 |

* Standard ist **1080P** (teuerste Stufe); bei Kostenbewusstsein `480P` / `720P` übergeben
* Abrechnungssekunden: bei `2`–`30` die angeforderte `duration`; bei `-1` die **tatsächlichen** Ausgabesekunden
* `audio: true/false` beeinflusst den Preis **nicht**

## Limits und Hinweise

| Punkt | Hinweise |
| - | - |
| Dauer | Ganzzahl `2`–`30` oder `-1` (Modell bestimmt die Dauer) |
| Mit Videoeingabe | Gesamtdauer Eingabevideo + Ausgabedauer ≤ 30 s |
| Latenz | Typisch 1–5 Minuten; länger bei langen Clips |
| Ergebnis-URL | Nach Erfolg auf die Plattform-CDN gespiegelt für langfristigen Zugriff |
| Prompt | ≤20.000 Zeichen; Überschuss wird abgeschnitten |

## Häufige Fehler

Alle sind **synchrone 400** (kein Task, keine Abrechnung):

| Fall | Vorgehen |
| - | - |
| Mischen von Frame- und Referenzfamilie | Eine Familie über `generation_type` wählen oder Rollen mit `image_with_roles` setzen |
| Sowohl `file_url` als auch `link_url` | Eines wählen |
| Ungültiges `duration` | Nur `2`–`30` oder `-1` |
| Nicht unterstützte Auflösung (z. B. 4K) | Nur `480P` / `720P` / `1080P` |
| Mehr als 10 Referenzbilder | Auf ≤10 reduzieren |
| Leerer `prompt` und leere Medien | Mindestens eines angeben |

## Response

**code** `integer`

Statuscode; 200 bei Erfolg

**data** `array`

Antwortdaten-Array

**Array-Elemente**

**status** `string`

Task-Status; bei Erstellung `submitted`

**task\_id** `string`

Task-ID fürs Polling

> [!NOTE]
>
> **Ergebnisse abfragen**
>
> Die Videogenerierung ist asynchron. [Task-Status abrufen](https://gccai.heqingsong.uk/de/api-reference/tasks/status.md) oder `GET /v1/videos/generations/{task_id}` pollen.
>
> Empfohlenes Intervall 5–10 Sekunden; Generierung dauert typisch 1–5 Minuten. Bei Erfolg URLs in `result.videos` verwenden.


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