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

[Client] ──(1) Gửi Request POST /video (hoặc /image, /audio) kèm webHookUrl──► [Partner API]
[Client] ◄─(2) Trả về ngay publicId & status: 1 (PENDING)────────────────────── [Partner API]
                                                                                      │
                                                                           (3) Đẩy vào Queue xử lý
                                                                                      │
[Client] ◄════(4) Bắn Webhook POST kết quả khi AI render xong═════════════════════════╝
   hoặc
[Client] ──(5) Chủ động Polling GET /<service>/:publicId─────────────────────► [Partner API]

{
  "partnerModelId": "ep-20260809114245-bzj48",
  "name": "Text-to-Video: Drone Over Canyon",
  "prompt": "Cinematic aerial drone shot soaring through a red rock canyon at golden hour, breathtaking landscape, photorealistic 4k, smooth cinematic camera motion",
  "mode": 1,
  "resolution": 3,
  "ratio": 2,
  "duration": 1,
  "seconds": 5,
  "outputFormat": "mp4",
  "outputSound": true,
  "watermark": false,
  "webHookUrl": "https://your-webhook-domain.com/webhook/video"
}

{
  "partnerModelId": "ep-20260809114245-bzj48",
  "name": "Image-to-Video: Animate Portrait",
  "prompt": "The woman gently turns her head toward the camera, smiles softly as the sea breeze blows her hair, cinematic depth of field, warm sunset lighting",
  "mode": 1,
  "resolution": 3,
  "ratio": 2,
  "duration": 1,
  "seconds": 5,
  "outputFormat": "mp4",
  "outputSound": true,
  "webHookUrl": "https://your-webhook-domain.com/webhook/video",
  "files": [
    {
      "assetId": "4a71b290-7c23-42be-a37c-f179b00982df",
      "role": "reference_image"
    }
  ]
}

{
  "partnerModelId": "ep-20260809114245-bzj48",
  "name": "First & Last Frame: Day to Night",
  "prompt": "Smooth time-lapse transition from the daytime city view in @image1 to the glittering night skyline in @image2, vehicles moving with light trails",
  "mode": 2,
  "resolution": 3,
  "ratio": 2,
  "duration": 1,
  "seconds": 5,
  "outputFormat": "mp4",
  "outputSound": true,
  "webHookUrl": "https://your-webhook-domain.com/webhook/video",
  "files": [
    {
      "assetId": "4a71b290-7c23-42be-a37c-f179b00982df",
      "role": "first_frame"
    },
    {
      "assetId": "8b192834-31da-45e2-9b2f-110293847561",
      "role": "last_frame"
    }
  ]
}

{
  "partnerModelId": "dreamina-seedance-2-0-fast-260128",
  "name": "Fast Coffee Steam Scene",
  "prompt": "Close-up of hot steaming coffee being poured into a white ceramic cup on a wooden table, cozy morning atmosphere",
  "mode": 1,
  "resolution": 2,
  "ratio": 2,
  "duration": 1,
  "seconds": 4,
  "outputFormat": "mp4",
  "webHookUrl": "https://your-webhook-domain.com/webhook/video"
}

{
  "partnerModelId": "ep-20260809114245-bzj48",
  "name": "Multi-Video Kungfu Scene",
  "prompt": "Apply sword combat motion from @video1, orbit camera trajectory from @video2, character face from @image1",
  "mode": 1,
  "resolution": 3,
  "ratio": 2,
  "duration": 1,
  "seconds": 5,
  "outputFormat": "mp4",
  "webHookUrl": "https://your-webhook-domain.com/webhook/video",
  "files": [
    {
      "assetId": "e3057cae-9907-4e92-ba2c-2936c0500a4d",
      "role": "reference_video"
    },
    {
      "assetId": "8b192834-31da-45e2-9b2f-110293847561",
      "role": "reference_video"
    },
    {
      "assetId": "4a71b290-7c23-42be-a37c-f179b00982df",
      "role": "reference_image"
    }
  ]
}

{
  "partnerModelId": "ep-20260809114245-bzj48",
  "name": "Edit - Remove Object at 2s",
  "prompt": "Video editing: In @video1, remove the trash bin at the 2-second mark and replace it with a clean flower pot, leaving the rest of the clip completely unchanged.",
  "mode": 3,
  "resolution": 3,
  "ratio": 7,
  "duration": 2,
  "outputFormat": "mov",
  "outputSound": true,
  "webHookUrl": "https://your-webhook-domain.com/webhook/video",
  "files": [
    {
      "assetId": "e3057cae-9907-4e92-ba2c-2936c0500a4d",
      "role": "reference_video"
    }
  ]
}

{
  "partnerModelId": "ep-20260809114245-bzj48",
  "name": "Edit - Replace Subject with Image",
  "prompt": "Editing task: Replace the protagonist in @video1 with the female character from @image1. Maintain exact lighting, camera movement, and walking sequence.",
  "mode": 3,
  "resolution": 3,
  "ratio": 7,
  "duration": 2,
  "outputFormat": "mov",
  "outputSound": true,
  "webHookUrl": "https://your-webhook-domain.com/webhook/video",
  "files": [
    {
      "assetId": "e3057cae-9907-4e92-ba2c-2936c0500a4d",
      "role": "reference_video"
    },
    {
      "assetId": "4a71b290-7c23-42be-a37c-f179b00982df",
      "role": "reference_image"
    }
  ]
}

{
  "partnerModelId": "ep-20260809114245-bzj48",
  "name": "Extend - Continue Story",
  "prompt": "Extend @video1 backward: The astronaut continues walking on the red sand of Mars, turns back toward the base station, and waves at the rover.",
  "mode": 4,
  "resolution": 3,
  "ratio": 7,
  "duration": 1,
  "seconds": 6,
  "outputFormat": "mov",
  "outputSound": true,
  "webHookUrl": "https://your-webhook-domain.com/webhook/video",
  "files": [
    {
      "assetId": "e3057cae-9907-4e92-ba2c-2936c0500a4d",
      "role": "reference_video"
    }
  ]
}

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

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

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

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

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

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

{
  "publicId": "204afc22-41dd-4c6a-92e0-9981c4234d1e",
  "status": 2,
  "statusText": "success",
  "phase": "completed",
  "output": {
    "master": {
      "url": "https://s3.ap-southeast-1.amazonaws.com/files/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 }
}

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

{
  "balance": 1500.5,
  "credits": 1500.5,
  "availableBalance": 1500.5,
  "escrow": 20.0,
  "currency": "CCC",
  "lastModified": "2026-10-21T03:00:00.000Z"
}

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

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

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

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

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

{
  "estimatedCost": 25,
  "availableBalance": 1450.5,
  "sufficient": true
}

{
  "estimatedCost": 62,
  "availableBalance": 1450.5,
  "sufficient": true,
  "durationSeconds": 90,
  "approximate": false
}