API Video

Buat, polling, dan unduh tugas video asinkron

Generasi video menggunakan model tugas asinkron: buat → polling status → unduh hasil. Gateway menyediakan dua path pembuatan; endpoint kueri dan unduhan dibagi bersama.

1. Ringkasan

Alur asinkron

Buat tugas → Poll GET /v1/videos/{task_id} → Unduh GET /v1/videos/{task_id}/content

Panggil POST /v1/videos atau POST /v1/multi/videos untuk mengirim tugas dan menerima task_id
Poll GET /v1/videos/{task_id} hingga status adalah completed atau failed
Setelah selesai, unduh melalui GET /v1/videos/{task_id}/content; opsional gunakan ?variant=thumbnail untuk gambar sampul

Membandingkan dua path pembuatan

Item	`POST /v1/videos`	`POST /v1/multi/videos`
Use case	Pembuatan video umum; field mengikuti konvensi model video upstream	Generasi video multimodal via `mode` + `assets[]`
Content-Type	`application/json` atau `multipart/form-data`	`application/json`
Param inti	`model`, `prompt`, `size`, `seconds`, `input_reference`	`model`, `mode`, `prompt`, `assets[]`, `resolution`, `duration_sec`, dll.
Gambar referensi	URL JSON / data URI Base64 / unggah file multipart	Kirim URL di `assets[]` berdasarkan `role`
Mode generasi	Tanpa field `mode`; ditentukan oleh model dan field permintaan	`mode` eksplisit: `t2v`, `i2v`, `first_frame`, `first_last_frame`, `ref_image`, `video_extend`, `video_edit`
Kueri & unduh	`GET /v1/videos/{task_id}`, `GET /v1/videos/{task_id}/content`	Sama (dibagi)

Prasyarat: model harus berupa model dari API Model yang supported_endpoint_types-nya mencakup openai-video.

2. Endpoint

Method	Path	Deskripsi
POST	`/v1/videos`	Buat tugas video (umum)
GET	`/v1/videos/{task_id}`	Kueri status tugas
GET	`/v1/videos/{task_id}/content`	Unduh video atau thumbnail
POST	`/v1/multi/videos`	Buat tugas video (multimodal / YunSell AI)

3. Status tugas

Item	Deskripsi
Format ID tugas	ID publik berbentuk `task_xxxxxxxx`
Alur status	`queued` → `in_progress` → `completed` / `failed`

`status`	Deskripsi
`queued`	Dalam antrean
`in_progress`	Sedang dihasilkan
`completed`	Selesai; siap diunduh
`failed`	Gagal; lihat field `error`

4. POST `/v1/videos`

Buat tugas video.

Auth: Bearer Token

Content-Type: application/json atau multipart/form-data

Body permintaan (JSON)

{
  "model": "sora-2",
  "prompt": "A cinematic shot of a cat walking on the beach at sunset, soft ocean waves, warm golden lighting",
  "size": "1280x720",
  "seconds": 8
}

Field permintaan

Field	Tipe	Wajib	Deskripsi
`model`	string	Ya	Nama model video
`prompt`	string	Ya	Deskripsi video (≤ 2500 karakter)
`size`	string	Bersyarat	Resolusi, mis. `1280x720`, `720x1280`; wajib untuk model seperti sora-2
`seconds`	int / string	Bersyarat	Durasi dalam detik; sora-2 mengizinkan `4/8/12/16/20`
`input_reference`	object / file	Tidak	Gambar referensi

Dengan gambar referensi (URL JSON):

{
  "model": "sora-2",
  "prompt": "Animate this image with a slight camera move",
  "size": "1280x720",
  "seconds": 8,
  "input_reference": {
    "image_url": "https://example.com/ref.jpg"
  }
}

Dengan gambar referensi (data URI Base64):

{
  "model": "sora-2",
  "prompt": "Animate this image with a slight camera move",
  "size": "1280x720",
  "seconds": 8,
  "input_reference": {
    "image_url": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
  }
}

multipart/form-data: input_reference adalah field form file; field lain menggunakan nama yang sama.

Contoh permintaan (curl)

JSON:

curl http://www.mangoto.ai/v1/videos \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "A cinematic shot of a cat walking on the beach at sunset, soft ocean waves, warm golden lighting",
    "size": "1280x720",
    "seconds": 8
  }'

Dengan gambar referensi (JSON):

curl http://www.mangoto.ai/v1/videos \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "Animate this image with a slight camera move",
    "size": "1280x720",
    "seconds": 8,
    "input_reference": {
      "image_url": "https://example.com/ref.jpg"
    }
  }'

multipart/form-data (unggah gambar referensi):

curl http://www.mangoto.ai/v1/videos \
  -H "Authorization: Bearer sk-xxx" \
  -F "model=sora-2" \
  -F "prompt=Animate this image with a slight camera move" \
  -F "size=1280x720" \
  -F "seconds=8" \
  -F "input_reference=@/path/to/ref.jpg"

Body respons

HTTP 200

{
  "id": "task_abc123xyz",
  "status": "queued",
  "progress": 0,
  "created_at": 1712697600
}

Field respons

Field	Tipe	Deskripsi
`id`	string	ID tugas untuk kueri dan unduhan
`status`	string	Awalnya `queued`
`progress`	integer	Progres 0–100
`created_at`	integer	Unix timestamp (detik)

Respons kegagalan

HTTP 400

{
  "code": "invalid_request",
  "message": "seconds must be one of 4, 8, 12, 16, 20"
}

Field	Tipe	Deskripsi
`code`	string	Kode error
`message`	string	Alasan kegagalan validasi

Lihat Error tugas untuk format error.

5. GET `/v1/videos/{task_id}`

Kueri status tugas video.

Auth: Bearer Token

Parameter path: task_id — id yang dikembalikan saat membuat tugas

Permintaan: Tanpa body permintaan

Contoh permintaan (curl)

curl http://www.mangoto.ai/v1/videos/task_abc123xyz \
  -H "Authorization: Bearer sk-xxx"

Body respons (sedang berlangsung)

HTTP 200

{
  "id": "task_abc123xyz",
  "object": "video",
  "model": "agnes-video-v2.0",
  "status": "in_progress",
  "progress": 45,
  "created_at": 1712697600,
  "seconds": "5.0",
  "size": "1280x704"
}

Body respons (selesai)

HTTP 200

{
  "id": "task_abc123xyz",
  "object": "video",
  "model": "agnes-video-v2.0",
  "status": "completed",
  "progress": 100,
  "created_at": 1712697600,
  "completed_at": 1712698200,
  "seconds": "5.0",
  "size": "1280x704",
  "remixed_from_video_id": "https://cdn.example.com/videos/video_abc.mp4",
  "error": null,
  "metadata": {
    "url": "https://cdn.example.com/videos/video_abc.mp4"
  }
}

Body respons (gagal)

HTTP 200

{
  "id": "task_abc123xyz",
  "object": "video",
  "model": "agnes-video-v2.0",
  "status": "failed",
  "progress": 100,
  "created_at": 1712697600,
  "error": {
    "message": "upstream generation failed",
    "code": "generation_failed"
  }
}

Field respons

Field	Tipe	Deskripsi
`id`	string	ID tugas; sama dengan `id` respons pembuatan
`object`	string	Selalu `video`
`model`	string	Model yang digunakan
`status`	string	Status tugas; lihat Status tugas
`progress`	integer	Progres 0–100
`created_at`	integer	Unix timestamp dibuat (detik)
`completed_at`	integer	Unix timestamp selesai (detik); dihilangkan saat belum selesai
`expires_at`	integer	Unix timestamp kedaluwarsa hasil (detik); dikembalikan beberapa channel
`seconds`	string	Durasi video dalam detik, mis. `"5.0"`
`size`	string	Resolusi video, mis. `"1280x704"`
`remixed_from_video_id`	string	URL hasil video; beberapa channel (mis. Agnes AI) mengembalikan alamat CDN di sini
`error`	object / null	Info error saat gagal; `null` atau dihilangkan saat berhasil
`error.message`	string	Alasan kegagalan
`error.code`	string	Kode error, mis. `generation_failed`
`metadata`	object	Metadata diperluas; kunci umum di bawah

Kunci metadata umum:

Kunci	Tipe	Deskripsi
`url`	string	URL hasil video
`thumbnail_url`	string	URL thumbnail
`duration`	number	Durasi aktual (detik)
`width`	integer	Lebar video (piksel)
`height`	integer	Tinggi video (piksel)
`fps`	integer	Frame rate
`seed`	integer	Seed acak

6. GET `/v1/videos/{task_id}/content`

Unduh video yang dihasilkan atau thumbnail.

Auth: Bearer Token atau Session konsol admin

Parameter path: task_id

Parameter query:

Parameter	Deskripsi
`variant`	Opsional. `video` (default) mengunduh video; `thumbnail` mengunduh gambar sampul

Prasyarat: status tugas harus completed.

Contoh permintaan (curl)

Unduh video (ikuti redirect 301):

curl -L http://www.mangoto.ai/v1/videos/task_abc123xyz/content \
  -H "Authorization: Bearer sk-xxx" \
  -o output.mp4

Unduh thumbnail:

curl -L "http://www.mangoto.ai/v1/videos/task_abc123xyz/content?variant=thumbnail" \
  -H "Authorization: Bearer sk-xxx" \
  -o cover.jpg

Respons (sudah disimpan di object storage)

HTTP 301 Moved Permanently

Location: https://cdn.example.com/users/1/tasks/task_abc123xyz/video.mp4

Header / field	Deskripsi
`Location`	URL resource object storage atau CDN; klien harus mengikuti redirect
Body	Tanpa konten JSON

Respons (gateway mem-proxy upstream)

HTTP 200, body adalah aliran biner (bukan JSON).

Header	Deskripsi
`Content-Type`	`video/mp4` (video) atau `image/jpeg` / `image/png` (thumbnail)
`Content-Length`	Ukuran file dalam byte
`Content-Disposition`	Mungkin menyertakan nama file, mis. `attachment; filename="task_abc123xyz.mp4"`
Body	Data biner video atau thumbnail

Respons error

Tugas belum selesai, HTTP 400:

{
  "error": {
    "message": "Task is not completed yet, current status: in_progress",
    "type": "invalid_request_error"
  }
}

Tugas tidak ditemukan, HTTP 404:

{
  "error": {
    "message": "Task not found",
    "type": "invalid_request_error"
  }
}

Variant tidak valid, HTTP 400:

{
  "error": {
    "message": "invalid variant \"cover\", must be \"video\" or \"thumbnail\"",
    "type": "invalid_request_error"
  }
}

Thumbnail tidak tersedia, HTTP 404:

{
  "error": {
    "message": "Thumbnail not available",
    "type": "invalid_request_error"
  }
}

Lihat Error standar untuk format error.

7. POST `/v1/multi/videos`

Generasi video multimodal. Tentukan mode generasi dengan mode, dan kirim URL gambar/video melalui assets[].

Setelah submit berhasil, kueri dengan GET /v1/videos/{task_id} dan unduh dengan GET /v1/videos/{task_id}/content.

Auth: Bearer Token

Content-Type: application/json

Mode generasi (`mode`)

`mode`	Deskripsi	Aset wajib tipikal
`t2v`	Teks-ke-video	Tidak ada
`i2v`	Gambar-ke-video	`image`
`first_frame`	Frame pertama ke video	`first_frame`
`first_last_frame`	Frame pertama dan terakhir ke video	`first_frame`, `last_frame`
`ref_image`	Gambar referensi ke video	Minimal satu `reference_images`
`video_extend`	Perpanjang / lanjutkan video	`source_video`
`video_edit`	Edit video cerdas	`source_video`; opsional `reference_images`

Nilai mode yang diaktifkan per model mengikuti konfigurasi konsol admin Kemampuan model → Kemampuan video.

Field permintaan

Field	Tipe	Wajib	Deskripsi
`model`	string	Ya	Model video
`mode`	string	Ya	Mode generasi
`prompt`	string	Bersyarat	Deskripsi video; wajib untuk sebagian besar mode
`assets`	array	Bersyarat	`[{ "role": "...", "url": "https://..." }]`
`resolution`	string	Tidak	mis. `720p`, `1080p`
`duration_sec`	number	Tidak	Durasi (detik)
`aspect_ratio`	string	Tidak	mis. `16:9`, `3:2`
`prompt_optimize`	boolean	Tidak	Apakah mengaktifkan optimasi prompt
`gen_tier`	string	Tidak	Tingkat generasi
`quality`	string	Tidak	Kualitas
`audio_mode`	string	Tidak	Mode audio
`camera_control`	string	Tidak	Kontrol kamera
`shot_type`	string	Tidak	Jenis shot
`hd_upscale`	string	Tidak	Upscale HD

Contoh permintaan: teks-ke-video (t2v)

{
  "model": "agnes-video-v2.0",
  "mode": "t2v",
  "prompt": "A cinematic shot of a cat walking on the beach at sunset, soft ocean waves, warm golden lighting, realistic motion",
  "resolution": "720p",
  "duration_sec": 5,
  "aspect_ratio": "3:2",
  "prompt_optimize": false
}

Contoh permintaan: frame pertama ke video (first_frame)

{
  "model": "agnes-video-v2.0",
  "mode": "first_frame",
  "prompt": "The woman slowly turns around and looks back at the camera, natural facial expression, cinematic camera movement",
  "assets": [
    { "role": "first_frame", "url": "https://example.com/image.png" }
  ],
  "duration_sec": 5
}

Contoh permintaan: gambar referensi ke video (ref_image)

{
  "model": "agnes-video-v2.0",
  "mode": "ref_image",
  "prompt": "Create a smooth transformation scene between the two reference images, cinematic lighting, consistent character identity, natural motion",
  "assets": [
    { "role": "reference_images", "url": "https://example.com/image1.png" },
    { "role": "reference_images", "url": "https://example.com/image2.png" }
  ],
  "duration_sec": 5
}

Contoh permintaan: perpanjang video (video_extend)

{
  "model": "wan2.6-t2v",
  "mode": "video_extend",
  "prompt": "Continue the scene with the character walking into the sunset",
  "assets": [
    { "role": "source_video", "url": "https://example.com/source.mp4" }
  ],
  "duration_sec": 5,
  "resolution": "720p"
}

Contoh permintaan (curl)

Teks-ke-video (t2v):

curl http://www.mangoto.ai/v1/multi/videos \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agnes-video-v2.0",
    "mode": "t2v",
    "prompt": "A cinematic shot of a cat walking on the beach at sunset, soft ocean waves, warm golden lighting, realistic motion",
    "resolution": "720p",
    "duration_sec": 5,
    "aspect_ratio": "3:2",
    "prompt_optimize": false
  }'

Frame pertama ke video (first_frame):

curl http://www.mangoto.ai/v1/multi/videos \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agnes-video-v2.0",
    "mode": "first_frame",
    "prompt": "The woman slowly turns around and looks back at the camera, natural facial expression, cinematic camera movement",
    "assets": [
      {"role": "first_frame", "url": "https://example.com/image.png"}
    ],
    "duration_sec": 5
  }'

Gambar referensi ke video (ref_image):

curl http://www.mangoto.ai/v1/multi/videos \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agnes-video-v2.0",
    "mode": "ref_image",
    "prompt": "Create a smooth transformation scene between the two reference images, cinematic lighting, consistent character identity, natural motion",
    "assets": [
      {"role": "reference_images", "url": "https://example.com/image1.png"},
      {"role": "reference_images", "url": "https://example.com/image2.png"}
    ],
    "duration_sec": 5
  }'

Perpanjang video (video_extend):

curl http://www.mangoto.ai/v1/multi/videos \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.6-t2v",
    "mode": "video_extend",
    "prompt": "Continue the scene with the character walking into the sunset",
    "assets": [
      {"role": "source_video", "url": "https://example.com/source.mp4"}
    ],
    "duration_sec": 5,
    "resolution": "720p"
  }'

Body respons

HTTP 200

{
  "id": "task_abc123xyz",
  "status": "queued",
  "progress": 0,
  "created_at": 1712697600
}

Field respons

Sama dengan respons pembuatan POST /v1/videos.

Field	Tipe	Deskripsi
`id`	string	ID tugas untuk kueri dan unduhan berikutnya
`status`	string	Awalnya `queued`
`progress`	integer	Progres 0–100
`created_at`	integer	Unix timestamp dibuat (detik)

Kueri dan unduhan berikutnya menggunakan GET /v1/videos/{task_id} dan GET /v1/videos/{task_id}/content. Field respons ada di Bagian 5 dan Bagian 6.

Respons kegagalan

HTTP 400

{
  "code": "invalid_request",
  "message": "model and mode are required"
}

{
  "code": "invalid_request",
  "message": "prompt is required"
}

Lihat Error tugas untuk format error.

8. Alur video asinkron yang disarankan

1. POST /v1/videos atau POST /v1/multi/videos
   → dapatkan task_id

2. Poll GET /v1/videos/{task_id}
   → lanjutkan menunggu saat status = queued / in_progress
   → periksa error saat status = failed
   → lanjutkan saat status = completed

3. GET /v1/videos/{task_id}/content
   → unduh file video

4. (Opsional) GET /v1/videos/{task_id}/content?variant=thumbnail
   → unduh thumbnail

Interval polling yang disarankan: 3–10 detik, untuk menghindari rate limiting dari permintaan yang terlalu sering.

API Gambar

Teks-ke-gambar dan gambar-ke-gambar/edit; secara sinkron mengembalikan URL gambar atau data Base64

API Audio

Teks-ke-ucapan (TTS) dan kueri daftar suara