📖 Coco Partner API – Hướng Dẫn Tích Hợp Hệ Thống

1. Giới thiệu tổng quan (Overview)

Coco Partner API là cổng kết nối RESTful API hiệu năng cao dành cho các đối tác / hệ thống bên thứ ba, cung cấp trọn bộ các dịch vụ Generative AI thế hệ mới:

🎬 AI Video Generation: Text-to-Video, Image-to-Video, Multimodal Reference Video, First & Last Frame Transition.

🖼️ AI Image Generation: Text-to-Image, Image-to-Image (Seedream 5.0 Lite/Pro của BytePlus, GPT Image của OpenAI).

🎙️ AI Audio Generation: Text-to-Speech (TTS), Voice Cloning / Reference Audio (Seed Audio).

🗄️ Model Management: Lấy danh sách model khả dụng theo thời gian thực.

2. Xác thực API (Authentication)

Tất cả các API yêu cầu xác thực bằng API Key thông qua Header của HTTP Request.

Header quy định:

Header Key	Kiểu dữ liệu	Bắt buộc	Mô tả
`apiKey` (hoặc `apikey`)	`string`	Có	Khóa API Key bí mật được cấp riêng cho đối tác
`Content-Type`	`string`	Có	`application/json`

3. AI Video Generation API

A. Ma trận so sánh giữa các Model Video

Tính năng / Thông số	Dreamina-Seedance-2.5 (Mới nhất)	Dreamina-Seedance-2.0, fast, mini / (Tiêu chuẩn)
Partner Model ID	`ep-20260809114245-bzj48` (hoặc `ep-20260824222535-8ddl9`)	`dreamina-seedance-2-0-fast-260128`
Loại Input hỗ trợ	Text, Image, Video, Audio	Text, Image, Video, Audio
Số lượng Ảnh tham chiếu (`files`)	Tối đa 30 ảnh (≤ 30MB/ảnh)	Tối đa 9 ảnh (≤ 30MB/ảnh)
Số lượng Video tham chiếu (`files`)	Tối đa 10 video (2s – 30s/clip, ≤ 200MB)	Tối đa 3 video (2s – 15s/clip, ≤ 200MB)
Số lượng Audio tham chiếu (`files`)	Tối đa 10 audio (2s – 30s/clip, ≤ 15MB)	Tối đa 3 audio (2s – 15s/clip, ≤ 15MB)
Chế độ tạo video (`mode`)	• `1`: Reference generation • `2`: First & Last frame	• `1`: Reference generation • `2`: First & Last frame
Độ dài xuất (`seconds`)	4 đến 30 giây	4 đến 15 giây
Chế độ Smart Length (`duration: 2`)	✅ Hỗ trợ (AI tự đo độ dài tối ưu)	❌ Không hỗ trợ
Độ phân giải (`resolution`)	`1` (480p), `2` (720p), `3` (1080p)	`1` (480p), `2` (720p), `3` (1080p), `4` (4k)
Tỉ lệ khung hình (`ratio`)	`1` (21:9), `2` (16:9), `3` (4:3), `4` (1:1), `5` (3:4), `6` (9:16)	`1` (21:9), `2` (16:9), `3` (4:3), `4` (1:1), `5` (3:4), `6` (9:16)
Định dạng xuất (`outputFormat`)	`"mp4"`, `"mov"`	`"mp4"`
Tự sinh âm thanh AI (`outputSound`)	✅ Có hỗ trợ	✅ Có hỗ trợ

B. Bảng mã định nghĩa Enums Video

mode: 1 (Reference Generation), 2 (First & Last Frame - yêu cầu truyền ảnh có role first_frame và last_frame).

resolution: 1 (480p), 2 (720p), 3 (1080p), 4 (4k).

ratio: 1 (21:9), 2 (16:9), 3 (4:3), 4 (1:1), 5 (3:4), 6 (9:16), 7 (adaptive).

duration: 1 (Seconds - bắt buộc truyền seconds), 2 (SmartLength - tự động độ dài).

C. Request Body mẫu: Tạo Video (`POST /video`)

{
  "partnerModelId": "ep-20260809114245-bzj48",
  "name": "Cinematic Beach Cat",
  "prompt": "A cute orange cat walking on a sunny beach, golden hour lighting, cinematic 4k",
  "mode": 1,
  "resolution": 2,
  "ratio": 2,
  "duration": 1,
  "seconds": 5,
  "outputFormat": "mp4",
  "outputSound": true,
  "watermark": false,
  "seed": -1,
  "webHookUrl": "https://your-webhook-domain.com/webhook/video",
  "files": [
    {
      "url": "https://your-storage-domain.com/cat.jpg",
      "mimeType": "image/jpeg",
      "role": "reference_image"
    }
  ]
}

4. AI Image Generation API

Hệ thống hỗ trợ cả 2 nhà cung cấp hàng đầu: BytePlus (Seedream 5.0 Lite/Pro) và OpenAI (GPT Image).

A. Ma trận so sánh giữa các Model Image

Thông số / Cấu hình	BytePlus (Seedream 5.0 Lite/Pro)	OpenAI (GPT Image)
Partner Model ID	`ep-20260824222944-wmrzt` (Lite) `ep-20260824223025-2c9qd` (Pro)	`gpt-image-2`
Độ phân giải (`resolution`)	`"1K"`, `"1.5K"`, `"2K"`, `"3K"`, `"4K"`	`"1024x1024"`, `"1024x1536"`, `"1536x1024"`, `"2560x1440"`, `"3840x2160"`
Tỉ lệ khung hình (`ratio`)	`"1:1"`, `"4:3"`, `"3:4"`, `"16:9"`, `"9:16"`, `"21:9"`	(Tự động theo kích thước `resolution`)
Chất lượng (`quality`)	N/A	`"low"`, `"medium"`, `"high"`
Độ trong suốt nền (`background`)	N/A	`"auto"`, `"transparent"`, `"opaque"`
Kiểm duyệt an toàn (`moderation`)	N/A	`"auto"`, `"low"`
Định dạng file xuất (`outputFormat`)	`"png"`, `"jpeg"`	`"png"`, `"jpeg"`, `"webp"` (Lưu ý: Transparent background yêu cầu PNG/WebP)
Số lượng tạo cùng lúc (`numOfGenerate`)	1 đến 14 ảnh	1 đến 14 ảnh
Ảnh tham chiếu (`files`)	Tối đa 14 ảnh (≤ 30MB/ảnh)	Tối đa 14 ảnh

B. Request Body mẫu: Tạo Ảnh (`POST /image`)

1. Dùng Model BytePlus (Seedream 5.0 Pro)

{
  "partnerModelId": "ep-20260824223025-2c9qd",
  "name": "Cyberpunk Street",
  "prompt": "Futuristic cyberpunk street at night, neon lights, rainy reflection, ultra-detailed, 8k",
  "resolution": "2K",
  "ratio": "16:9",
  "outputFormat": "png",
  "numOfGenerate": 2,
  "webHookUrl": "https://your-webhook-domain.com/webhook/image"
}

2. Dùng Model OpenAI (GPT Image - Nền trong suốt Transparent)

{
  "partnerModelId": "gpt-image-2",
  "name": "Logo Icon",
  "prompt": "A modern minimalist 3D coffee cup logo icon, vibrant colors",
  "resolution": "1024x1024",
  "quality": "high",
  "background": "transparent",
  "outputFormat": "png",
  "numOfGenerate": 1,
  "webHookUrl": "https://your-webhook-domain.com/webhook/image"
}

5. AI Audio Generation API (Text-to-Speech & Voice Cloning)

Hệ thống hỗ trợ model giọng nói Seed Audio với khả năng tùy biến chất giọng, tốc độ nói, cao độ và clone giọng từ file âm thanh mẫu.

A. Bảng thông số cấu hình Audio

Tham số	Kiểu dữ liệu	Bắt buộc	Khoảng giá trị / Mô tả
`partnerModelId`	`string`	Có	ID model Audio (lấy từ `GET /model/audio`)
`prompt`	`string`	Có	Nội dung văn bản cần chuyển thành giọng nói (tối đa 3000 ký tự)
`format`	`string`	Có	Định dạng âm thanh: `"mp3"`, `"wav"`, `"pcm"`, `"ogg"`
`sampleRate`	`number`	Có	Tần số mẫu: `16000`, `24000`, `44100`, `48000` (Hz)
`tone`	`number`	Không	Cao độ giọng nói (pitch rate): từ `-12` đến `12` (mặc định `0`)
`speechRate`	`number`	Không	Tốc độ nói: từ `-50` đến `100` (mặc định `0`)
`volume`	`number`	Không	Âm lượng (loudness): từ `-50` đến `100` (mặc định `0`)
`numOfGenerate`	`number`	Có	Số lượng audio tạo cùng lúc (từ `1` đến `8`)
`files`	`array`	Không	Mảng file audio mẫu để Clone giọng (tối đa 3 clips, ≤ 10MB/clip)
`imageFile`	`object`	Không	Ảnh tham chiếu cảm xúc nhân vật (≤ 10MB)
`webHookUrl`	`string`	Có	URL nhận kết quả Webhook

⚠️ Lưu ý: files (Audio Reference) và imageFile (Image Reference) là loại trừ lẫn nhau (chỉ chọn truyền 1 trong 2).

B. Request Body mẫu: Tạo Audio (`POST /audio`)

{
  "partnerModelId": "seed-audio-1.0",
  "name": "Podcast Intro Voice",
  "prompt": "Welcome to our AI technology podcast. Today we will explore the future of Generative AI!",
  "format": "mp3",
  "sampleRate": 44100,
  "tone": 0,
  "speechRate": 10,
  "volume": 0,
  "numOfGenerate": 1,
  "webHookUrl": "https://your-webhook-domain.com/webhook/audio"
}

6. Quản lý Danh sách Model (`GET /model/*`)

Các API này không cần truyền body, dùng để lấy danh sách partnerModelId và name chính xác đang hoạt động trên hệ thống:

Phương thức	Endpoint	Mô tả
`GET`	`/model/video`	Lấy danh sách các Model Video
`GET`	`/model/image`	Lấy danh sách các Model Image
`GET`	`/model/audio`	Lấy danh sách các Model Audio

Response mẫu (200 OK):

{
  "code": 200,
  "data": [
    {
      "partnerModelId": "ep-20260824222944-wmrzt",
      "name": "Seedream-5-0-lite"
    },
    {
      "partnerModelId": "ep-20260824223025-2c9qd",
      "name": "Seedream-5-0-pro"
    },
    {
      "partnerModelId": "gpt-image-2",
      "name": "GPT Image"
    }
  ]
}

7. Cấu trúc dữ liệu Webhook Callback nhận kết quả

Khi bất kỳ tác vụ nào (Video, Image, Audio) hoàn tất render, hệ thống sẽ tự động gửi HTTP POST request đến webHookUrl bạn đã cung cấp:

Payload Callback Video:

{
  "id": "e3057cae-9907-4e92-ba2c-2936c0500a4d",
  "status": "success",
  "name": "Cinematic Beach Cat",
  "videoUrl": "https://s3.ap-southeast-1.amazonaws.com/files/video.mp4",
  "lastFrameUrl": "https://s3.ap-southeast-1.amazonaws.com/files/last-frame.jpeg",
  "thumbnailUrl": "https://s3.ap-southeast-1.amazonaws.com/files/thumb.jpg",
  "duration": 5,
  "resolution": "720p",
  "ratio": "16:9"
}

Payload Callback Image:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "success",
  "name": "Cyberpunk Street",
  "images": [
    {
      "url": "https://s3.ap-southeast-1.amazonaws.com/files/image-1.png",
      "thumbnailUrl": "https://s3.ap-southeast-1.amazonaws.com/files/thumb-1.jpg"
    }
  ]
}

Payload Callback Audio:

{
  "id": "7b8f9e60-f654-4a21-88bb-4c270d97bb01",
  "status": "success",
  "name": "Podcast Intro Voice",
  "audioUrl": "https://s3.ap-southeast-1.amazonaws.com/files/podcast.mp3",
  "duration": 6.2,
  "format": "mp3"
}

8. Tra cứu & Quản lý tác vụ qua API

Tra cứu chi tiết theo publicId:

GET /video/:publicId

GET /image/:publicId

GET /audio/:publicId

Lấy danh sách tác vụ (có phân trang):

GET /video?page=1&limit=20

GET /image?page=1&limit=20

GET /audio?page=1&limit=20

Xóa tác vụ thất bại:

DELETE /video/:publicId

DELETE /image/:publicId

DELETE /audio/:publicId

9. Bảng mã lỗi thường gặp (Error Codes)

HTTP Code	Error Message	Ý nghĩa & Cách xử lý
`400`	`ApiKey Invalid`	Header `apiKey` bị thiếu hoặc không chính xác
`400`	`Model is required` / `Not found partnerModelId`	Model không tồn tại. Gọi `GET /model/*` để lấy đúng ID
`400`	`Insufficient account balance`	Số dư tài khoản không đủ để tạm giữ cọc (escrow)
`400`	`Transparent background requires PNG or WebP output format`	Chọn `background: "transparent"` nhưng lại đặt `outputFormat: "jpeg"`
`400`	`Reference audio and reference image cannot be used together`	Audio API không cho phép truyền cả ảnh và clip audio cùng lúc
`400`	`This model only allows seconds from 4 to 30`	Tham số `seconds` vượt quá phạm vi của Video model
`429`	`Too Many Requests`	Vượt quá giới hạn tần suất gửi request (Rate Limit)

📖 Coco Partner API – Hướng Dẫn Tích Hợp Hệ Thống

1. Giới thiệu tổng quan (Overview)#

2. Xác thực API (Authentication)#

Header quy định:#

3. AI Video Generation API#

A. Ma trận so sánh giữa các Model Video#

B. Bảng mã định nghĩa Enums Video#

C. Request Body mẫu: Tạo Video (POST /video)#

4. AI Image Generation API#

A. Ma trận so sánh giữa các Model Image#

B. Request Body mẫu: Tạo Ảnh (POST /image)#

1. Dùng Model BytePlus (Seedream 5.0 Pro)#

2. Dùng Model OpenAI (GPT Image - Nền trong suốt Transparent)#

5. AI Audio Generation API (Text-to-Speech & Voice Cloning)#

A. Bảng thông số cấu hình Audio#

B. Request Body mẫu: Tạo Audio (POST /audio)#

6. Quản lý Danh sách Model (GET /model/*)#

7. Cấu trúc dữ liệu Webhook Callback nhận kết quả#

Payload Callback Video:#

Payload Callback Image:#

Payload Callback Audio:#

8. Tra cứu & Quản lý tác vụ qua API#

9. Bảng mã lỗi thường gặp (Error Codes)#