AI Video Upscale API

Nâng chất lượng và độ phân giải của video: tăng độ nét, giảm nhiễu, và có thể xuất sang định dạng hậu kỳ (ProRes, FFV1, EXR). Tác vụ chạy bất đồng bộ; kết quả trả qua Webhook (mục 7) hoặc tra cứu (mục 8).

Nguồn video là một trong hai:

videoPublicId: một video bạn đã tạo bằng POST /video và đã hoàn thành.

videoUrl: đường dẫn https tới file MP4/MOV, tối đa 10 GB. Hệ thống tự tải file về trước khi xử lý.

A. Ma trận Định dạng đầu ra (`outputFormat`)

`outputFormat`	File nhận được	`toolVersion`	Nhận `bitrate`	Giới hạn video đầu vào
`auto` (mặc định)	`.mp4`	`standard` / `professional`	Có	—
`h264_8`	`.mp4` – H.264 8-bit	`professional`	Có	—
`h265_8`	`.mp4` – H.265 8-bit	`professional`	Có	—
`h265_10`	`.mp4` – H.265 10-bit	`professional`	Có	—
`prores_10`	`.mov` – ProRes 422 HQ 10-bit	`professional`	Không	—
`ffv1_16`	`.mov` – FFV1 16-bit (lossless)	`professional`	Không	Tối đa 40 giây
`exr_16`	`.zip` – chuỗi ảnh EXR 16-bit, không có âm thanh	`professional`	Không	Tối đa 40 giây

⚠️ ProRes, FFV1, EXR và H.265 10-bit thường không phát được trên trình duyệt: hãy tải file về và mở bằng phần mềm dựng phim. File có thể rất lớn (FFV1 ~77 MB mỗi giây ở 1080p, EXR ~1,6 GB cho 6 giây ở 1080p).
⚠️ Professional 16-bit (ffv1_16, exr_16) có thể mất hơn 20 phút kể cả với video vài giây. Nên nhận kết quả qua Webhook.

Danh sách định dạng đang được bật cho tài khoản: GET /video-upscale/capabilities.

B. Bảng tham số: Tạo tác vụ Upscale (`POST /video-upscale`)

Tham số	Kiểu dữ liệu	Bắt buộc	Khoảng giá trị / Mô tả
`videoPublicId`	`string`	Có*	`publicId` của video (`POST /video`) đã hoàn thành và còn trong thời hạn lưu
`videoUrl`	`string`	Có*	URL https tới file MP4/MOV, tối đa 10 GB, truy cập công khai (URL có chữ ký cũng được). Không chấp nhận địa chỉ nội bộ / IP riêng
`resolution`	`string`	Có**	Độ phân giải đầu ra: `"240p"`, `"360p"`, `"480p"`, `"540p"`, `"720p"`, `"1080p"`, `"2K"`, `"4K"`, `"8K"`
`resolutionLimit`	`integer`	Có**	Thay cho `resolution`: khoá cạnh ngắn của video ở N pixel (128 – 2160)
`fps`	`integer`	Có	Số khung hình/giây đầu ra: 15 – 120
`toolVersion`	`string`	Không	`"standard"` (mặc định) hoặc `"professional"` (chất lượng cao hơn, giá cao hơn; bắt buộc với định dạng hậu kỳ)
`outputFormat`	`string`	Không	Xem bảng A. Mặc định `"auto"`
`scene`	`string`	Không	Chỉ áp dụng cho Standard: `"common"`, `"aigc"`, `"short_series"`, `"ugc"`, `"old_film"`
`enhanceStyle`	`string`	Không	`"hd"` (mặc định) hoặc `"natural"`
`bitrateLevel`	`string`	Không	`"low"`, `"medium"` (mặc định), `"high"`. Không dùng chung với `bitrate`
`bitrate`	`integer`	Không	Bitrate cụ thể (kbps): 10 – 150000. Không dùng chung với `bitrateLevel`
`name`	`string`	Không	Tên tác vụ (tối đa 256 ký tự). Bỏ trống → `"Upscale · <publicId>"`
`webHookUrl`	`string`	Có	URL nhận kết quả khi tác vụ kết thúc

* Gửi đúng một trong hai: videoPublicId hoặc videoUrl.
** Gửi một trong hai: resolution hoặc resolutionLimit.

C. Request Body mẫu: Upscale từ video đã tạo (`POST /video-upscale`)

{
  "videoPublicId": "09109249-8fa5-4857-a488-9946f124957e",
  "resolution": "1080p",
  "fps": 30,
  "webHookUrl": "https://your-domain.com/webhooks/coco"
}

D. Request Body mẫu: Upscale từ URL, xuất ProRes (`POST /video-upscale`)

{
  "videoUrl": "https://cdn.your-domain.com/videos/clip.mp4",
  "name": "Clip quảng cáo – ProRes",
  "resolution": "4K",
  "fps": 30,
  "toolVersion": "professional",
  "outputFormat": "prores_10",
  "webHookUrl": "https://your-domain.com/webhooks/coco"
}

Response:

{
  "publicId": "c79370e7-d263-4bb9-adc6-7136f00e333d",
  "name": "Clip quảng cáo – ProRes",
  "status": 0,
  "statusText": "pending",
  "phase": "downloading",
  "errorMessage": "",
  "createdDate": "2026-10-05T08:06:07.000Z",
  "output": { "master": null, "verifyStatus": null, "billing": null },
  "balance": { "estimateCost": 0, "confirmCost": null }
}

E. Trạng thái & Kết quả (`GET /video-upscale/:publicId`)

`status`	`statusText`	Ý nghĩa
`0`	`pending`	Đang chờ (đang tải file nguồn hoặc chờ xử lý)
`1`	`processing`	Đang upscale
`2`	`success`	Hoàn thành
`3`	`failure`	Thất bại, xem `errorMessage`

phase chi tiết hơn: "downloading" (đang tải file từ videoUrl), "queued", "processing", "completed", "failed".

Kết quả khi hoàn thành:

{
  "publicId": "204afc22-41dd-4c6a-92e0-9981c4234d1e",
  "status": 2,
  "statusText": "success",
  "phase": "completed",
  "output": {
    "master": {
      "url": "https://…/204afc22-41dd-4c6a-92e0-9981c4234d1e.mov",
      "fileName": "204afc22-41dd-4c6a-92e0-9981c4234d1e.mov",
      "mimeType": "video/quicktime",
      "contentType": "video",
      "container": "mov",
      "codec": "ffv1",
      "bitDepth": 16,
      "width": 1920,
      "height": 1080,
      "sizeBytes": 309941372,
      "durationSeconds": 4,
      "hasAudio": false
    },
    "verifyStatus": "matched",
    "billing": "charged"
  },
  "balance": { "estimateCost": 23, "confirmCost": 22 }
}

Trường	Mô tả
`output.master.url`	Link tải file kết quả, lưu 30 ngày kể từ khi hoàn thành
`output.master.contentType`	`"video"`, hoặc `"image_sequence"` (EXR, file `.zip`)
`output.verifyStatus`	`"matched"`: đúng định dạng yêu cầu. `"mismatched"` / `"unverifiable"`: khác hoặc không kiểm chứng được, khi đó không tính phí
`output.billing`	`"charged"` (đã trừ tiền), `"waived"` (miễn phí), `"refunded"` (đã hoàn tiền)
`balance.estimateCost`	Số tiền tạm giữ (escrow) khi bắt đầu xử lý
`balance.confirmCost`	Số tiền thực tế bị trừ. `null` khi tác vụ chưa kết thúc

⚠️ Chi phí tính theo độ phân giải đầu ra, fps, toolVersion (Professional đắt hơn Standard) và thời lượng video; outputFormat không làm thay đổi giá. Tác vụ thất bại được hoàn tiền toàn bộ.

Video Upscale

Gửi một lần khi tác vụ kết thúc. source = 4 là sự kiện của Video Upscale. Sau khi nhận, gọi GET /video-upscale/:publicId để lấy link file và chi phí.

{
  "aiVideoUpscaleId": "204afc22-41dd-4c6a-92e0-9981c4234d1e",
  "source": 4,
  "status": 2,
  "createdDate": "2026-10-05T09:41:48.000Z"
}

Khi thất bại (status = 3):

{
  "aiVideoUpscaleId": "739ae40d-1dda-408c-b211-de052055438c",
  "source": 4,
  "status": 3,
  "createdDate": "2026-10-05T09:41:49.000Z",
  "errorMessage": "Output format exr_16 accepts videos up to 40 seconds (this one is 41.00s)"
}

⚠️ Endpoint nhận webhook cần trả HTTP 2xx. Lỗi tạm thời được gửi lại; lỗi 4xx thì ngừng gửi.

Tra cứu theo publicId: GET /video-upscale/:publicId

Danh sách có phân trang: GET /video-upscale?page=1&size=20 (có thể thêm search để tìm theo tên)

Xoá tác vụ thất bại: DELETE /video-upscale/:publicId

Định dạng đang hỗ trợ: GET /video-upscale/capabilities

Các lỗi xảy ra sau khi tạo tác vụ (tác vụ chuyển status: 3, không tốn phí), trả trong errorMessage:

`errorMessage`	Ý nghĩa / Xử lý
`Download failed: the source returned HTTP <code>.`	Server chứa file từ chối khi hệ thống tải về
`Download failed: the source took too long to download.`	Tải file quá 3 giờ
`The source is not an MP4/MOV video file.`	URL không trả về video MP4/MOV
`Output format … accepts videos up to 40 seconds (this one is …s)`	Định dạng 16-bit với video dài hơn 40 giây
`Insufficient account balance.`	Số dư không đủ cho chi phí ước tính

D. Draft mode (bản nháp giá rẻ, chỉ Dreamina Seedance 2.5)

Tạo bản nháp 480p để duyệt nội dung với chi phí thấp, sau đó tạo bản chính thức 1080p dùng lại toàn bộ nội dung của bản nháp (prompt, file tham chiếu, thời lượng, tỉ lệ, seed, âm thanh).

Bước 1: POST /video, thêm tham số:

Tham số	Kiểu dữ liệu	Bắt buộc	Khoảng giá trị / Mô tả
`draft`	`boolean`	Không	`true` để tạo bản nháp. Chỉ dùng với model Dreamina Seedance 2.5 và `resolution` = 480p (`1`)

Bước 2: POST /video/:publicId/finalize (publicId của bản nháp), body tuỳ chọn:

Tham số	Kiểu dữ liệu	Bắt buộc	Khoảng giá trị / Mô tả
`webHookUrl`	`string`	Không	Bỏ trống thì dùng `webHookUrl` của bản nháp

Response trả về video mới (bản chính thức) với publicId riêng, kèm "draftOf": "<publicId bản nháp>".

⚠️ Bản nháp phải đã hoàn thành (status = 2), chưa từng finalize (mỗi bản nháp chỉ finalize một lần) và tạo cách đây không quá 7 ngày. Bản nháp tính giá video 480p, bản chính thức tính giá video 1080p.

GET /video và GET /video/:publicId có thêm hai trường: draft (true nếu là bản nháp) và finalized (true nếu bản nháp đã được dùng để tạo bản chính thức).

AI Video Upscale API - Hướng Dẫn Sử Dụng