Seedance API

API นี้ช่วยให้คุณส่งงานสร้างวิดีโอของ Seedance 2.5 และ Seedance 2.0 ได้โดยใช้โปรแกรมอัตโนมัติ โดยเราขอแนะนำโมเดล Seedance 2.5 ซึ่งเป็นเวอร์ชันล่าสุดที่รองรับการสร้างวิดีโอจากข้อความ, การสร้างวิดีโอจากภาพแรก หรือภาพแรกและภาพสุดท้าย รวมถึงการใช้อ้างอิงแบบมัลติโมดอลเพื่อสร้างวิดีโอ การทำงานของระบบจะเป็นแบบอะซิงโครนัส (Asynchronous) กล่าวคือ เมื่อคุณสร้างงาน ระบบจะส่ง Task ID กลับไปให้ทันที จากนั้นคุณสามารถรับไฟล์วิดีโอที่เสร็จสมบูรณ์ได้ด้วยการส่งคำขอตรวจสอบสถานะ (Polling) หรือรับการแจ้งเตือนผ่านเว็บฮุค (Webhook)

สร้างคีย์ API ได้ที่แดชบอร์ด และส่งคีย์ดังกล่าวเป็น Bearer token ในทุกๆ คำขอ ทั้งนี้ ระบบจะแสดงคีย์ตัวเต็มให้เห็นเพียงครั้งเดียวตอนสร้างคีย์เท่านั้น

Authorization: Bearer sk_live_xxxxxxxx

เริ่มจากการส่งงานสร้างวิดีโอก่อน เมื่อระบบตอบรับงานแล้ว คุณสามารถเลือกวิธีรับผลลัพธ์ได้สองวิธี คือ ส่งคำขอตรวจสอบสถานะงาน (Poll) หรือรอรับผลลัพธ์สุดท้ายผ่านเว็บฮุค (Webhook)

curl https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5",
    "callback_url": "https://your-domain.com/api/seedance/webhook",
    "input": {
      "prompt": "a cat surfing on a neon wave, cinematic lighting",
      "generation_type": "text-to-video",
      "duration": 5,
      "aspect_ratio": "16:9",
      "resolution": "720p",
      "generate_audio": true,
      "watermark": false,
      "web_search": false,
      "return_last_frame": false
    }
  }'

curl https://api.seevio.ai/v1/tasks/3f2aK9mR7xQp4TnZ8bLc6YwH \
  -H "Authorization: Bearer sk_live_xxx"

export async function POST(request: Request) {
  const callbackData = await request.json();

  if (callbackData.status === "completed") {
    const videoUrl = callbackData.data.results[0];
    // Save the video URL or update your own task record here.
  }

  if (callbackData.status === "failed") {
    const errorMessage = callbackData.data.failed_reason;
    // Mark your own task record as failed here.
  }

  return new Response(null, { status: 200 });
}

สร้างงานวิดีโอโดยส่งคำขอ POST ไปที่ /v1/videos/generations โดยใน Body ของคำขอจะต้องประกอบด้วยฟิลด์ model ในระดับบนสุด ฟิลด์ callback_url (ไม่บังคับ) และออบเจกต์ input ที่ระบุข้อความคำสั่ง (prompt) พร้อมตั้งค่าการสร้างวิดีโอ

curl https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5",
    "callback_url": "https://your-domain.com/api/seedance/webhook",
    "input": {
      "prompt": "a cat surfing on a neon wave, cinematic lighting",
      "generation_type": "text-to-video",
      "duration": 5,
      "aspect_ratio": "16:9",
      "resolution": "720p",
      "generate_audio": true,
      "watermark": false,
      "web_search": false,
      "return_last_frame": false
    }
  }'

พารามิเตอร์ generation_type จะเป็นตัวกำหนดประเภทของสื่ออินพุตที่รองรับ และกำหนดวิธีการตีความข้อมูลของโมเดล

curl https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5",
    "callback_url": "https://your-domain.com/api/seedance/webhook",
    "input": {
      "prompt": "a cinematic drone shot over a futuristic coastal city at sunrise",
      "generation_type": "text-to-video",
      "duration": 5,
      "aspect_ratio": "16:9",
      "resolution": "720p",
      "generate_audio": true,
      "watermark": false,
      "web_search": false,
      "return_last_frame": false
    }
  }'

curl https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5",
    "input": {
      "prompt": "the subject turns toward camera, soft studio motion",
      "generation_type": "image-to-video",
      "image_urls": ["https://your.cdn.com/first-frame.jpg"],
      "duration": 5,
      "resolution": "720p"
    }
  }'

curl https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5",
    "input": {
      "prompt": "use the product from image 1 and the camera motion from the reference video",
      "generation_type": "reference-to-video",
      "image_urls": ["https://your.cdn.com/product.jpg"],
      "video_urls": ["https://your.cdn.com/camera-motion.mp4"],
      "audio_urls": [],
      "duration": 8,
      "resolution": "720p"
    }
  }'

ชื่อพารามิเตอร์, ค่า Enum, เส้นทางของเอนด์พอยต์ (paths) และตัวอย่างโครงสร้างข้อมูลทั้งหมดถือเป็นข้อกำหนดของ API ด้านล่างนี้คือคำอธิบายลักษณะการทำงานของแต่ละฟิลด์

นี่คือข้อมูลตอบกลับเมื่อทำรายการสำเร็จจาก POST /v1/videos/generations ซึ่งหมายความว่าระบบได้รับงานของคุณเรียบร้อยแล้วและได้ทำการสำรองเครดิตไว้แล้ว คุณสามารถใช้ taskId ที่ได้กลับไปเพื่อส่งคำขอตรวจสอบสถานะแบบ GET /v1/tasks/:id หรือใช้เพื่อจับคู่ข้อมูลส่งกลับ (Callback) เมื่อระบบประมวลผลงานเสร็จสิ้นหรือล้มเหลว

{
  "taskId": "3f2aK9mR...",
  "credits": 100
}

ใช้คำขอ GET /v1/tasks/:id เพื่อตรวจสอบสถานะปัจจุบันของงาน โดยแนะนำให้ส่งคำขอตรวจสอบสถานะได้ไม่เกิน 1 ครั้งในทุกๆ 10 วินาที ทั้งนี้สำหรับระบบที่นำไปใช้บริการจริง แนะนำให้เลือกใช้งานเว็บฮุคแทน

curl https://api.seevio.ai/v1/tasks/3f2aK9mR7xQp4TnZ8bLc6YwH \
  -H "Authorization: Bearer sk_live_xxx"

{
  "id": "3f2aK9mR...",
  "status": "completed",
  "created_at": 1781234567,
  "model": "seedance-2-5",
  "billing_status": "charged",
  "credits": 100,
  "failed_reason": null,
  "data": {
    "results": ["https://cdn.seevio.ai/.../x.mp4"],
    "video_expires_at": "2026-06-13T10:00:00Z",
    "last_frame_url": null,
    "processing_time": 48
  }
}

{
  "id": "3f2aK9mR...",
  "status": "failed",
  "created_at": 1781234567,
  "model": "seedance-2-5",
  "billing_status": "refunded",
  "credits": 100,
  "failed_reason": "provider_failed"
}

เมื่อมีการระบุ callback_url ระบบ Seedance จะส่งคำขอเรียกไปยังเอนด์พอยต์ของคุณทันทีที่งานสร้างวิดีโอเสร็จสิ้นหรือล้มเหลว โดยจะส่งข้อมูล JSON ที่อธิบายผลลัพธ์สุดท้ายไปให้ หากเอนด์พอยต์ของคุณตอบกลับด้วยรหัสที่ไม่ใช่ 2xx หรือไม่ตอบกลับภายใน 15 วินาที ระบบจะพยายามส่งข้อมูลใหม่อีกครั้งสูงสุด 5 ครั้ง การส่งข้อมูลใหม่จะใช้ task id เดิม ดังนั้นโปรดป้องกันการบันทึกข้อมูลซ้ำซ้อนโดยยึด id เป็นหลัก และกรุณาส่งรหัสตอบกลับ 200 ทันทีที่คุณได้บันทึกข้อมูลผลลัพธ์ดังกล่าวเข้าสู่ระบบของคุณเรียบร้อยแล้ว

{
  "id": "3f2aK9mR...",
  "status": "completed",
  "created_at": 1781234567,
  "model": "seedance-2-5",
  "data": {
    "results": ["https://cdn.seevio.ai/.../x.mp4"],
    "video_expires_at": "2026-06-13T10:00:00Z",
    "last_frame_url": null,
    "processing_time": 48
  }
}

{
  "id": "3f2aK9mR...",
  "status": "failed",
  "created_at": 1781234567,
  "model": "seedance-2-5",
  "data": {
    "failed_reason": "provider_failed",
    "credits_refunded": 100
  }
}

export async function POST(request: Request) {
  const callbackData = await request.json();

  if (callbackData.status === "completed") {
    const videoUrl = callbackData.data.results[0];
    // Save the video URL or update your own task record here.
  }

  if (callbackData.status === "failed") {
    const errorMessage = callbackData.data.failed_reason;
    // Mark your own task record as failed here.
  }

  return new Response(null, { status: 200 });
}

ระบบจะส่งโครงสร้างข้อผิดพลาดนี้กลับมาในคำขอ POST /v1/videos/generations และ GET /v1/tasks/:id เมื่อตัวคำขอ API เกิดความล้มเหลว เช่น พารามิเตอร์ไม่ถูกต้อง, คีย์ API ไม่ถูกต้อง, เครดิตไม่เพียงพอ, เกินโควตาการเรียกใช้งาน หรือไม่พบข้อมูลงาน ทั้งนี้ในบางกรณี ข้อผิดพลาดอาจมีข้อมูลฟิลด์พิเศษเพิ่มเติมอย่าง required, available หรือ retry_after แนบไปด้วย ขึ้นอยู่กับประเภทของปัญหาที่เกิดขึ้น

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits for this task.",
    "required": 100,
    "available": 12
  }
}

ระบบจะตรวจสอบและจำกัดอัตราการส่งคำขอสำหรับแต่ละคีย์ API ด้วยรูปแบบ Sliding Window โดยการส่งคำขอสร้างงานจะมีโควตาเริ่มต้นที่ 100 ครั้งต่อนาที ส่วนการส่งคำขอตรวจสอบสถานะงานจะมีความยืดหยุ่นและอนุญาตให้ส่งคำขอได้มากกว่า ทั้งนี้ ข้อมูลตอบกลับรหัส HTTP 429 จะมีส่วนหัวข้อความ Retry-After ระบุมาด้วย

ขั้นตอนการทำรายการเครดิตสำหรับ API จะเริ่มต้นด้วยการ 'สำรองเครดิต' เมื่อส่งคำขอ, 'ตัดยอดเครดิต' เมื่อทำงานสำเร็จ และ 'คืนเครดิต' เมื่อเกิดข้อผิดพลาด คุณสามารถเข้าดูประวัติการใช้เครดิตของ API, บันทึกประวัติการทำงาน และสถิติการใช้งานจำแนกตามช่วงเวลาได้ที่หน้าการใช้งานบนแดชบอร์ด