HappyHorse - referensi-ke-video Referensi API

Catatan penggunaan

Untuk memastikan panggilan API berhasil, Anda harus menggunakan model, URL endpoint, dan Kunci API yang semuanya berada di wilayah yang sama. Panggilan lintas-wilayah akan gagal.

Select a model: Konfirmasi wilayah tempat model Anda berada.
Select a URL: Pilih URL endpoint yang sesuai. URL HTTP maupun SDK DashScope didukung.
Configure an API key: Pilih wilayah, dapatkan Kunci API, 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 menyarankan Anda bermigrasi ke domain baru berikut:

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 lama tetap berfungsi sepenuhnya.

Panggilan HTTP

Karena tugas referensi-ke-video memakan waktu lama (biasanya 1–5 menit), API menggunakan panggilan asinkron. Alur kerja terdiri dari dua langkah inti: "Create a task → Poll for the result".

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 menanyakan hasilnya. task_id berlaku selama 24 jam. Jangan membuat tugas duplikat. Sebagai gantinya, gunakan polling untuk mengambil hasilnya.
Untuk panduan pemula, lihat Call APIs with Postman or cURL.

Parameter permintaan

Header 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 ada, 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-r2v.input object (Wajib)Input model, yang mencakup gambar referensi dan prompt teks.

Properti

prompt string (Wajib)Deskripsi elemen yang diinginkan dan gaya visual untuk video yang dihasilkan.Input dalam bahasa apa pun didukung. Panjangnya dibatasi hingga 5.000 karakter non-Cina atau 2.500 karakter Cina. Konten yang melebihi batas ini akan dipotong secara otomatis.Referensi gambar: Dalam prompt, gunakan "[Image 1]" dan "[Image 2]" untuk merujuk ke gambar referensi yang sesuai dalam array media. Urutannya harus konsisten dengan urutan dalam array media. Saat menggunakan referensi, sebutkan objek dalam gambar tersebut, misalnya "wanita berqipao merah di [Image 1]".media array (Wajib)Daftar gambar referensi.Setiap elemen dalam array adalah objek media yang berisi bidang type dan url.

Urutan elemen dalam array ini menentukan urutan referensi subjek dalam prompt.
reference_image pertama dalam array sesuai dengan [Image 1], yang kedua dengan [Image 2], dan seterusnya.

Properti elemen

type string (Wajib)Jenis aset media. Atur nilai ini ke:

reference_image: Gambar referensi.

Batas aset:

Jumlah gambar referensi: 1 hingga 9.

url string (Wajib)URL atau data yang dikodekan Base64 dari gambar referensi.Persyaratan gambar:

Format: JPEG, JPG, PNG, WEBP.
Resolusi: Sisi terpendek minimal 400 piksel. Disarankan menggunakan gambar jernih dengan resolusi 720P atau lebih tinggi. Hindari gambar yang terlalu kecil, buram, atau terlalu terkompresi karena dapat menurunkan kualitas output.
Ukuran file maksimum: 20 MB.

Format input yang didukung:

URL publik:
- Mendukung protokol HTTP atau HTTPS.
- Contoh: https://xxx/xxx.jpg.
String gambar yang dikodekan Base64:
- Format data: data:{MIME_type};base64,{base64_data}.
- Contoh: data:image/png;base64,GDU7MtCZzEbTbmRZ...... (disingkat untuk keperluan tampilan).
  Format data yang dikodekan Base64
  Format: data:{MIME_type};base64,{base64_data} .
  - {base64_data}: String yang dikodekan Base64 dari file gambar.
  - {MIME_type}: Jenis media gambar, yang harus sesuai dengan format file.
  Format gambar
  Tipe MIME
  JPEG
  image/jpeg
  JPG
  image/jpeg
  PNG
  image/png
  WEBP
  image/webp

parameters object (Opsional)Parameter untuk generasi video, seperti resolusi video, rasio aspek, dan durasi.

Properti

resolution string (Opsional)Tingkat resolusi video yang dihasilkan.Nilai yang valid:

480P
720P
1080P: Nilai default.

ratio string (Opsional)Rasio aspek video yang dihasilkan.Nilai yang valid:

16:9: Nilai default.
9:16
3:4
4:3
4:5
5:4
1:1
9:21
21:9

duration integer (Opsional)Durasi video yang dihasilkan, dalam detik.Rentang nilai: Bilangan bulat dari 3 hingga 15.Nilai default: 5.watermark boolean (Opsional)Menentukan apakah watermark ditambahkan ke video yang dihasilkan. Watermark ditempatkan di pojok kanan bawah dengan teks tetap "Happy Horse".

true: Nilai default. Watermark ditambahkan.
false: Tidak ada watermark yang ditambahkan.

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 generasi model bersifat probabilistik, seed yang sama tidak menjamin hasil identik.

Referensi-ke-video (multi-gambar)

# URL berikut ini untuk wilayah Singapore. Saat memanggil, ganti {WorkspaceId} dengan ID ruang kerja aktual Anda. URL berbeda-beda tergantung 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-r2v",
    "input": {
        "prompt": "A woman in a red qipao from [Image 1] is first shown in a profile medium shot, highlighting the tailored cut and S-curve of the dress. The camera then switches to a low-angle shot, capturing her unfolding the fan from [Image 2] while the tassel earrings from [Image 3] sway with her head movement. The scene ends with a close-up of her face, focusing on the charm in her eyes as her fingertips touch the fan, showcasing Eastern elegance from multiple angles.",
        "media": [
            {
                "type": "reference_image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/mvzfud/hh-v2v-girl.jpg"
            },
            {
                "type": "reference_image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/fvuihk/hh-v2v2-folding-fan.jpg"
            },
            {
                "type": "reference_image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/imerii/hh-v2v-earrings.jpg"
            }
        ]
    },
    "parameters": {
        "resolution": "720P",
        "ratio": "16:9",
        "duration": 5
    }
}'

Parameter respons

output objectInformasi output tugas.

Properti

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

Nilai Enumerasi

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

request_id stringIdentifikasi unik permintaan 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.

Respons sukses
Respons kesalahan

Simpan task_id untuk menanyakan status dan hasil tugas.

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

Langkah 2: Dapatkan hasil tugas

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

Saran polling: Generasi video dapat memakan waktu beberapa menit. Kami menyarankan Anda menerapkan mekanisme polling dengan interval penanyakan yang wajar (misalnya, 15 detik) untuk mengambil hasilnya.
Alur status tugas: PENDING (Dalam antrean) → RUNNING (Diproses) → SUCCEEDED (Berhasil) atau FAILED (Gagal).
Masa berlaku ID tugas: ID tugas berlaku selama 24 jam. Setelah periode ini, Anda tidak dapat lagi menanyakan hasilnya, dan API akan mengembalikan status tugas UNKNOWN.

Parameter permintaan

Header permintaan

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

Parameter path URL

task_id string (Wajib)ID tugas.

Penanyakan hasil tugas

Ganti {task_id} dengan nilai task_id yang dikembalikan oleh panggilan API sebelumnya. task_id berlaku untuk penanyakan 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 respons

outputobjectInformasi output untuk tugas.

Properti

task_id stringID tugas. Berlaku untuk penanyakan 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 penanyakan awal biasanya PENDING atau RUNNING.
Saat status berubah menjadi SUCCEEDED, respons 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_url stringURL video yang dihasilkan. Hanya dikembalikan saat task_status bernilai SUCCEEDED.Berlaku selama 24 jam. Video dalam format MP4 dengan encoding H.264.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 untuk tugas. Anda hanya ditagih untuk tugas yang berhasil.

Properti

duration integerDurasi tagihan video yang dihasilkan, dalam detik.input_video_duration integerDurasi total video input, dalam detik. Nilai ini selalu 0 untuk tugas referensi-ke-video.output_video_duration integerDurasi total video output, dalam detik.ratio stringRasio aspek video yang dihasilkan.SR integerTingkat resolusi video yang dihasilkan.video_count integerJumlah video yang dihasilkan. Nilai ini selalu 1.

request_id stringIdentifikasi 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": "35137489-2862-96cb-b6f2-xxxxxx",
    "output": {
        "task_id": "1469cfc3-3004-4d9e-ab10-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-04-25 15:03:25.848",
        "scheduled_time": "2026-04-25 15:03:25.884",
        "end_time": "2026-04-25 15:04:05.882",
        "orig_prompt": "A woman in a red qipao from [Image 1] is first shown in a profile medium shot, highlighting the dress'\''s tailored cut and S-curve. The camera then switches to a low-angle shot, capturing her unfolding the fan from [Image 2] while the tassel earrings from [Image 3] sway with her head movement. The scene ends with a close-up of her face, focusing on the charm in her eyes as her fingertips touch the fan, showcasing Eastern elegance from multiple angles.",
        "video_url": "https://dashscope-result-intl.oss-ap-southeast-1.aliyuncs.com/xxxx.mp4"
    },
    "usage": {
        "duration": 5,
        "input_video_duration": 0,
        "output_video_duration": 5,
        "video_count": 1,
        "SR": 720,
        "ratio": "16:9"
    }
}

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 resolution is not valid xxxxxx"
    }
}

task_id berlaku selama 24 jam. Setelah periode ini, penanyakan 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 pemanggilan model gagal dan mengembalikan pesan kesalahan, lihat Kode kesalahan untuk solusinya.

​Catatan penggunaan

​Panggilan HTTP

​Langkah 1: Buat tugas

Parameter permintaan

Header permintaan

Body permintaan

Parameter respons

​Langkah 2: Dapatkan hasil tugas

Parameter permintaan

Header permintaan

Parameter path URL

Parameter respons

​Kode kesalahan

Catatan penggunaan

Panggilan HTTP

Langkah 1: Buat tugas

Langkah 2: Dapatkan hasil tugas

Kode kesalahan