Hướng dẫn Seedream 5.5 API: code Python, giá và kết quả thực tế

Để gọi Seedream 5.5 API, hãy gửi POST tới https://api.seedrouter.ai/v1/images/generations với "model": "seedream-5-5" và một prompt, giữ lại id tác vụ được trả về rồi truy vấn GET /v1/tasks/{id} cho đến khi trạng thái là completed. Tác vụ hoàn tất chứa URL ảnh. Cùng yêu cầu đó cũng chỉnh sửa với tối đa 10 ảnh tham chiếu, tạo PNG có nền trong suốt và tách một ảnh thành các lớp trong suốt.

ByteDance phát hành Seedream 5.5 ngày 9 tháng 11 năm 2026 với ba thay đổi chính: chỉnh sửa ổn định hơn qua nhiều lượt, đầu ra trong suốt ngay từ mô hình và ảnh chân thực hơn với chữ nhỏ rõ hơn.^[1] Chúng tôi chạy thử ba lần trên SeedRouter vào ngày hôm sau. Hướng dẫn này dựa trên các lần chạy đó: code đã gửi, kết quả trả về, thời gian và chi phí. Mọi trường đều được liệt kê trong tài liệu API Seedream 5.5, còn Playground nằm trên trang mô hình.

Cần chuẩn bị gì trước lần gọi Seedream 5.5 API đầu tiên?

Hai thứ: một khóa API và ID mô hình. Không có gì để tải xuống. ByteDance chưa phát hành trọng số Seedream 5.5, nên mô hình chạy trên máy chủ dịch vụ, còn code của bạn chỉ gửi JSON.

Tạo khóa trên trang khóa API và giữ nó trong biến môi trường trên máy chủ của bạn, đừng bao giờ đặt trong code chạy trên trình duyệt:

export SEEDROUTER_API_KEY="your-key"
pip install requests

ID mô hình là seedream-5-5. Một ID dùng cho tạo ảnh từ văn bản, chỉnh sửa và tách lớp; các trường yêu cầu quyết định thao tác được chạy. Tài khoản mới bắt đầu với số dư miễn phí nhỏ, đủ cho vài ảnh thử nghiệm 1K trước khi bạn nạp tiền.

Tạo ảnh bằng Python thế nào?

Lệnh gửi trả về ngay một tác vụ, không phải ảnh. Script này gửi prompt, truy vấn 10 giây một lần, dừng chờ sau 15 phút và lưu từng ảnh nhận được.

import os
import time
import requests

API = "https://api.seedrouter.ai/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"}


def submit(body):
    r = requests.post(f"{API}/images/generations", headers=HEADERS, json=body, timeout=60)
    r.raise_for_status()
    return r.json()["id"]


def wait(task_id, limit=900):
    deadline = time.time() + limit
    while time.time() < deadline:
        r = requests.get(f"{API}/tasks/{task_id}", headers=HEADERS, timeout=30)
        r.raise_for_status()
        task = r.json()
        if task["status"] in ("completed", "failed"):
            return task
        time.sleep(10)
    raise TimeoutError(f"{task_id} is still running; poll it again later")


task_id = submit({
    "model": "seedream-5-5",
    "prompt": "A ceramic teapot shaped like a sleeping fox on a linen tablecloth, "
              "soft morning window light, shallow depth of field. No text.",
    "size": "1K",
})
task = wait(task_id)
if task["status"] == "failed":
    raise RuntimeError(task["error"]["message"])

for i, image in enumerate(task["output"]["data"]):
    data = requests.get(image["url"], timeout=60).content
    with open(f"seedream-{i}.{image['output_format']}", "wb") as f:
        f.write(data)
    print(image["size"], image["url"])

Đó là lần chạy đầu tiên của chúng tôi. Tác vụ hoàn tất sau 47 giây và trả về một PNG 1248 × 832.

Có hai thói quen trong vòng lặp này cần giữ khi chạy thực tế. Nếu truy vấn hết thời gian chờ, giữ ID tác vụ và kiểm tra lại; ảnh có thể vẫn đang được tạo. Đừng gửi yêu cầu lần thứ hai để “thử lại”, vì như vậy sẽ tạo tác vụ thứ hai và bị tính phí lần thứ hai.

Những trường yêu cầu nào quan trọng?

Hầu hết yêu cầu chỉ cần model, prompt và size. Các trường bạn sẽ thiết lập thường xuyên nhất, kèm giá trị mặc định:

Đầu ra lớn nhất là 2K. Lần chỉnh sửa 16:9 ở 2K của chúng tôi trả về ảnh 2560 × 1440, còn kích thước pixel chính xác có thể đạt tổng cộng 4.624.220 pixel. Không có trường tỷ lệ khung hình: để cố định hình dạng, gửi kích thước pixel chính xác. Không có mức kích thước 3K hay 4K, nên nếu cần tệp lớn hơn, bạn phải phóng to sau đó. Tài liệu API liệt kê mọi trường. Các trường không được liệt kê trong đó bị loại bỏ thay vì khiến yêu cầu bị từ chối, nên seed, style hoặc n còn sót từ API ảnh khác không làm hỏng yêu cầu và cũng không có tác dụng gì. Một yêu cầu tạo một ảnh.

Chỉnh sửa ảnh bằng ảnh tham chiếu thế nào?

Đưa ảnh nguồn vào image và nêu trong prompt những gì cần đổi và cần giữ. Lần chạy thứ hai biến ảnh chụp người thợ sơn trên ban công vòng quanh ngọn hải đăng vào ngày nắng thành đêm đông:

task_id = submit({
    "model": "seedream-5-5",
    "prompt": "Turn this scene into a snowy winter night with warm light from "
              "the lighthouse windows, keep the composition",
    "image": "https://static.seedrouter.ai/media/landing/models/seedream-5-5/v1/lighthouse-source.webp",
    "size": "2560x1440",
})

Tác vụ mất 40 giây và trả về PNG 2560 × 1440. Người thợ sơn, tư thế, cọ, cuộn dây thừng, cả hai thùng sơn và lan can đều giữ nguyên vị trí. Ảnh được thêm tuyết rơi, tuyết trên sàn và vai người thợ, bầu trời tối cùng những ô cửa sáng phía trên dải sơn đỏ.

Khi có nhiều ảnh tham chiếu, hãy nhắc đến chúng theo thứ tự trong danh sách (“áo khoác trong ảnh 2”). Mọi ảnh tham chiếu đều được tính phí, kể cả ảnh đầu tiên, nên chỉ gửi ảnh cần cho việc chỉnh sửa.

Tuyên bố chính của ByteDance về phiên bản này là các vùng không chỉnh sửa giữ nguyên ở mức pixel qua các lần chỉnh sửa, đã thử qua 100 lượt liên tiếp.^[1] Qua API, chỉnh sửa nhiều lượt là một vòng lặp: lấy URL từ tác vụ hoàn tất rồi truyền vào image của yêu cầu tiếp theo. Chúng tôi chưa tự chạy chuỗi dài nên chưa thể xác nhận con số 100 lượt. Hãy nhớ mỗi lượt là một tác vụ mới và phải trả phí cho ảnh tham chiếu của lượt đó.

Làm sao lấy PNG trong suốt?

Đặt background thành transparent và giữ output_format là png. Có thể chỉ dùng prompt hoặc dùng cùng ảnh tham chiếu:

task_id = submit({
    "model": "seedream-5-5",
    "prompt": "A glossy red enamel pin shaped like a cherry, product cutout",
    "background": "transparent",
    "size": "1K",
})

transparent kết hợp với jpeg bị từ chối trước khi tác vụ được tạo vì JPEG không có kênh alpha. ByteDance mô tả đây là đầu ra RGBA trực tiếp từ mô hình với độ trong suốt toàn phần và một phần, các đường viền được dựng cẩn thận, nên không cần bước xóa nền riêng cho hình ảnh này.^[1]

Tách lớp ảnh qua API thế nào?

Gửi đúng một ảnh với layer_decomposition: true. Lần chạy thứ ba tách poster nhạc jazz, bật nhận dạng văn bản và giới hạn đầu ra tối đa bốn ảnh:

task_id = submit({
    "model": "seedream-5-5",
    "image": "https://static.seedrouter.ai/media/landing/models/seedream-5-5/v1/poster-source.webp",
    "layer_decomposition": True,
    "size": "1K",
    "layer_decomposition_options": {"max_images": 4, "text_recognition": True},
})

Tác vụ mất 39 giây và trả về bốn ảnh: ảnh nền và ba lớp trong suốt.

Hai lớp văn bản trả về kèm phần chữ đã được đọc. text_recognition của lớp tiêu đề chứa "BLUE TIDE\nSESSIONS", với phông chữ được đoán là HTF Didot và màu #122C4D, còn lớp dòng chú thích chứa "LIVE JAZZ · PIER 7 HALL · SATURDAY 9 PM". Mỗi dòng có hộp bao và kiểu trình bày riêng, nên bạn có thể gõ lại bằng phông chữ của mình tại cùng vị trí.

Có ba điều cần biết trước khi dựa vào kết quả:

• Tệp lớp lớn hơn hộp bao của chúng. Hệ số khác nhau cho từng lớp: 1,74× cho tiêu đề, 1,08× cho minh họa và 2,59× cho dòng chú thích. Thu nhỏ từng PNG về bounding_box.absolute của nó trước khi đặt, rồi xếp các lớp theo z_index tăng dần.
• max_images là giới hạn tối đa, và đặt thấp sẽ gộp các phần. Với bốn vị trí ảnh, mô hình đặt người chơi saxophone, sóng và mặt trời màu san hô vào một lớp. Hãy chừa đủ chỗ cho số thành phần dự kiến.
• Một thành phần có thể xuất hiện hai lần. Mặt trời màu san hô nằm trong lớp minh họa và cũng còn trên ảnh nền. Kiểm tra ảnh nền trước khi di chuyển một lớp.

Seedream 5.5 API giá bao nhiêu?

Bạn trả tiền mỗi ảnh theo kích thước riêng, cộng thêm mọi ảnh tham chiếu. Ảnh tối đa 2,61 triệu pixel (1K và 1.5K) thuộc bậc giá thấp; 2K và mọi kích thước lớn hơn thuộc bậc giá cao. Tách lớp tính phí ảnh nền và từng lớp theo kích thước riêng. Tác vụ thất bại không bị tính phí.

Ba lần chạy của chúng tôi ngày 10 tháng 11 năm 2026 và những gì được tính phí ở mỗi lần:

Nhân các đơn vị đó với giá trong bảng phía trên để tính số tiền. Cần chú ý lần tách lớp: chi phí là bốn ảnh chứ không phải một, vì ảnh nền và từng lớp đều được tính phí.

Trong lúc chạy, tách lớp tạm giữ số tiền lớn hơn khoản phí cuối cùng. Khi tiếp nhận tác vụ, số dư cần cho max_images ảnh được tạm giữ, là 30 ảnh nếu bỏ qua trường này, với auto tính theo bậc giá cao. Khi tác vụ hoàn tất, bạn bị tính phí số ảnh trả về và phần còn lại được giải phóng. Vì vậy, một lần tách không có max_images và không có size cần đủ số dư cho 30 ảnh bậc giá cao cộng ảnh đầu vào để bắt đầu, ngay cả khi chỉ trả về bốn ảnh. Đặt max_images gần với số phần bạn dự kiến và chọn một mức kích thước, như lần chạy thứ ba của chúng tôi (yêu cầu bốn ảnh, trả về bốn ảnh), thì số tiền tạm giữ sẽ gần với khoản phí.

Cần dự phòng những lỗi nào?

Ảnh tham chiếu phải là URL HTTP(S) công khai. Data URI base64 bị từ chối, nên hãy tải tệp lên kho lưu trữ của riêng bạn trước. Chấp nhận JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC và HEIF, mỗi tệp tối đa 30 MB. Danh sách mã đầy đủ nằm trong danh mục lỗi.

Câu hỏi thường gặp

Đã có Seedream 5.5 Pro chưa?

Chưa có. Bài công bố của ByteDance ghi "A Pro version of the Seedream 5.5 series will follow" (phiên bản Pro của dòng này sẽ ra mắt sau đó) và không nêu ngày.^[1] Hiện API có một mô hình, seedream-5-5. Mô hình Pro của thế hệ trước vẫn có sẵn dưới tên Seedream 5.0 Pro.

Seedream 5.5 API có miễn phí không?

Không. API tính phí mỗi ảnh từ số dư nạp trước, không có gói đăng ký. Số dư miễn phí ban đầu của tài khoản mới đủ cho vài ảnh 1K, nên bạn có thể chạy script phía trên trước khi nạp tiền.

Có thể tải Seedream 5.5 xuống không?

Không. ByteDance chưa công bố trọng số mô hình, nên không có tệp để chạy cục bộ. Bạn dùng mô hình qua một API như API này.

Có thể gửi bao nhiêu ảnh tham chiếu?

Tối đa 10 ảnh trong image. Tách lớp nhận đúng một ảnh.

Một yêu cầu mất bao lâu?

Ba lần chạy của chúng tôi mất từ 39 đến 47 giây. Tách lớp trả về nhiều lớp có thể mất vài phút, vì vậy script phía trên truy vấn tối đa 15 phút.

Nguồn tham khảo

1. ByteDance Seed. More Realistic Images, More Stable Editing Across 100 Rounds | Introducing Seedream 5.5. Ngày 9 tháng 11 năm 2026. Kiểm tra ngày 11 tháng 11 năm 2026 tại seed.bytedance.com.
2. SeedRouter. Tài liệu API Seedream 5.5. /docs/seedream-5-5.