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

# Vidu Q4 Preview Pembuatan Video

> Buat video dari satu frame awal atau hingga 15 gambar dan 3 klip audio referensi. 3–16 detik, hingga 4K, dengan audio secara default.

> [!NOTE]
>
> Model ini mendukung gambar-ke-video dan referensi-ke-video, tetapi tidak mendukung teks tanpa gambar atau pasangan frame awal/akhir. Setelah pengiriman, ambil ID tugas dari `data[0].task_id` dan gunakan [Kueri Tugas](https://gccai.heqingsong.uk/id/api-reference/tasks/status.md) untuk melihat status dan hasil.

## Mode pembuatan

`viduq4-preview` memilih mode secara otomatis berdasarkan gambar, peran, dan audio referensi. Tidak perlu parameter mode tambahan.

| Input | Mode |
| - | - |
| Hanya `first_frame_image` atau satu gambar dengan `role: "first_frame"` | Gambar-ke-video |
| Satu gambar tanpa peran dan tanpa audio referensi | Gambar-ke-video |
| Ada peran `reference_image` atau `reference`, tanpa frame awal eksplisit | Referensi-ke-video |
| Total 2–15 gambar, tanpa frame awal eksplisit | Referensi-ke-video |
| Audio referensi dan 1–15 gambar, tanpa frame awal eksplisit | Referensi-ke-video |

* **Gambar-ke-video**: tepat satu frame awal; prompt opsional; audio referensi tidak diterima.
* **Referensi-ke-video**: 1–15 gambar, hingga 3 klip audio referensi, dan **prompt wajib**. Jika hanya satu gambar tanpa audio referensi, tetapkan `role: "reference_image"` secara eksplisit; jika tidak, mode gambar-ke-video digunakan.
* Frame awal eksplisit (`first_frame_image` atau `role: "first_frame"`) tidak boleh digabung dengan gambar lain, peran gambar referensi, atau audio referensi. Jika digabung, HTTP 400 dikembalikan.

```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": "viduq4-preview",
    "prompt": "Seorang gadis menoleh sambil tersenyum, rambut panjangnya tertiup angin dan kamera perlahan mendekat",
    "image_urls": ["https://example.com/first-frame.png"],
    "duration": 5,
    "resolution": "1080p"
  }'
```

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

response = requests.post(
    "https://gccai.heqingsong.uk/v1/videos/generations",
    headers={"Authorization": "Bearer <token>"},
    json={
        "model": "viduq4-preview",
        "prompt": "Seorang gadis menoleh sambil tersenyum, rambut panjangnya tertiup angin dan kamera perlahan mendekat",
        "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://gccai.heqingsong.uk/v1/videos/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "viduq4-preview",
    prompt: "Seorang gadis menoleh sambil tersenyum, rambut panjangnya tertiup angin dan kamera perlahan mendekat",
    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());
```

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

## Header permintaan

**Authorization** `string` *required*

Autentikasi Bearer dengan format `Bearer <token>`; `<token>` adalah GccAi API Key Anda.

## Parameter permintaan

**model** `string` *required*

Harus persis `viduq4-preview` dalam huruf kecil.

**prompt** `string`

Prompt pembuatan video, maksimal 20.000 karakter.

* Gambar-ke-video: opsional. Jika dihilangkan, model membuat konten berdasarkan frame awal.
* Referensi-ke-video: wajib. Jika tidak ada, mengembalikan HTTP 400.

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

Array gambar. Mendukung URL gambar publik atau Data URL Base64 seperti `data:image/png;base64,...`.

* Gambar-ke-video: hanya satu gambar sebagai frame awal.
* Referensi-ke-video: total 1–15 gambar bersama `image_with_roles`.

Dapat digabung dengan `image_with_roles`; jumlahnya dijumlahkan. Jangan gabungkan dengan `first_frame_image` atau peran `first_frame` eksplisit. Untuk satu gambar tanpa peran, keberadaan audio referensi juga menentukan mode.

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

Array gambar dengan peran. Satu elemen untuk gambar-ke-video; total 1–15 gambar bersama `image_urls` untuk referensi-ke-video.

**Tampilkan kolom gambar**

**url** `string` *required*

URL gambar publik atau Data URL Base64.

**role** `string`

Peran gambar, tidak peka huruf besar/kecil:

* `first_frame`: frame awal untuk gambar-ke-video.
* `reference_image`: gambar referensi untuk referensi-ke-video; `reference` juga diterima.
* Dihilangkan atau kosong: tanpa audio referensi, jumlah total menentukan mode: satu gambar untuk gambar-ke-video, dua atau lebih untuk referensi-ke-video. Dengan audio referensi, mode referensi-ke-video digunakan.

Nilai lain seperti `last_frame` mengembalikan HTTP 400 secara sinkron.

Dapat digabung dengan `image_urls` untuk memasok referensi, tetapi peran frame awal tidak boleh dicampur dengan materi referensi.

**first\_frame\_image** `string`

Khusus gambar-ke-video. Berikan URL publik atau Data URL Base64 untuk frame awal.

Saat memakai kolom ini, jangan berikan gambar lain atau audio referensi. Untuk referensi-ke-video, gunakan `image_urls` atau `image_with_roles`.

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

Array URL audio referensi, khusus referensi-ke-video. Maksimal 3 klip jika digabung dengan `audio_url`.

Wajib MP3, tiap klip 3–12 detik dan maksimal 50MB. Audio referensi tetap memerlukan minimal satu gambar dan `prompt`.

Format atau durasi audio yang tidak sesuai menyebabkan tugas gagal saat eksekusi dengan pengembalian dana penuh, bukan HTTP 400 sinkron saat pengiriman.

**audio\_url** `string`

URL satu audio referensi. Persyaratan sama dengan `audio_urls`; maksimal 3 klip dari kedua kolom.

**aspect\_ratio** `string` (default: 16:9)

Khusus referensi-ke-video. Mendukung `1:1`, `9:16`, `16:9`, `3:4`, dan `4:3`. Default: `16:9`.

Pada gambar-ke-video, frame awal menentukan rasio aspek dan parameter ini diabaikan.

**size** `string`

Alias kompatibilitas untuk `aspect_ratio` dengan nilai yang sama. Sebaiknya gunakan hanya salah satu kolom. Tidak berpengaruh pada gambar-ke-video.

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

Durasi video dalam detik. Mendukung 3–16 detik, bukan 1–2 detik.

**resolution** `string` (default: 720p)

Resolusi: `540p`, `720p`, `1080p`, `2K`, atau `4K`, tidak peka huruf besar/kecil.

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

Apakah video menyertakan dialog dan efek suara.

* `true`: video dengan audio (default).
* `false`: video tanpa suara.

Harga video dengan atau tanpa suara sama.

**seed** `integer`

Seed acak. Hilangkan atau kirim `0` untuk nilai acak.

## Persyaratan materi

* Gambar-ke-video: wajib tepat satu gambar frame awal; audio referensi tidak diterima.
* Referensi-ke-video: wajib 1–15 gambar referensi; hingga 3 klip audio referensi opsional.
* Mendukung PNG, JPEG, JPG, WEBP, maksimal 50MB per gambar.
* Jika memakai Base64, seluruh body permintaan harus kurang dari 20MB. URL publik disarankan.
* URL gambar harus dapat diakses publik. Ganti URL contoh dengan alamat gambar yang benar-benar dapat diakses.

> [!WARNING]
>
> Kedua mode memerlukan gambar dan tidak mendukung `last_frame_image`. Kesalahan seperti mencampur frame awal dengan referensi atau melampaui jumlah gambar/audio mengembalikan HTTP 400 saat pengiriman, tanpa membuat tugas atau mengenakan biaya. Format atau durasi audio referensi yang salah menyebabkan kegagalan saat eksekusi dan pengembalian dana.

## Contoh permintaan

### Hanya frame awal, tanpa prompt

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

Secara default menghasilkan video 5 detik, 720p, dengan audio.

### Frame awal dengan peran eksplisit dan output 4K

```json theme={null}
{
  "model": "viduq4-preview",
  "prompt": "Kamera perlahan mendekat sementara orang tersebut tersenyum alami",
  "image_with_roles": [
    {
      "url": "https://example.com/first-frame.png",
      "role": "first_frame"
    }
  ],
  "duration": 8,
  "resolution": "4K",
  "audio": true
}
```

### Video tanpa suara menggunakan kolom frame awal

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

### Video dari beberapa gambar dan audio referensi

```json theme={null}
{
  "model": "viduq4-preview",
  "prompt": "Anak laki-laki pada gambar 1 berbicara kepada gadis pada gambar 2 menggunakan isi audio referensi, di kafe pada gambar 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"
}
```

### Referensi-ke-video dengan satu gambar

```json theme={null}
{
  "model": "viduq4-preview",
  "prompt": "Orang dalam gambar referensi masuk ke kafe dan melambaikan tangan kepada staf",
  "image_with_roles": [
    {
      "url": "https://example.com/person.png",
      "role": "reference_image"
    }
  ],
  "aspect_ratio": "9:16",
  "duration": 5,
  "resolution": "1080p"
}
```

Contoh ini tidak menyertakan audio referensi dan memilih referensi-ke-video secara eksplisit lewat peran `reference_image`. Ganti semua URL gambar dan audio dengan alamat materi yang dapat diakses.

## Respons pengiriman

**code** `integer`

Kode status respons; `200` berarti berhasil.

**data** `array`

Hasil pengiriman tugas.

**Tampilkan kolom tugas**

**status** `string`

`submitted` berarti pengiriman berhasil, bukan pembuatan video telah selesai.

**task\_id** `string`

ID tugas untuk memeriksa status dan hasil.

## Memeriksa hasil tugas

Lakukan polling setiap 5–10 detik dan berhenti pada `completed` atau `failed`. Gunakan endpoint kueri terpadu:

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

Contoh respons berhasil (URL video adalah placeholder):

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

| Status | Tindakan |
| - | - |
| `pending` | Dalam antrean; lanjutkan polling |
| `processing` | Sedang dibuat; lanjutkan polling |
| `completed` | Berhasil; baca tautan video dari array `data.result.videos[0].url` |
| `failed` | Gagal; baca penyebab dari `data.error.message` dan hentikan polling; dana dikembalikan penuh |

Tautan video berlaku 24 jam. Segera unduh dan simpan. Tentukan penyelesaian berdasarkan `status`, bukan angka kemajuan tetap.

## Penagihan

Biaya berdasarkan durasi dan resolusi: biaya = durasi (detik) × tarif per detik untuk resolusi tersebut.

Lihat [Harga Model](https://gccai.heqingsong.uk/pricing). Kedua mode berharga sama, dengan atau tanpa audio. Gambar dan audio referensi tidak dikenakan biaya tambahan. Tugas yang gagal otomatis mendapat pengembalian dana penuh.

## Kesalahan parameter umum

Kasus berikut mengembalikan HTTP 400 secara sinkron, tanpa membuat tugas atau mengenakan biaya:

| Masalah | Tindakan |
| - | - |
| Tidak ada gambar | Berikan satu frame awal untuk gambar-ke-video atau 1–15 gambar referensi untuk referensi-ke-video |
| Frame awal eksplisit dicampur dengan gambar lain, peran referensi, atau audio referensi | Sisakan satu frame awal untuk gambar-ke-video; hapus kolom atau peran frame awal eksplisit untuk referensi-ke-video |
| `role` tidak didukung, seperti `last_frame` | Gunakan `first_frame`, `reference_image`, `reference`, atau kosongkan |
| Lebih dari 15 gambar referensi | Batasi total `image_urls` dan `image_with_roles` hingga 15 |
| Lebih dari 3 klip audio referensi | Batasi total `audio_urls` dan `audio_url` hingga 3 |
| `prompt` tidak ada pada referensi-ke-video | Tambahkan prompt hingga 20.000 karakter |
| Rasio aspek referensi tidak didukung, seperti `21:9` | Gunakan `1:1`, `9:16`, `16:9`, `3:4`, atau `4:3` |
| `last_frame_image` diberikan | Hapus kolom; pasangan frame awal/akhir tidak didukung |
| `duration` kurang dari 3 atau lebih dari 16 | Gunakan bilangan bulat 3–16 detik |
| Resolusi tidak didukung, seperti `480p` atau `8K` | Gunakan `540p`, `720p`, `1080p`, `2K`, atau `4K` |

## Model Vidu lainnya

Untuk teks-ke-video atau pasangan frame awal/akhir, gunakan [Vidu Q3 Pro / Turbo](https://gccai.heqingsong.uk/id/api-reference/videos/vidu-q3-pro/generation.md). Model ini sudah mendukung banyak gambar referensi; [Vidu Q3 Mix / Standard](https://gccai.heqingsong.uk/id/api-reference/videos/vidu-q3/generation.md) juga menyediakan referensi-ke-video. Untuk klip 1–2 detik, pilih `viduq3-pro`; model ini memerlukan minimal 3 detik.


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