Bỏ qua để đến nội dung
RouteAPI RouteAPI

ByteDance Seedream

Mô hình Seedream đang bán: seedream-5.0-pro và seedream-5.0-lite. Chúng được cung cấp bởi kênh Volcengine (Doubao) và gọi qua cùng các endpoint images tương thích OpenAI mô tả tại Định dạng hình ảnh OpenAI; trang này trình bày những gì adapter Volcengine thay đổi.

Mô hình Seedream có image-generation trong supported_endpoint_types — cách đọc trường này xem tại Mô hình.

Endpoint

Phần tiêu đề “Endpoint”
POST /v1/images/generations
POST /v1/images/edits

/v1/images/generations nhận body JSON. Chỉnh sửa ảnh sang ảnh dùng /v1/images/edits với ảnh nguồn truyền dưới dạng chuỗi trong image; RouteAPI chuyển cả hai tới endpoint tạo hình ảnh của upstream (trên kênh này Volcengine không cung cấp endpoint chỉnh sửa dạng form riêng).

Tham số yêu cầu

Phần tiêu đề “Tham số yêu cầu”
TrườngKiểuBắt buộcMô tả
modelstringCóseedream-5.0-pro hoặc seedream-5.0-lite
promptstringCóMô tả văn bản hoặc chỉ dẫn chỉnh sửa
sizestringKhôngKích thước hoặc bậc đầu ra. Được chuẩn hóa trước khi tới Volcengine (xem Chuẩn hóa kích thước)
imagestringKhôngẢnh nguồn cho ảnh sang ảnh, dạng URL http(s) hoặc chuỗi data:image/...;base64,.... Gửi trong body JSON
watermarkbooleanKhôngCó đóng dấu watermark lên đầu ra hay không; false tường minh vẫn được chuyển tiếp
sequential_image_generationstringKhông"auto" bật tạo nhiều ảnh; "disabled" tắt
sequential_image_generation_optionsobjectKhôngTùy chọn tạo tuần tự; {"max_images": <số nguyên>} đặt số lượng
layer_decompositionbooleanKhôngTách kết quả thành các lớp. Khi bật, cách tính phí của yêu cầu cũng thay đổi (xem Tính phí)
backgroundstringKhôngXử lý nền, ví dụ "transparent" hoặc "opaque"
toolsarrayKhôngCông cụ upstream như [{"type": "web_search"}]
optimize_prompt_optionsobjectKhôngTối ưu prompt, ví dụ {"mode": "standard"} hoặc {"mode": "fast"}

Các trường này thuộc cấu trúc yêu cầu hình ảnh của gateway và được chuyển tới Volcengine. Các trường tùy chọn bạn bỏ qua sẽ bị lược khỏi body upstream chứ không gửi null. Các trường JSON không nhận diện khác bị loại bỏ — hãy bật chuyển tiếp nguyên body trên kênh nếu cần trường mà gateway không mô hình hóa.

Chuẩn hóa kích thước

Phần tiêu đề “Chuẩn hóa kích thước”

Cách xử lý size phụ thuộc mô hình:

Mô hìnhXử lý size
seedream-5.0-proGiữ nguyên kích thước gốc: 1K, 1.5K, các giá trị pixel như 1024x1024 và các giá trị khác
seedream-5.0-liteKích thước dạng pixel được viết lại thành bậc 2K / 3K / 4K

Với các mô hình bị viết lại, cạnh dài quyết định bậc: chia cho 1024 rồi làm tròn tới số nguyên gần nhất (.5 làm tròn lên), sau đó kẹp vào khoảng 2K–4K. Bậc gửi trực tiếp như 2K hay 3k chỉ bị kẹp, còn giá trị không nhận diện được như auto được truyền tiếp để Volcengine kiểm tra. Ví dụ với seedream-5.0-lite:

size yêu cầuGửi tới upstream
1024x10242K
2048x20482K
1536x15362K
1440x25603K
3840x21604K
1K2K
5K4K
autoauto

Tạo hình ảnh

Phần tiêu đề “Tạo hình ảnh”
Terminal window
curl https://api.routeapi.ai/v1/images/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-pro",
    "prompt": "A misty mountain lake at sunrise, cinematic",
    "size": "2K"
  }'

Tạo tuần tự

Phần tiêu đề “Tạo tuần tự”
Terminal window
curl https://api.routeapi.ai/v1/images/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-lite",
    "prompt": "A series of four postcards from the same coastal town, consistent style",
    "sequential_image_generation": "auto",
    "sequential_image_generation_options": { "max_images": 4 }
  }'

Khi sequential_image_generation là "auto" và không có max_images, bước ước tính chi phí ban đầu sẽ tính theo 15 ảnh nếu mô hình có cấu hình giá cho đầu ra bổ sung.

Chỉnh sửa hình ảnh

Phần tiêu đề “Chỉnh sửa hình ảnh”

Gửi ảnh nguồn dưới dạng chuỗi trong body JSON. Gateway chuyển nguyên giá trị image tới Volcengine — có thể là URL http(s) hoặc chuỗi data:image/...;base64,.... Chuẩn hóa kích thước ở trên cũng áp dụng cho yêu cầu chỉnh sửa.

Terminal window
curl https://api.routeapi.ai/v1/images/edits \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-pro",
    "prompt": "Replace the background with a sunset beach, keep the subject unchanged",
    "image": "https://example.com/photo.png",
    "size": "2K"
  }'

layer_decomposition: true yêu cầu upstream tách kết quả thành các lớp riêng; background: "transparent" yêu cầu nền trong suốt. Cả hai được truyền nguyên.

Phản hồi

Phần tiêu đề “Phản hồi”

Đối tượng images của upstream được trả nguyên cho bạn. Các trường có thể phân tích gồm:

{
  "data": [
    {
      "url": "https://example.com/generated.png",
      "size": "2048x2048"
    }
  ],
  "usage": {
    "input_images": 1,
    "generated_images": 1,
    "output_tokens": 4096,
    "total_tokens": 4096
  }
}
  • Đọc hình ảnh từ data[].url. Mỗi phần tử có thể kèm size thực tế được giao, có thể khác bậc bạn đã yêu cầu.
  • usage.input_images và usage.generated_images được dùng để quyết toán khi mô hình tính phí theo ảnh; output_tokens dùng cho quyết toán theo token.

Tính phí

Phần tiêu đề “Tính phí”

Mô hình Seedream tính phí theo ảnh khi mô hình được cấu hình theo cách đó. Nếu trang chi tiết mô hình hiển thị các bậc kích thước, bậc được chọn theo số pixel của size bạn gửi, trước khi chọn kênh. Xem Giá mô hình và trang chi tiết mô hình để biết giá áp dụng.

Hai điểm riêng của Seedream:

  • Adapter viết lại size cho seedream-5.0-lite, nên ảnh được giao có thể rơi vào bậc khác với bậc đã tính phí. Để tránh sự lệch này, các mô hình tính phí theo bậc kích thước bị từ chối với 400 khi được định tuyến tới kênh Volcengine — chế độ chuyển tiếp nguyên body được miễn vì khi đó adapter không viết lại body.
  • layer_decomposition: true chuyển yêu cầu sang cấu hình giá tách lớp, khi mô hình có cấu hình này. Ảnh tham chiếu vượt hạn mức miễn phí và các đầu ra tuần tự cũng được tính phí; trang chi tiết mô hình liệt kê các con số áp dụng.

Lỗi và giới hạn

Phần tiêu đề “Lỗi và giới hạn”
Trạng tháiÝ nghĩaNguyên nhân thường gặp
400Yêu cầu không hợp lệThiếu model, n lớn hơn 128, dùng × làm dấu phân cách kích thước trong body JSON, hoặc mô hình tính phí theo bậc kích thước được định tuyến tới Volcengine
401Xác thực thất bạiAPI Key thiếu, không hợp lệ, hết hạn hoặc hết hạn mức
403Hết số dư hoặc hạn mứcinsufficient_user_quota hoặc pre_consume_token_quota_failed
429Bị giới hạn tần suấtGiảm số yêu cầu đồng thời
500Lỗi chuyển đổi hoặc nội bộKhông chuyển đổi được yêu cầu, hoặc upstream không trả hình ảnh

Lỗi từ upstream như size không được hỗ trợ hay prompt bị từ chối được trả về với mã trạng thái và thông điệp của upstream, kèm ID yêu cầu của RouteAPI.

Bước tiếp theo

Phần tiêu đề “Bước tiếp theo”