Seedream 5.0 Pro API

ความสามารถ

ราคาและเครดิต

ราคาระบุด้านล่างนี้คิดเป็นราคาต่อหนึ่งรูปภาพผลลัพธ์ที่ส่งกลับ การสร้างงานทั่วไปจะสำรองเครดิตสำหรับรูปภาพ 1 รูป ส่วนโหมดแยกเลเยอร์ภาพจะสำรองเครดิตสำหรับ 17 รูป และหักค่าบริการตามจำนวนรูปภาพที่ได้จริง (รวมถึงภาพฐานด้วย) และจะคืนเครดิตส่วนที่ไม่ได้ใช้กลับสู่ยอดคงเหลือเดิม สำหรับงานที่ล้มเหลวจะได้รับการคืนเงินเต็มจำนวน

ที่ความละเอียดเริ่มต้นแบบ 2K สำหรับการแยกเลเยอร์ภาพ ระบบจะสำรองเครดิตไว้ 136 เครดิต หากมีรูปภาพส่งกลับมาทั้งหมด 4 รูป ค่าบริการสุดท้ายที่ถูกหักคือ 32 เครดิต และจะได้รับเครดิตคืน 104 เครดิต

ระบบไม่รองรับคุณสมบัติ Idempotency ของคำขอ การส่งคำขอ POST ที่ถูกต้องแต่ละครั้งจะสร้างงานใหม่ที่มีค่าใช้จ่าย หากไม่แน่ใจผลลัพธ์ของการส่งข้อมูล ให้ตรวจสอบจาก taskId ที่ได้รับคืนมา การส่งคำขอ POST ซ้ำอาจทำให้เกิดการสร้างงานใหม่ซ้ำซ้อน

การยืนยันตัวตน

สร้างคีย์ API ได้ในแดชบอร์ด โดยระบบจะแสดงคีย์ตัวเต็มเพียงครั้งเดียวเท่านั้น โปรดเก็บรักษาไว้บนเซิร์ฟเวอร์ของคุณและส่งมาในรูปแบบ Bearer token ในทุกรีเควส

https://api.seevio.ai

Authorization: Bearer sk_live_your_api_key
Content-Type: application/json

ตั้งค่าตัวแปรสภาพแวดล้อม SEEVIO_API_KEY ก่อนรันตัวอย่างเหล่านี้ ตัวอย่าง JavaScript จะทำงานบนเซิร์ฟเวอร์ด้วย Node.js ส่วนตัวอย่าง Python จะใช้แพ็กเกจ requests

Request body

พารามิเตอร์อินพุต

การขอใช้งานแต่ละครั้งจะสร้างขึ้นหนึ่งงาน โดยระบบแปลงข้อความเป็นภาพ (Text-to-image) และแปลงภาพเป็นภาพ (Image-to-image) จะส่งคืนรูปภาพหนึ่งรูป ส่วนระบบแยกเลเยอร์ภาพ (layer-decomposition) จะส่งคืนรูปภาพ 1–17 รูป ซึ่งรวมถึงรูปภาพหลักด้วย ทั้งนี้ ห้ามส่งค่า aspect_ratio สำหรับการแยกเลเยอร์ภาพ

เริ่มต้นด่วน

ส่งรีเควสแบบย่อนี้ บันทึก taskId ที่ได้รับ จากนั้นใช้ตัวอย่างการสืบค้นสถานะงานด้านล่าง โดยค่าเครดิตที่แสดงในการตอบกลับเมื่อสร้างงานจะเป็นจำนวนเครดิตที่ถูกสำรองไว้

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedream-5-0-pro",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "text-to-image"
  }
}'

ตัวอย่างการตอบกลับเมื่อสร้างงาน

{
  "taskId": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "credits": 8
}

สร้างภาพจากข้อความ

สร้างรูปภาพ, แก้ไขรูปภาพอ้างอิง หรือแยกเลเยอร์รูปภาพด้วยคีย์ API ของ Seevio ของคุณ งานจะทำงานแบบไม่ซิงโครนัส (Asynchronous) โปรดบันทึก taskId และทำการตรวจสอบสถานะผ่านปลายทางเช็กสถานะงาน หรือรอรับข้อมูลผ่านการเรียกกลับ (Callback)

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedream-5-0-pro",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "text-to-image"
  }
}'

สร้างภาพจากภาพ

สำหรับการแก้ไขรูปภาพ ให้ตั้งค่า generation_type เป็น image-to-image และระบุ image_urls ส่วนพารามิเตอร์อื่นๆ ทั้งหมดให้ใช้ข้อกำหนดเดียวกัน

โปรดเปลี่ยน URL สื่อของ example.com ให้เป็นไฟล์ HTTPS สาธารณะของคุณเอง URL ตัวอย่างเหล่านี้มีไว้เพื่อแสดงโครงสร้างรีเควสเท่านั้น ไม่ใช่ไฟล์ตัวอย่างที่ดาวน์โหลดได้

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedream-5-0-pro",
  "input": {
    "prompt": "Change the teapot to matte sage green. Preserve its shape and the studio lighting.",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "image-to-image",
    "image_urls": [
      "https://example.com/teapot.png"
    ]
  }
}'

การแยกเลเยอร์ภาพ

กำหนด generation_type เป็น layer-decomposition และระบุ URL รูปภาพเพียงหนึ่งรายการเท่านั้น โดยไม่ต้องใส่ aspect_ratio ทั้งนี้ output_format จะควบคุมเฉพาะรูปแบบของรูปภาพหลัก เท่านั้น ส่วนเลเยอร์ที่แยกออกมาจะถูกส่งกลับเป็นไฟล์ PNG ที่คงค่าความโปร่งใสเสมอ โปรดบันทึกทุก URL ที่ส่งกลับมาใน data.results

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedream-5-0-pro",
  "input": {
    "generation_type": "layer-decomposition",
    "image_urls": [
      "https://example.com/teapot.png"
    ],
    "resolution": "2K",
    "output_format": "png"
  }
}'

โหมดแยกเลเยอร์ภาพสามารถส่งกลับ URL รูปภาพได้หลายรายการใน data.results ได้แก่ ภาพฐานและภาพเลเยอร์ย่อยที่ถูกแยกออก โดยแต่ละ URL จะชี้ไปยังรูปภาพแต่ละชิ้น จำนวนผลลัพธ์จะขึ้นอยู่กับงานนั้นๆ (รวมทั้งหมด 1–17 รูป) โปรดออกแบบระบบให้ประมวลผลอาร์เรย์ทั้งหมดแทนที่จะอ่านเฉพาะค่า data.results[0] ซึ่งทั้งการตอบกลับเมื่อสอบถามงานที่เสร็จสิ้นแล้วและ webhook แจ้งงานเสร็จสิ้นจะมีอาร์เรย์นี้ส่งไปให้ ส่วนการตอบกลับตอนสร้างงานเริ่มแรกจะมีเพียง taskId และเครดิตที่สำรองไว้เท่านั้น จะยังไม่มี URL ของรูปภาพส่งกลับไปให้

ตัวอย่างการตอบกลับเมื่อสร้างงาน

{
  "taskId": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "credits": 136
}

การแยกเลเยอร์ภาพเสร็จสมบูรณ์: ตัวอย่างกรณีได้ URL รูปภาพหลายรูป

ตัวอย่างการตอบกลับนี้แสดงรูปภาพผลลัพธ์ 4 รูป ได้แก่ ภาพฐานหนึ่งรูปและภาพเลเยอร์ย่อยสามรูป ซึ่งงานจริงของคุณอาจได้จำนวนรูปภาพแตกต่างไปจากนี้ ที่ระดับความละเอียด 2K ตามคำขอ ฟิลด์ credits จะแสดงค่าใช้จ่ายรวมสุดท้ายสำหรับรูปภาพทั้ง 4 รูปนี้ โดยเครดิตที่สำรองไว้ตอนแรกสำหรับ 17 รูปในส่วนที่เหลือได้ถูกคืนสู่ยอดคงเหลือแล้ว

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "seedream-5-0-pro",
  "credits": 32,
  "failed_code": null,
  "status": "completed",
  "billing_status": "charged",
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/images/example/base.png",
      "https://cdn.seevio.ai/api/images/example/layer-1.png",
      "https://cdn.seevio.ai/api/images/example/layer-2.png",
      "https://cdn.seevio.ai/api/images/example/layer-3.png"
    ],
    "image_expires_at": "2026-10-12T00:00:00.000Z",
    "processing_time": 12
  }
}

ประมวลผลรูปภาพที่ส่งกลับทั้งหมด

const response = await fetch(
  "https://api.seevio.ai/v1/tasks/TASK_ID",
  { headers: { Authorization: `Bearer ${process.env.SEEVIO_API_KEY}` } }
);
if (!response.ok) throw new Error(await response.text());
const task = await response.json();

if (task.status === "completed") {
  // Process every returned image, including the base image.
  // The number of URLs varies; do not read only results[0].
  for (const [index, imageUrl] of task.data.results.entries()) {
    console.log({ taskId: task.id, index, imageUrl });
    // Download or store this image in your application.
  }
} else if (task.status === "failed") {
  throw new Error(task.failed_reason || "Image generation failed.");
}
// If queued or generating, poll again after at least 5 seconds.

สืบค้นสถานะงาน

แทนที่ ID ตัวอย่างด้วย taskId ที่ได้จากการสร้างงาน การสืบค้นจะแสดงเฉพาะงานที่เป็นของผู้ใช้คีย์ API นั้นๆ เท่านั้น หากเข้าถึงไม่ได้หรือไม่พบ ID จะส่งคืน HTTP 404

ในเบื้องต้นแนะนำให้สืบค้นสถานะทุกๆ 10–20 วินาที หากพบ HTTP 429 ให้เว้นระยะเวลาเพิ่มขึ้น และหยุดสืบค้นเมื่อสถานะเป็น completed หรือ failed แนะนำให้ใช้เว็บฮุกสำหรับสภาพแวดล้อมจริง ตัวอย่างโค้ดด้านล่างนี้แต่ละชุดจะทำการสืบค้นเพียงหนึ่งครั้ง

curl --fail-with-body https://api.seevio.ai/v1/tasks/3f2aK9mR7xQp4TnZ8bLc6YwH \
  -H "Authorization: Bearer $SEEVIO_API_KEY"

อยู่ในคิว

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "seedream-5-0-pro",
  "credits": 8,
  "failed_code": null,
  "status": "queued",
  "billing_status": "reserved",
  "failed_reason": null,
  "data": {
    "results": [],
    "image_expires_at": null,
    "processing_time": null
  }
}

เสร็จสิ้น

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "seedream-5-0-pro",
  "credits": 8,
  "failed_code": null,
  "status": "completed",
  "billing_status": "charged",
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/images/example.png"
    ],
    "image_expires_at": "2026-10-12T00:00:00.000Z",
    "processing_time": 12
  }
}

ล้มเหลว

เมื่อสถานะที่ส่งกลับมาเป็น status=failed แสดงว่าการสร้างภาพไม่สำเร็จ ให้ดูสาเหตุที่ล้มเหลวได้ใน failed_reason และตรวจสอบผลการคืนเครดิตได้จาก billing_status สำหรับตัวอย่างนี้ refunded หมายถึงระบบได้คืนเครดิตให้แล้ว ส่วน credits จะยังคงแสดงจำนวนเดิมที่เคยสำรองไว้ และจะไม่มีการส่งกลับข้อมูลใน data

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "seedream-5-0-pro",
  "credits": 8,
  "failed_code": "400",
  "status": "failed",
  "billing_status": "refunded",
  "failed_reason": "The input or output was flagged as sensitive. Please try again with different inputs."
}

ลิงก์ผลลัพธ์จะสามารถใช้งานได้เป็นเวลา 30 วันหลังจากบันทึกข้อมูล เมื่อหมดอายุแล้ว ผลลัพธ์ในช่อง results จะว่างเปล่า

เว็บฮุก

ตั้งค่า callback_url ในรีเควสการสร้างงานเพื่อรับ JSON POST เมื่อสร้างงานสำเร็จหรือล้มเหลว ระบบปลายทางของคุณต้องส่งการตอบกลับ 2xx กลับมาภายใน 15 วินาที หากส่งไม่สำเร็จระบบจะพยายามส่งซ้ำ โปรดออกแบบระบบรับข้อมูลให้รองรับการทำงานแบบ Idempotent โดยตรวจสอบจาก ID ของงาน

ปลายทางคอลแบ็ก (Callback endpoint) ของคุณต้องรองรับคำขอแบบ POST ที่ส่งข้อมูลมาในรูปแบบ JSON (Content-Type: application/json)

สร้างงานพร้อมกำหนดคอลแบ็ก

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedream-5-0-pro",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "text-to-image"
  },
  "callback_url": "https://example.com/webhooks/seevio"
}'

การเรียกกลับ (Callbacks) จะใช้โครงสร้างการตอบกลับเหมือนกับการสอบถามข้อมูลงาน (task query) สำหรับการแจ้งเตือนกรณีที่ดำเนินการไม่สำเร็จและมีการคืนเครดิต จะมีฟิลด์ credits_refunded แสดงอยู่ในระดับบนสุดด้วย ให้ใช้ id ในการระบุงาน และใช้ status เพื่อแยกแยะระหว่างงานที่เสร็จสมบูรณ์กับงานที่ล้มเหลว ทั้งนี้ การแจ้งเตือนอาจเกิดขึ้นซ้ำได้ จึงควรประมวลผลแบบ Idempotent โดยอ้างอิงจาก id และ status การเรียกกลับจะไม่มีการลงลายมือชื่อดิจิทัล (Unsigned) ดังนั้นโปรดตรวจสอบความถูกต้องของงานผ่าน Endpoint สอบถามงานที่ต้องยืนยันตัวตน ทั้งนี้ หากการส่งข้อมูลเรียกกลับล้มเหลว จะไม่มีการคืนเครดิตสำหรับงานที่ดำเนินการสำเร็จแล้ว

งานเสร็จสิ้น: ข้อมูล Callback เมื่อทำรายการสำเร็จ

created_at คือเวลาสร้างเหตุการณ์ ส่วน task_created_at คือเวลาสร้างงาน ทั้งคู่เป็นวินาที Unix ตัวอย่างแสดงฟิลด์ที่แนะนำ โดยข้อมูลตอบกลับอาจมีฟิลด์เพิ่มเติม

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171212,
  "model": "seedream-5-0-pro",
  "credits": 8,
  "failed_code": null,
  "status": "completed",
  "billing_status": "charged",
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/images/example.png"
    ],
    "image_expires_at": "2026-10-12T00:00:00.000Z",
    "processing_time": 12
  },
  "task_created_at": 1789171200
}

งานล้มเหลว: ข้อมูล Callback เมื่อทำรายการไม่สำเร็จ

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171212,
  "model": "seedream-5-0-pro",
  "credits": 8,
  "failed_code": "400",
  "status": "failed",
  "billing_status": "refunded",
  "failed_reason": "The input or output was flagged as sensitive. Please try again with different inputs.",
  "task_created_at": 1789171200,
  "credits_refunded": 8
}

ตัวอย่างระบบรับข้อมูล

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

  if (callbackData.status === "completed") {
    const imageUrls = callbackData.data.results;
    // Save the image URLs and mark this task as completed in your application.
    console.log(callbackData.id, imageUrls);
  }

  if (callbackData.status === "failed") {
    const { failed_reason, credits_refunded } = callbackData;
    // Record the failure reason and refunded credits for this task.
    console.error(callbackData.id, failed_reason, credits_refunded);
  }

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

ตัวอย่างการใช้งาน Next.js นี้จะอ่านข้อมูล JSON จาก Callback และจัดการกับสถานะงานที่เสร็จสิ้นหรือล้มเหลวโดยตรง ทั้งนี้ ควรเพิ่มระบบจัดเก็บข้อมูล (Persistence) และระบบป้องกันงานซ้ำ (Task-ID deduplication) สำหรับแอปพลิเคชันของคุณ รวมถึงจัดคิวงานที่ใช้เวลาประมวลผลนานก่อนที่จะตอบรับ (Acknowledge) Callback

ข้อผิดพลาด

ข้อผิดพลาด HTTP จะมีออบเจ็กต์ error ซึ่งประกอบด้วย code และ message ทั้งนี้งานที่ระบบรับไปเรียบร้อยแล้วก็ยังอาจล้มเหลวในภายหลังได้ โปรดสืบค้นสถานะงานหรือจัดการผ่านคอลแบ็กความล้มเหลว

{
  "error": {
    "code": "invalid_request",
    "message": "input.prompt is required."
  }
}

ข้อผิดพลาดจะใช้รูปแบบ error.code และ error.message: 400 invalid_request, 401 invalid_api_key, 402 insufficient_credits, 403 forbidden, 404 not_found, 429 rate_limited, 500 internal_error โดยข้อผิดพลาด 402 insufficient_credits หมายถึงยอดเครดิตคงเหลือของคุณไม่เพียงพอสำหรับการส่งคำขอนี้

การจำกัดอัตราการส่งคำขอ

การสร้างงาน: คีย์ API แต่ละคีย์สามารถส่งคำขอได้สูงสุด 100 ครั้งต่อนาทีโดยค่าเริ่มต้น และในขณะนี้ยังไม่รองรับการกำหนดขีดจำกัดอัตราการส่งคำขอแบบกำหนดเอง

การสอบถามข้อมูลงาน: คีย์ API แต่ละคีย์สามารถส่งคำขอได้สูงสุด 120 ครั้งต่อนาทีโดยค่าเริ่มต้น โดยจะนับจำนวนคำขอสอบถามข้อมูลและคำขอสร้างงานแยกกัน

คำขอสร้างรูปภาพและวิดีโอจะใช้ขีดจำกัดอัตราการส่งคำขอ (Rate limit) ร่วมกันภายใต้ API key เดียวกัน

HTTP 429 จะมี Header Retry-After: 60 สำหรับการสร้างงาน และ Retry-After: 5 สำหรับการสืบค้นสถานะงาน โปรดใช้การเว้นระยะเวลาส่งคำขอ (Backoff) และหลีกเลี่ยงการสืบค้นบ่อยเกินความจำเป็น

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 60

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded."
  }
}