Referensi API HappyHorse image-to-video (frame pertama)

Catatan penggunaan

Model, URL endpoint, dan Kunci API harus berada di Wilayah yang sama. Panggilan lintas-Wilayah akan gagal.

Select a model: Periksa Wilayah tempat model tersebut berada.
Select a URL: Pilih URL endpoint untuk Wilayah yang sama.
Configure an API key: Dapatkan API key untuk Wilayah yang sama, lalu konfigurasikan Kunci API sebagai Variabel lingkungan.

Kode contoh dalam topik ini berlaku untuk Wilayah Singapore.

Alibaba Cloud Model Studio telah merilis domain khusus ruang kerja untuk Wilayah China (Beijing) dan Singapore. Domain khusus baru ini memberikan performa lebih unggul dan stabilitas lebih tinggi untuk permintaan Inferensi. Kami merekomendasikan migrasi ke domain baru:

China (Beijing): dari https://dashscope.aliyuncs.com ke https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
Singapore: dari https://dashscope-intl.aliyuncs.com ke https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

{WorkspaceId} adalah ID ruang kerja Anda, yang dapat ditemukan di halaman Workspace Details pada Konsol Alibaba Cloud Model Studio. Domain yang ada tetap berfungsi penuh.

Panggilan HTTP

Tugas image-to-video memerlukan waktu 1–5 menit. API menggunakan panggilan asinkron: "Buat tugas → polling hasil".

Langkah 1: Buat tugas

POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda.

Setelah tugas dibuat, gunakan task_id yang dikembalikan untuk mengkueri hasilnya. task_id berlaku selama 24 jam. Jangan membuat tugas duplikat. Sebagai gantinya, gunakan polling untuk mengambil hasilnya.
Untuk panduan pemula, lihat Panggil API dengan Postman atau cURL.

Parameter permintaan

Content-Type string (Wajib)Tipe konten permintaan. Harus berupa application/json.Authorization string (Wajib)Mengautentikasi permintaan dengan Kunci API Model Studio. Contoh: Bearer sk-xxxx.X-DashScope-Async string (Wajib)Mengaktifkan pemrosesan asinkron. Permintaan HTTP hanya mendukung panggilan asinkron. Harus diatur ke enable.

Jika header permintaan ini tidak disertakan, kesalahan "current user api does not support synchronous calls" akan dikembalikan.

Body permintaan

model string (wajib)Nama model. Untuk daftar model yang tersedia, lihat Konsol Model Studio.Contoh: happyhorse-1.1-i2v.input object (wajib)Input model, termasuk prompt teks.

Properti

prompt string (opsional)Menjelaskan konten video yang akan dihasilkan.Mendukung semua bahasa. Maksimum: 5.000 karakter non-Cina atau 2.500 karakter Cina. Input yang lebih panjang akan dipotong.media array (wajib)Array gambar input.

Properti elemen media[]

type string (wajib)Jenis media. Nilai yang diizinkan:

first_frame: Frame pertama.

Tepat satu gambar frame pertama wajib disediakan.url string (wajib)URL media.

Gambar input (type=first_frame)

URL atau data terenkripsi Base64 dari gambar frame pertama.Batasan gambar:

Format: JPEG, JPG, PNG, WEBP.
Resolusi: Lebar dan tinggi minimal 300 piksel.
Rasio aspek: Antara 1:2,5 hingga 2,5:1.
Ukuran file: Maksimal 20 MB.

Format input yang didukung:

URL publik:
- HTTP dan HTTPS didukung.
- Contoh: https://xxx/xxx.png.
String gambar terenkripsi Base64:
- Format: data:{MIME_type};base64,{base64_data}.
- Contoh: data:image/png;base64,GDU7MtCZzEbTbmRZ...... (disingkat untuk tampilan).
  Format encoding Base64
  Format: data:{MIME_type};base64,{base64_data} .
  - {base64_data}: String terenkripsi Base64 dari file gambar.
  - {MIME_type}: Jenis media gambar, yang harus sesuai dengan format file.
  Format gambar
  MIME Type
  JPEG
  image/jpeg
  JPG
  image/jpeg
  PNG
  image/png
  WEBP
  image/webp

parameters object (opsional)Pengaturan output video seperti resolusi dan durasi.

Properti

resolution string (opsional)Resolusi video yang dihasilkan.Jumlah piksel output mendekati tier yang dipilih sambil mempertahankan rasio aspek gambar input.Nilai yang diizinkan:

480P
720P
1080P (Default)

duration integer (opsional)Durasi video yang dihasilkan, dalam detik.Nilainya harus bilangan bulat dalam rentang [3, 15]. Default: 5.watermark boolean (opsional)Menambahkan watermark teks "Happy Horse" di pojok kanan bawah.

true (Default)
false

seed integer (Opsional)Seed bilangan acak harus berupa bilangan bulat dalam rentang [0, 2147483647].Jika tidak ditentukan, seed acak akan dihasilkan. Seed tetap meningkatkan kemampuan reproduksi.Karena pembuatan model bersifat probabilistik, seed yang sama tidak menjamin hasil identik.

Image-to-video

# URL berikut untuk Wilayah Singapore. Ganti {WorkspaceId} dengan ID ruang kerja Bailian Anda. URL bervariasi berdasarkan Wilayah.
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "happyhorse-1.1-i2v",
    "input": {
        "prompt": "A cat running on the grass",
        "media": [
            {
                "type": "first_frame",
                "url": "https://cdn.translate.alibaba.com/r/wanx-demo-1.png"
            }
        ]
    },
    "parameters": {
        "resolution": "720P",
        "duration": 5
    }
}'

Parameter tanggapan

output objectOutput tugas.

Properti

task_id stringID tugas. Berlaku untuk kueri selama 24 jam.task_status stringStatus tugas.

Nilai enumerasi

PENDING
RUNNING
SUCCEEDED
FAILED
CANCELED
UNKNOWN: Tugas tidak ada atau statusnya tidak diketahui.

request_id stringIdentifier permintaan unik untuk pelacakan dan troubleshooting.code stringKode kesalahan. Hanya dikembalikan untuk permintaan yang gagal. Lihat Kode kesalahan.message stringPesan kesalahan detail. Hanya dikembalikan untuk permintaan yang gagal. Lihat Kode kesalahan.

Tanggapan sukses
Tanggapan kesalahan

Simpan task_id untuk mengkueri status dan hasil tugas.

{
    "output": {
        "task_status": "PENDING",
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
    },
    "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}

Langkah 2: Lakukan polling untuk hasilnya

GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

Rekomendasi polling: Pembuatan video memerlukan beberapa menit. Gunakan mekanisme polling dengan interval yang masuk akal, misalnya 15 detik.
Transisi status tugas: PENDING → RUNNING → SUCCEEDED atau FAILED.
Tautan hasil: Setelah tugas berhasil, URL video yang berlaku selama 24 jam akan dikembalikan. Unduh dan simpan video ke penyimpanan permanen, seperti OSS.
task_idmasa berlaku: 24 jam. Setelah periode ini, kueri akan mengembalikan status tugas sebagai UNKNOWN.

Parameter permintaan

Header permintaan

Authorization string (Wajib)Mengautentikasi permintaan menggunakan Kunci API Model Studio. Contoh: Bearer sk-xxxx.

Parameter path

task_id string (Wajib)ID tugas.

Kueri hasil tugas

Ganti {task_id} dengan nilai task_id yang dikembalikan oleh panggilan API sebelumnya. task_id berlaku untuk kueri selama 24 jam, Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda.

curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Parameter tanggapan

outputobjectOutput tugas.

Properti

task_id stringID tugas. Berlaku untuk kueri selama 24 jam.task_status stringStatus tugas.

Nilai enumerasi

PENDING
RUNNING
SUCCEEDED
FAILED
CANCELED
UNKNOWN: Tugas tidak ada atau statusnya tidak diketahui.

Transisi status selama polling:

PENDING → RUNNING → SUCCEEDED atau FAILED.
Status kueri awal biasanya PENDING atau RUNNING.
Saat status berubah menjadi SUCCEEDED, tanggapan berisi URL video yang dihasilkan.
Jika statusnya FAILED, periksa pesan kesalahan dan coba ulang tugas tersebut.

submit_time stringWaktu saat tugas diajukan. Waktu dalam UTC+8 dan formatnya YYYY-MM-DD HH:mm:ss.SSS.scheduled_time stringWaktu saat tugas dieksekusi. Waktu dalam UTC+8 dan formatnya YYYY-MM-DD HH:mm:ss.SSS.end_time stringWaktu saat tugas selesai. Waktu dalam UTC+8 dan formatnya YYYY-MM-DD HH:mm:ss.SSS.video_urlstringHanya dikembalikan ketika task_status bernilai SUCCEEDED.URL berlaku selama 24 jam. Unduh video MP4 (24 fps, encoding H.264) dari URL ini.orig_prompt stringPrompt input asli, sesuai dengan parameter permintaan prompt.code stringKode kesalahan. Hanya dikembalikan untuk permintaan yang gagal. Lihat Kode kesalahan.message stringPesan kesalahan detail. Hanya dikembalikan untuk permintaan yang gagal. Lihat Kode kesalahan.

usage objectStatistik penggunaan. Dihitung hanya untuk tugas yang berhasil.

Properti

input_video_duration integerDurasi video input, dalam detik.output_video_duration integerDurasi video output, dalam detik.duration integerTotal durasi video yang digunakan untuk penagihan.SR integerResolusi video output.video_count integerJumlah video output. Nilai ini selalu 1.

request_id stringIdentifier permintaan unik untuk pelacakan dan troubleshooting.

Tugas berhasil
Tugas gagal
Kueri tugas kedaluwarsa

URL video hanya berlaku selama 24 jam, lalu secara otomatis dihapus. Segera simpan video yang dihasilkan.

{
    "request_id": "8ae698ba-df2d-966c-abcf-xxxxxx",
    "output": {
        "task_id": "e56d806f-76f9-4037-aefa-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-04-20 19:33:50.425",
        "scheduled_time": "2026-04-20 19:33:50.463",
        "end_time": "2026-04-20 19:35:34.216",
        "orig_prompt": "A cat running on the grass",
        "video_url": "https://dashscope-result.oss-cn-beijing.aliyuncs.com/xxx.mp4?Expires=xxx"
    },
    "usage": {
        "duration": 5,
        "input_video_duration": 0,
        "output_video_duration": 5,
        "video_count": 1,
        "SR": 720
    }
}

Saat tugas gagal, task_status bernilai FAILED dengan kode dan pesan kesalahan. Lihat Kode kesalahan.

{
    "request_id": "e5d70b02-ebd3-98ce-9fe8-759d7d7b107d",
    "output": {
        "task_id": "86ecf553-d340-4e21-af6e-a0c6a421c010",
        "task_status": "FAILED",
        "code": "InvalidParameter",
        "message": "The parameter is invalid."
    }
}

task_id berlaku selama 24 jam. Setelah periode ini, kueri akan mengembalikan kesalahan berikut.

{
    "request_id": "a4de7c32-7057-9f82-8581-xxxxxx",
    "output": {
        "task_id": "502a00b1-19d9-4839-a82f-xxxxxx",
        "task_status": "UNKNOWN"
    }
}

Kode kesalahan

Jika panggilan gagal, periksa referensi pesan kesalahan.

FAQ

Rasio aspek video

Rasio aspek output sesuai dengan frame pertama. Berbeda dengan model HappyHorse text-to-video, image-to-video tidak mendukung parameter ratio.

​Catatan penggunaan

​Panggilan HTTP

​Langkah 1: Buat tugas

Parameter permintaan

Body permintaan

Parameter tanggapan

​Langkah 2: Lakukan polling untuk hasilnya

Parameter permintaan

Header permintaan

Parameter path

Parameter tanggapan

​Kode kesalahan

​FAQ

​Rasio aspek video

Catatan penggunaan

Panggilan HTTP

Langkah 1: Buat tugas

Langkah 2: Lakukan polling untuk hasilnya

Kode kesalahan

FAQ

Rasio aspek video