📖 Hướng Dẫn Tích Hợp Advance Creation API

2. So sánh: Tệp Người Thật vs Clip do Coco sinh ra

Tiêu chí	Tệp người thật ngoài đời (Ảnh/Video thật)	Clip do chính Coco AI sinh ra
Bản chất media	Dữ liệu sinh trắc học người thật ngoài đời	Hình ảnh tổng hợp nhân tạo (Synthetic AI)
Có cần đăng ký Advance Creation không?	BẮT BUỘC	HOÀN TOÀN KHÔNG CẦN
Cách sử dụng làm tham chiếu	Đăng ký qua `POST /advance-creation` → Chờ duyệt `status = 1` (`VERIFIED`) → Lấy `assetId` truyền vào `files` của `POST /video`	Lấy trực tiếp trường `storagePublicId` từ kết quả `GET /video/:publicId` truyền thẳng vào `files[].assetId` của `POST /video`
Chi phí lưu trữ	Tính theo chu kỳ của `expiredType` (2 CC / 15 ngày)	Miễn phí, lưu trữ vĩnh viễn theo quota gói

3. Điều kiện tiên quyết (Prerequisites)

Gói tài khoản TITAN: Chỉ doanh nghiệp nâng cấp lên gói TITAN mới được mở khóa quyền sử dụng khuôn mặt người thật và cấp phép gọi API Advance Creation.

Kích hoạt tính năng & eKYC: Doanh nghiệp phải hoàn tất eKYC xác thực danh tính trên nền tảng Coco Studio Web.

Số dư Coco Credits (CC): Tài khoản cần có đủ số dư CC khả dụng để thanh toán phí lưu trữ tài nguyên.

4. Cơ chế Tính phí & Chi tiết tham số `expiredType`

A. Bảng quy đổi giá trị `expiredType`

Hệ thống tính thời hạn lưu trữ theo các chu kỳ (block), mỗi chu kỳ cố định là 15 ngày. Mỗi chu kỳ 15 ngày có phí duy trì là 2 CC.

Giá trị `expiredType`	Tên chu kỳ	Thời hạn sử dụng (`retentionDays`)	Chi phí (Coco Credits)	Mô tả & Khuyến nghị
`1`	`D15`	15 ngày	2 CC	Mặc định nếu không truyền. Phù hợp cho chiến dịch ngắn.
`2`	`D30`	30 ngày	4 CC	Dành cho dự án chạy trong 1 tháng.
`3`	`D45`	45 ngày	6 CC
`4`	`D60`	60 ngày	8 CC	Dành cho dự án 2 tháng.
`5`	`D75`	75 ngày	10 CC
`6`	`D90`	90 ngày	12 CC	Thời hạn lưu trữ tối đa cho 1 lần đăng ký (3 tháng).

B. Công thức tính toán

Thời hạn lưu trữ (ngày):

Chi phí Credit (CC):

C. Quy trình trừ phí & Hết hạn (Escrow & Expiry)

Lúc gửi request: Hệ thống tạm giữ (escrow) expiredType * 2 CC từ ví công ty.

Thẩm định thành công: Hệ thống chính thức trừ tiền (confirmEscrow) và mở khóa tệp.

Thẩm định thất bại: Hệ thống tự động hoàn lại 100% số tiền tạm giữ về ví công ty.

Khi hết hạn: Hệ thống chạy Cron Job mỗi 30 phút. Khi quá thời hạn (createdDate + retentionDays), asset tự động đổi sang trạng thái status: 3 (SUSPENDED) với lý do kycStatusText: "Expired" và không thể tiếp tục dùng để tạo video.

5. Vòng đời Trạng thái Asset (`status`)

Khi tra cứu tài nguyên qua API, trường status thể hiện tiến trình thẩm định:

[POST /advance-creation] ──► status: 1 (UNVERIFIED / "Processing")
                                     │
                 ┌───────────────────┴───────────────────┐
                 ▼                                       ▼
     status: 2 (VERIFIED)                    status: 3 (SUSPENDED)
  (Thẩm định thành công, sẵn sàng dùng)    (Bị từ chối hoặc Hết hạn lưu trữ)

1 (UNVERIFIED): Đang tải tệp ("Downloading") hoặc đang được AI thẩm định bản quyền ("Processing").

2 (VERIFIED): Đã thẩm định thành công ("Verified"). Tệp hợp lệ để đưa vào mảng files của API tạo video.

3 (SUSPENDED): Bị treo / khóa do bị từ chối thẩm định hoặc đã hết hạn lưu trữ ("Expired").

6. Danh mục Chi tiết các Endpoint REST API

Base URL: https://api.cocostudio.io
Header bắt buộc: apiKey: YOUR_API_KEY | Content-Type: application/json

A. Đăng ký Asset Người Thật (`POST /advance-creation`)

API dùng để đăng ký một tệp ảnh, video hoặc audio người thật lên hệ thống.

Phương thức: POST

Endpoint: /advance-creation

Request Body:

⚠️ Lưu ý: Chỉ truyền duy nhất 1 trong 2 trường: url (đường dẫn https bên ngoài) HOẶC assetId (tệp đã có sẵn trong kho Storage của công ty).

{
  "url": "https://your-storage-bucket.com/actors/portrait_face.jpg",
  "expiredType": 2
}

hoặc:

{
  "assetId": "550e8400-e29b-41d4-a716-446655440000",
  "expiredType": 1
}

Bảng tham số Request:

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
`url`	`string`	Tùy chọn	N/A	Đường dẫn HTTPS trực tiếp của ảnh/video/audio (tối đa 2048 ký tự). (Loại trừ với `assetId`)
`assetId`	`string`	Tùy chọn	N/A	Mã `publicId` của tệp đã có sẵn trong kho Storage. (Loại trừ với `url`)
`expiredType`	`integer`	Không	`1`	Gói thời hạn lưu trữ: `1` (15 ngày), `2` (30 ngày), ..., `6` (90 ngày).

Response mẫu (200 OK):

{
  "assetId": "f83a1b02-5c4d-4e6f-8a8b-0c1d2e3f4a5b",
  "status": 1,
  "createdDate": "2026-10-22T03:30:00.000Z"
}

B. Kiểm tra Trạng thái Xác thực Asset (`GET /advance-creation/:publicId`)

API dùng để kiểm tra xem tệp người thật đã được thẩm định thành công hay chưa.

Phương thức: GET

Endpoint: /advance-creation/:publicId (truyền assetId vào :publicId)

1. Response khi tệp Đang được thẩm định (`status: 1`):

{
  "assetId": "f83a1b02-5c4d-4e6f-8a8b-0c1d2e3f4a5b",
  "name": "portrait_face.jpg",
  "type": "image",
  "mimeType": "image/jpeg",
  "status": 1,
  "statusText": "Processing",
  "retentionDays": 30,
  "expiresAt": "2026-11-21T03:30:00.000Z",
  "createdDate": "2026-10-22T03:30:00.000Z"
}

(Nếu tải qua URL ngoài, statusText ban đầu có thể là "Downloading" trước khi chuyển sang "Processing").

2. Response khi tệp đã Thẩm định thành công (`status: 2` - Sẵn sàng sử dụng):

{
  "assetId": "f83a1b02-5c4d-4e6f-8a8b-0c1d2e3f4a5b",
  "name": "portrait_face.jpg",
  "type": "image",
  "mimeType": "image/jpeg",
  "status": 2,
  "statusText": "Verified",
  "retentionDays": 30,
  "expiresAt": "2026-11-21T03:30:00.000Z",
  "createdDate": "2026-10-22T03:30:00.000Z"
}

✅ Điều kiện sẵn sàng: Khi status = 2 và statusText = "Verified", bạn mới lấy assetId này đưa vào mảng files của POST /video.

3. Response khi tệp Bị từ chối hoặc Đã hết hạn (`status: 3`):

{
  "assetId": "f83a1b02-5c4d-4e6f-8a8b-0c1d2e3f4a5b",
  "name": "portrait_face.jpg",
  "type": "image",
  "mimeType": "image/jpeg",
  "status": 3,
  "statusText": "Expired",
  "retentionDays": 30,
  "expiresAt": "2026-11-21T03:30:00.000Z",
  "createdDate": "2026-10-22T03:30:00.000Z"
}

C. Lấy Danh sách Asset Advance Creation (`GET /advance-creation`)

API lấy danh sách các tệp người thật của doanh nghiệp kèm phân trang.

Phương thức: GET

Endpoint: /advance-creation?page=1&size=20

Query Parameters:

page (integer, tùy chọn): Số trang (mặc định: 1).

size (integer, tùy chọn): Số lượng mục mỗi trang (mặc định: 10, tối đa: 500).

⚠️ Lưu ý: Hệ thống sử dụng tham số size để phân trang. Không dùng limit (nếu truyền limit, hệ thống sẽ bỏ qua và mặc định trả về 10 dòng).

Response mẫu (200 OK):

{
  "total": 1,
  "rows": [
    {
      "assetId": "f83a1b02-5c4d-4e6f-8a8b-0c1d2e3f4a5b",
      "name": "portrait_face.jpg",
      "type": "image",
      "mimeType": "image/jpeg",
      "status": 2,
      "statusText": "Verified",
      "retentionDays": 30,
      "expiresAt": "2026-11-21T03:30:00.000Z",
      "createdDate": "2026-10-22T03:30:00.000Z"
    }
  ]
}

D. Ước tính Chi phí Đăng ký (`POST /advance-creation/estimate`)

Dự toán số tiền CC cần chi trả trước khi đăng ký tệp.

Phương thức: POST

Endpoint: /advance-creation/estimate

Body: Giống như POST /advance-creation.

Response mẫu (200 OK):

{
  "amount": 4,
  "currency": "CCC"
}

E. Xóa Asset Advance Creation (`DELETE /advance-creation/:publicId`)

Hủy và xóa tài nguyên người thật khỏi hệ thống.

Phương thức: DELETE

Endpoint: /advance-creation/:publicId

Response mẫu (200 OK):

{
  "success": true
}

7. Quy Trình Tích Hợp Hoàn Chỉnh (End-to-End Flow)

Dưới đây là mã lệnh minh họa quy trình từ lúc đăng ký khuôn mặt người thật cho đến khi tạo video thành công:

[Client]                                  [Coco Partner API]
   │                                               │
   │─── 1. POST /advance-creation ────────────────►│ (Tạm giữ 2 CC, đẩy sang BytePlus)
   │◄── Trả về assetId, status: 1 (UNVERIFIED) ───│
   │                                               │
   │─── 2. Polling GET /advance-creation/:assetId ─►│
   │◄── Trả về status: 2 (VERIFIED) ───────────────│ (Đã duyệt bản quyền khuôn mặt)
   │                                               │
   │─── 3. POST /video (files: [{assetId}]) ───────►│ (Tạo video với nhân vật người thật)
   │◄── Trả về publicId tác vụ video ──────────────│

Bước 1: Đăng ký tệp người thật

Nhận về: assetId: "f83a1b02-5c4d-4e6f-8a8b-0c1d2e3f4a5b"

Bước 2: Kiểm tra cho đến khi `status: 2` (VERIFIED)

Bước 3: Tạo video sử dụng nhân vật đã được duyệt

8. Bảng mã lỗi thường gặp (Troubleshooting)

HTTP Code	Thông báo lỗi	Nguyên nhân & Cách khắc phục
`400`	`Provide exactly one of url or assetId`	Không truyền cả hai hoặc truyền đồng thời cả `url` và `assetId`.
`400`	`expiredType must be one of 1, 2, 3, 4, 5, 6`	Truyền `expiredType` nằm ngoài khoảng giá trị quy định.
`400`	`Your balance (...) is not enough to upload this file (...)`	Số dư tài khoản không đủ để thanh toán phí lưu trữ.
`400`	`Advance Creation is not enabled for your company...`	Tài khoản chưa mua gói TITAN hoặc chưa hoàn tất eKYC.
`400`	`Asset ... is still being verified`	Đưa asset vào `POST /video` khi trạng thái vẫn đang là `UNVERIFIED`. Cần đợi chuyển sang `VERIFIED`.
`400`	`Asset ... is suspended (rejected or expired)`	Asset đã bị BytePlus từ chối thẩm định hoặc đã hết hạn lưu trữ (`expiredType`). Cần đăng ký lại.

📖 Hướng Dẫn Tích Hợp Advance Creation API

2. So sánh: Tệp Người Thật vs Clip do Coco sinh ra#

3. Điều kiện tiên quyết (Prerequisites)#

4. Cơ chế Tính phí & Chi tiết tham số expiredType#

A. Bảng quy đổi giá trị expiredType#

B. Công thức tính toán#

C. Quy trình trừ phí & Hết hạn (Escrow & Expiry)#

5. Vòng đời Trạng thái Asset (status)#

6. Danh mục Chi tiết các Endpoint REST API#

A. Đăng ký Asset Người Thật (POST /advance-creation)#

Request Body:#

Bảng tham số Request:#

Response mẫu (200 OK):#

B. Kiểm tra Trạng thái Xác thực Asset (GET /advance-creation/:publicId)#

1. Response khi tệp Đang được thẩm định (status: 1):#

2. Response khi tệp đã Thẩm định thành công (status: 2 - Sẵn sàng sử dụng):#

3. Response khi tệp Bị từ chối hoặc Đã hết hạn (status: 3):#

C. Lấy Danh sách Asset Advance Creation (GET /advance-creation)#

Query Parameters:#

Response mẫu (200 OK):#

D. Ước tính Chi phí Đăng ký (POST /advance-creation/estimate)#

Response mẫu (200 OK):#

E. Xóa Asset Advance Creation (DELETE /advance-creation/:publicId)#

Response mẫu (200 OK):#

7. Quy Trình Tích Hợp Hoàn Chỉnh (End-to-End Flow)#

Bước 1: Đăng ký tệp người thật#

Bước 2: Kiểm tra cho đến khi status: 2 (VERIFIED)#

Bước 3: Tạo video sử dụng nhân vật đã được duyệt#

8. Bảng mã lỗi thường gặp (Troubleshooting)#

2. So sánh: Tệp Người Thật vs Clip do Coco sinh ra

3. Điều kiện tiên quyết (Prerequisites)

4. Cơ chế Tính phí & Chi tiết tham số `expiredType`

A. Bảng quy đổi giá trị `expiredType`

B. Công thức tính toán

C. Quy trình trừ phí & Hết hạn (Escrow & Expiry)

5. Vòng đời Trạng thái Asset (`status`)

6. Danh mục Chi tiết các Endpoint REST API

A. Đăng ký Asset Người Thật (`POST /advance-creation`)

Request Body:

Bảng tham số Request:

Response mẫu (200 OK):

B. Kiểm tra Trạng thái Xác thực Asset (`GET /advance-creation/:publicId`)

1. Response khi tệp Đang được thẩm định (`status: 1`):

2. Response khi tệp đã Thẩm định thành công (`status: 2` - Sẵn sàng sử dụng):

3. Response khi tệp Bị từ chối hoặc Đã hết hạn (`status: 3`):

C. Lấy Danh sách Asset Advance Creation (`GET /advance-creation`)

Query Parameters:

Response mẫu (200 OK):

D. Ước tính Chi phí Đăng ký (`POST /advance-creation/estimate`)

Response mẫu (200 OK):

E. Xóa Asset Advance Creation (`DELETE /advance-creation/:publicId`)

Response mẫu (200 OK):

7. Quy Trình Tích Hợp Hoàn Chỉnh (End-to-End Flow)

Bước 1: Đăng ký tệp người thật

Bước 2: Kiểm tra cho đến khi `status: 2` (VERIFIED)

Bước 3: Tạo video sử dụng nhân vật đã được duyệt

8. Bảng mã lỗi thường gặp (Troubleshooting)