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

<Info>
  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](/id/api-reference/tasks/status) untuk melihat status dan hasil.
</Info>

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

<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": "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://api.apimart.ai/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://api.apimart.ai/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());
  ```
</RequestExample>

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

## Header permintaan

<ParamField header="Authorization" type="string" required>
  Autentikasi Bearer dengan format `Bearer <token>`; `<token>` adalah APIMart API Key Anda.
</ParamField>

## Parameter permintaan

<ParamField body="model" type="string" required>
  Harus persis `viduq4-preview` dalam huruf kecil.
</ParamField>

<ParamField body="prompt" type="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.
</ParamField>

<ParamField body="image_urls" type="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.
</ParamField>

<ParamField body="image_with_roles" type="object[]">
  Array gambar dengan peran. Satu elemen untuk gambar-ke-video; total 1–15 gambar bersama `image_urls` untuk referensi-ke-video.

  <Expandable title="Tampilkan kolom gambar">
    <ParamField body="url" type="string" required>
      URL gambar publik atau Data URL Base64.
    </ParamField>

    <ParamField body="role" type="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.
    </ParamField>
  </Expandable>

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

<ParamField body="first_frame_image" type="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`.
</ParamField>

<ParamField body="audio_urls" type="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.
</ParamField>

<ParamField body="audio_url" type="string">
  URL satu audio referensi. Persyaratan sama dengan `audio_urls`; maksimal 3 klip dari kedua kolom.
</ParamField>

<ParamField body="aspect_ratio" type="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.
</ParamField>

<ParamField body="size" type="string">
  Alias kompatibilitas untuk `aspect_ratio` dengan nilai yang sama. Sebaiknya gunakan hanya salah satu kolom. Tidak berpengaruh pada gambar-ke-video.
</ParamField>

<ParamField body="duration" type="integer" default="5">
  Durasi video dalam detik. Mendukung 3–16 detik, bukan 1–2 detik.
</ParamField>

<ParamField body="resolution" type="string" default="720p">
  Resolusi: `540p`, `720p`, `1080p`, `2K`, atau `4K`, tidak peka huruf besar/kecil.
</ParamField>

<ParamField body="audio" type="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.
</ParamField>

<ParamField body="seed" type="integer">
  Seed acak. Hilangkan atau kirim `0` untuk nilai acak.
</ParamField>

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

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

<ResponseField name="code" type="integer">
  Kode status respons; `200` berarti berhasil.
</ResponseField>

<ResponseField name="data" type="array">
  Hasil pengiriman tugas.

  <Expandable title="Tampilkan kolom tugas">
    <ResponseField name="status" type="string">
      `submitted` berarti pengiriman berhasil, bukan pembuatan video telah selesai.
    </ResponseField>

    <ResponseField name="task_id" type="string">
      ID tugas untuk memeriksa status dan hasil.
    </ResponseField>
  </Expandable>
</ResponseField>

## 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://api.apimart.ai/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://apimart.ai/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](/id/api-reference/videos/vidu-q3-pro/generation). Model ini sudah mendukung banyak gambar referensi; [Vidu Q3 Mix / Standard](/id/api-reference/videos/vidu-q3/generation) 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.