Referensi API video editing HappyHorse - Alibaba Cloud Model Studio

Model video editing HappyHorse menerima video dan gambar referensi sebagai input, lalu melakukan tugas editing seperti style transfer dan penggantian lokal berdasarkan instruksi teks.

Ketersediaan

Pastikan bahwa model, URL endpoint, dan Kunci API berada di wilayah yang sama. Panggilan lintas-wilayah akan gagal.

Select a model: Periksa wilayah tempat model tersebut berada.
Select a URL: Gunakan URL endpoint untuk wilayah yang sesuai. URL HTTP didukung.
Configure an API key: Pilih wilayah dan Create an API key, lalu Export API key as environment variable.

CatatanKode contoh dalam topik ini berlaku untuk wilayah Singapura.

PentingAlibaba Cloud Model Studio telah merilis domain khusus ruang kerja untuk wilayah China (Beijing) dan Singapura. Domain khusus baru ini memberikan performa lebih unggul dan stabilitas lebih tinggi untuk permintaan inferensi. Kami menyarankan Anda bermigrasi ke domain baru:

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

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

Permintaan HTTP

Tugas video editing memakan waktu lama (biasanya 1–5 menit), sehingga API menggunakan panggilan asinkron. Alur kerja terdiri dari dua langkah: "Create a task → Poll for result" seperti dijelaskan di bawah ini:

Langkah 1: Buat tugas dan dapatkan ID tugas

Singapura

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

AS (Virginia)

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

China (Beijing)

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

Jerman (Frankfurt)

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

Jepang (Tokyo)

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

Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda.

Catatan

Setelah tugas dibuat, gunakan task_id yang dikembalikan untuk mengambil 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

Content-Type string (Wajib)

Tipe konten permintaan. Harus berupa application/json.

Authorization string (Wajib)

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

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

Body permintaan

model string (Wajib)

Nama model.

Nilai tetap: happyhorse-1.0-video-edit.

input object (Wajib)

Informasi input, termasuk video yang akan diedit, gambar referensi, dan prompt.

Properti

prompt string (Wajib)

Prompt teks yang menjelaskan edit yang dimaksudkan, seperti style transfer atau penggantian lokal.

Mendukung semua bahasa. Maksimal 5.000 karakter non-Cina atau 2.500 karakter Cina. Konten yang melebihi batas ini akan dipotong secara otomatis.

media array (Wajib)

Daftar aset media, termasuk video yang akan diedit dan gambar referensi opsional.

Array harus berisi tepat 1 elemen video dan boleh berisi 0–5 elemen reference_image.

Properti elemen

type string (Wajib)

Jenis aset media. Harus salah satu dari:

video: Wajib. Video yang akan diedit.
reference_image: Opsional. Gambar referensi.

Batas aset:

Video: tepat 1.
Gambar referensi: 0–5.

url string (Wajib)

URL aset media.

Input video (type=video)

URL video yang dapat diakses publik untuk diedit.

Mendukung HTTP dan HTTPS.
Contoh: https://xxx/xxx.mp4.

Persyaratan video:

Format: MP4, MOV (disarankan encoding H.264).
Durasi: 3–60 detik.
Resolusi: sisi panjang tidak boleh melebihi 4.096 px; sisi pendek minimal 360 px.
Rasio aspek: 1:2,5–2,5:1.
Ukuran file: maksimal 100 MB.
Laju frame: 8–60 fps. Jika video input memiliki laju frame variabel, pastikan perubahan laju frame tetap dalam rentang ini.

CatatanDurasi video output: 3–15 detik.

Jika video input berdurasi 15 detik atau kurang, video output memiliki durasi yang sama dengan input.
Jika video input lebih dari 15 detik, sistem secara otomatis hanya menggunakan 15 detik pertama, sehingga durasi output maksimal adalah 15 detik.

Input gambar (type=reference_image)

URL atau data gambar yang di-encode Base64.

Persyaratan gambar:

Format: JPEG, JPG, PNG, WEBP.
Resolusi: lebar dan tinggi minimal 300 px.
Rasio aspek: 1:2,5–2,5:1.
Ukuran file: maksimal 20 MB.

Format input yang didukung:

URL publik:
- Mendukung HTTP dan HTTPS.
- Contoh: https://xxx/xxx.png.
String gambar yang di-encode Base64:
- Format: data:{MIME_type};base64,{base64_data}.
- Contoh: data:image/png;base64,GDU7MtCZzEbTbmRZ...... (disingkat untuk demonstrasi).
  Format data encoding Base64
  Format: data:{MIME_type};base64,{base64_data} .
  - {base64_data}: String gambar yang di-encode Base64.
  - {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 video editing seperti resolusi.

Properti

resolution string (Opsional)

Resolusi video yang dihasilkan.

Nilai yang valid:

1080P (default)
720P

watermark boolean (Opsional)

Apakah akan menambahkan watermark ke video yang dihasilkan. Watermark muncul di pojok kanan bawah dengan teks "Happy Horse". Default-nya true.

true (default)
false

audio_setting string (Opsional)

Kontrol audio.

auto (default): Ditentukan oleh model.
origin: Mempertahankan audio asli dari video input.

seed integer (Opsional)

Seed bilangan acak harus berupa integer 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.

Video editing (instruksi + gambar referensi)

# URL berikut untuk wilayah Singapura. 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.0-video-edit",
    "input": {
        "prompt": "Make the horse-headed humanoid character in the video wear the striped sweater from the image",
        "media": [
            {
                "type": "video",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260409/dozxak/Wan_Video_Edit_33_1.mp4"
            },
            {
                "type": "reference_image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260415/hynnff/wan-video-edit-clothes.webp"
            }
        ]
    },
    "parameters": {
        "resolution": "720P"
    }
}'

Parameter respons

output object

Informasi output tugas.

Properti

task_id string

ID tugas. Berlaku untuk kueri selama 24 jam.

task_status string

Status tugas.

Nilai Enumerasi

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

request_id string

Identifier permintaan unik untuk pelacakan dan troubleshooting.

code string

Kode kesalahan. Hanya dikembalikan untuk permintaan yang gagal. Lihat Error codes.

message string

Pesan kesalahan detail. Hanya dikembalikan untuk permintaan yang gagal. Lihat Error codes.

Respons berhasil

Simpan task_id untuk mengecek status dan hasil tugas.

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

Respons error

Pembuatan tugas gagal. Lihat Error codes.

{
    "code": "InvalidApiKey",
    "message": "Invalid API-key provided.",
    "request_id": "7438d53d-6eb8-4596-8835-xxxxxx"
}

Langkah 2: Ambil hasil berdasarkan ID tugas

Singapura

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

AS (Virginia)

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

China (Beijing)

GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}

Jerman (Frankfurt)

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

Jepang (Tokyo)

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

Catatan

Polling: Video editing memerlukan beberapa menit. Gunakan mekanisme polling dengan interval yang masuk akal (misalnya, 15 detik) untuk memeriksa hasilnya.
Alur status tugas: PENDING (diantrikan) → RUNNING (diproses) → SUCCEEDED / FAILED.
Kedaluwarsa task_id: task_id kedaluwarsa setelah 24 jam. Setelah kedaluwarsa, hasil tidak dapat lagi diambil dan API mengembalikan status tugas UNKNOWN.

Parameter permintaan

Header

Authorization string (Wajib)

Mengotentikasi permintaan dengan Kunci API Model Studio. Contoh: Bearer sk-xxxx.

Parameter path

task_id string (Wajib)

ID tugas.

Hasil tugas kueri

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 respons

outputobject

Informasi output tugas.

Properti

task_id string

ID tugas. Berlaku untuk kueri selama 24 jam.

task_status string

Status 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, respons berisi URL video yang dihasilkan.
Jika statusnya FAILED, periksa pesan kesalahan dan coba ulang tugas tersebut.

submit_time string

Waktu saat tugas diajukan. Waktu dalam UTC+8 dan formatnya YYYY-MM-DD HH:mm:ss.SSS.

scheduled_time string

Waktu saat tugas dieksekusi. Waktu dalam UTC+8 dan formatnya YYYY-MM-DD HH:mm:ss.SSS.

end_time string

Waktu saat tugas selesai. Waktu dalam UTC+8 dan formatnya YYYY-MM-DD HH:mm:ss.SSS.

video_url string

URL video yang dihasilkan. Hanya dikembalikan jika task_status bernilai SUCCEEDED.

Berlaku selama 24 jam. Video dalam format MP4 dengan encoding H.264.

orig_prompt string

Prompt input asli, sesuai dengan parameter permintaan prompt.

code string

Kode kesalahan. Hanya dikembalikan untuk permintaan yang gagal. Lihat Error codes.

message string

Pesan kesalahan detail. Hanya dikembalikan untuk permintaan yang gagal. Lihat Error codes.

usage object

Statistik penggunaan. Hanya menghitung hasil yang berhasil.

Properti

duration float

Total durasi video dari video yang dihasilkan, digunakan untuk penagihan.

SR integer

Tingkat resolusi video yang dihasilkan.

output_video_duration float

Durasi video output, dalam detik.

input_video_duration float

Durasi video input, dalam detik.

video_count integer

Jumlah video yang dihasilkan. Selalu 1.

request_id string

Identifier permintaan unik untuk pelacakan dan troubleshooting.

Tugas berhasil

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

{
    "request_id": "c11018a8-3f83-9591-a636-xxxxxx",
    "output": {
        "task_id": "051c7b40-b2c5-4341-aee4-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-04-26 14:13:14.373",
        "scheduled_time": "2026-04-26 14:13:14.419",
        "end_time": "2026-04-26 14:14:13.679",
        "orig_prompt": "Dress the horse-headed humanoid character in the video in the striped sweater from the image",
        "video_url": "https://dashscope-result.oss-cn-beijing.aliyuncs.com/xxxx.mp4"
    },
    "usage": {
        "duration": 13.24,
        "input_video_duration": 6.62,
        "output_video_duration": 6.62,
        "video_count": 1,
        "SR": 720
    }
}

Tugas gagal

Jika tugas gagal, task_status bernilai FAILED dengan kode dan pesan kesalahan. Lihat Error codes.

{
    "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"
    }
}

Kueri tugas kedaluwarsa

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

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

Error codes

Jika pemanggilan model gagal dan mengembalikan pesan kesalahan, lihat Error codes untuk solusinya.