Lỗi của Seedance chia hai tầng: một tầng là yêu cầu HTTP thất bại, ví dụ 401, 403, 400, 429; tầng còn lại là yêu cầu thành công nhưng tác vụ cuối cùng failed hoặc expired. Chỉ nhìn giao diện gửi trả 200 rồi coi là thành công là chẩn đoán nhầm phổ biến nhất khi tích hợp API video. Thứ tự điều tra đúng là: xem mã trạng thái HTTP trước, sau đó xem trạng thái tác vụ và trường error, cuối cùng mới sửa prompt hoặc đổi mô hình.

Bài viết tách theo loại lỗi, nêu nguyên nhân, thứ tự xử lý và một đoạn mã xử lý lỗi có thể dùng lại. Đường dẫn giao diện, cách đặt tên trạng thái và quy tắc hạn mức có thể điều chỉnh theo phiên bản; thực tế căn cứ theo tài liệu trên trang và tài liệu chính thức.

Lưu ý: Seedance, Doubao và Volcano Engine là nhãn hiệu của ByteDance và các công ty liên kết. Bài viết chỉ nhằm mục đích kỹ thuật, không ngụ ý bất kỳ quan hệ liên kết hay bảo trợ nào. Đường dẫn và trường trong ví dụ chỉ để minh họa; hãy đối chiếu tài liệu trước khi gọi.

1. Phân biệt yêu cầu thất bại và tác vụ thất bại trước

Hiện tượng Tầng Nguyên nhân thường gặp Xử lý
401 HTTP Thiếu Key, sai định dạng, hết hiệu lực Sửa xác thực
403 HTTP Thiếu quyền, mô hình chưa kích hoạt, giới hạn khu vực Kiểm tra quyền và trạng thái kích hoạt
400 HTTP Tham số vượt khoảng, sai tên mô hình, tư liệu không truy cập được Đối chiếu tài liệu, sửa tham số
429 HTTP Bị giới hạn đồng thời, tốc độ hoặc hạn mức Lùi, giảm đồng thời
5xx HTTP Thượng nguồn quá tải hoặc sự cố tạm thời Lùi, đổi kênh
failed Tác vụ Kiểm duyệt từ chối, vấn đề tư liệu, tạo sinh bất thường Đọc error, sửa tư liệu
expired Tác vụ Quá hạn chưa hoàn thành hoặc chưa lấy kết quả Tạo lại tác vụ, kiểm tra thời hạn
Tải thất bại Kết quả URL hết hạn, xác thực, mạng Lấy lại hoặc chuyển lưu

Nhật ký tối thiểu ghi thời gian, mã trạng thái HTTP, mã lỗi, tên mô hình, task_id, mã đơn nghiệp vụ và thời gian xử lý. Không ghi toàn bộ Key, cũng không in nguyên URL kết quả có chữ ký.

2. 401 và 403: kiểm tra header và Key trước

401 nghĩa là danh tính chưa được xác minh, thường không liên quan năng lực mô hình hay số dư. Kiểm tra theo thứ tự:

  • Authorization có phải Bearer <key>; Volcano Ark dùng API Key làm Bearer Token.
  • Key có khoảng trắng, xuống dòng hoặc dấu ngoặc thừa không; biến môi trường có thực sự được nạp không.
  • Base URL và Key có thuộc cùng nền tảng, cùng khu vực không.
  • Key có bị xóa, luân chuyển, vô hiệu hóa, hoặc dự án thiếu quyền không.
  • Reverse proxy có ghi đè hoặc làm mất header Authorization không.

403 thiên về vấn đề quyền: mô hình chưa kích hoạt, tài khoản không có quyền với mô hình đó, giới hạn khu vực hoặc tuân thủ. 401 chỉ cần đổi Key mới làm yêu cầu tối thiểu là định vị nhanh; 403 phải kiểm tra trạng thái kích hoạt và quyền tài khoản trên bảng điều khiển, sửa mã thường không có tác dụng.

3. 429: giới hạn tốc độ, đồng thời và hạn mức

429 nghĩa là yêu cầu vượt giới hạn tốc độ, đồng thời hoặc hạn mức. Tình huống kích hoạt phổ biến:

  • Nhiều dịch vụ dùng chung một Key, chiếm dụng hạn mức lẫn nhau.
  • Tác vụ hàng loạt khởi động cùng lúc đúng giờ tròn, tạo xung lưu lượng.
  • Thử lại không lùi, càng thất bại càng gửi nhiều, tạo bão thử lại.
  • Tác vụ dài chiếm hết đồng thời, tác vụ ngắn cũng không chen vào được.

Nguyên tắc xử lý là lùi cấp số nhân kèm nhiễu ngẫu nhiên, giảm đồng thời, tách Key theo dự án, gửi lệch giờ. Đừng lặp thử lại khi không có lùi; tiếp tục gửi dồn dập trong thời gian 429 sẽ biến giới hạn tốc độ thành sự cố kéo dài. Khi nghiệp vụ thực sự cần đồng thời cao, xác nhận trần hạn mức trước và chuẩn bị kênh dự phòng.

4. 400: phần lớn là lỗi tham số

400 thường định vị trực tiếp được từ thông tin lỗi; tập trung đối chiếu:

  • Tên mô hình và phiên bản: sao chép từ tài liệu, đừng ghép hậu tố theo trí nhớ.
  • Thời lượng: các mô hình có khoảng khác nhau, ví dụ 2.5 là 4–30 giây, 2.0 là 4–15 giây, 1.0 là 2–12 giây.
  • Độ phân giải và tỷ lệ: xác nhận mô hình đó có hỗ trợ 4K, 21:9 hoặc adaptive không.
  • Số lượng tư liệu tham chiếu: 2.5 tối đa 30 ảnh, 10 video, 10 âm thanh; giới hạn của 2.0 thấp hơn.
  • URL ảnh hoặc video: phải để nền tảng truy cập được, không phải địa chỉ mạng nội bộ hoặc liên kết cần đăng nhập.
  • Tác vụ chỉnh sửa hoặc viết tiếp: một số chế độ chỉ cho phép thời lượng tự động, không điền số giây thủ công.
  • Đầu vào âm thanh: một số phiên bản không hỗ trợ đầu vào chỉ có âm thanh.

Cách tiết kiệm thời gian nhất là dùng phần thân yêu cầu mẫu trong tài liệu để tái hiện tối thiểu, rồi thêm lại từng tham số của mình. Mỗi lần thêm một mục, kiểm tra một lần, sẽ định vị được trường cụ thể.

5. Tác vụ failed và expired

Gửi thành công chỉ có nghĩa tác vụ đã vào hàng đợi. Kết quả truy vấn thường có các trạng thái queued, running, succeeded, failed, expired. Với failed phải xem trường error: kiểm duyệt nội dung từ chối, tư liệu đầu vào không hợp lệ, ảnh tham chiếu không đọc được, quá trình tạo sinh bất thường — cách xử lý hoàn toàn khác nhau.

expired thường gặp khi tác vụ vượt thời hạn thực thi mà chưa hoàn thành hoặc chưa lấy kết quả. Trong tài liệu, execution_expires_after có thể cấu hình, mặc định 48 giờ; ID tác vụ giữ 7 ngày. Sau thời hạn, tiếp tục hỏi trạng thái sẽ không hồi phục, chỉ có thể tạo lại tác vụ. Khi dùng callback còn phải chú ý: callback không xác nhận trong 5 giây sẽ bị thử lại 3 lần; giao diện callback phải idempotent.

Kiểm duyệt từ chối không nên đổi vài từ để lách lặp lại. Hãy xác nhận quyền tư liệu, chân dung người, yếu tố thương hiệu và chính sách nội dung trước, rồi mới quyết định gửi lại.

6. Quá thời gian và hỏi trạng thái

Quá thời gian chia ba lớp: quá thời gian kết nối máy khách, quá thời gian một lần truy vấn, và deadline tổng của tác vụ. Giao diện gửi thường trả task_id rất nhanh; phần tốn thời gian thực sự là xếp hàng và kết xuất. Đặt quá thời gian máy khách HTTP quá ngắn sẽ coi lần gửi bình thường là thất bại; quá dài lại giữ thread pool.

Hỏi trạng thái nên bắt đầu từ 5 giây, lùi dần đến 15–30 giây, và đặt deadline tổng. Khi hỗ trợ callback thì ưu tiên callback, hỏi trạng thái làm lớp dự phòng. Đừng gửi lại ngay sau quá thời gian; hãy dùng mã đơn nghiệp vụ hoặc khóa idempotent kiểm tra xem đã có tác vụ đang chạy chưa.

7. Tải kết quả thất bại

Tác vụ thành công không đồng nghĩa đã có tệp trong tay. video_url thường là địa chỉ tạm có chữ ký và thời hạn; lưu thẳng vào cơ sở dữ liệu, vài giờ sau mới tải thường gặp 403 hoặc 404. Cách xử lý:

  • Tải truyền phát ngay vào object storage của mình sau khi thành công.
  • Tải thất bại thì thử lại riêng, đừng tạo lại tác vụ tạo sinh.
  • Kiểm tra Content-Type, kích thước tệp và khả năng phát.
  • Không in toàn bộ URL có chữ ký trong nhật ký.

8. Ví dụ: xử lý lỗi kèm lùi và idempotent

Đoạn mã dưới đây tách riêng gửi, hỏi trạng thái và tải về, chỉ thử lại với lỗi tạm thời. Đường dẫn và trường căn cứ theo tài liệu trên trang.

import os, time, random, requests

BASE = os.environ["SEEDANCE_BASE_URL"].rstrip("/")
HEADERS = {
    "Authorization": f"Bearer {os.environ['SEEDANCE_API_KEY']}",
    "Content-Type": "application/json",
}

def submit(payload, max_retries=5):
    # Trước khi gọi, tra bảng tác vụ theo mã đơn nghiệp vụ; đã có task_id thì dùng lại
    for attempt in range(max_retries):
        try:
            r = requests.post(
                f"{BASE}/contents/generations/tasks",
                headers=HEADERS, json=payload, timeout=(5, 30),
            )
        except requests.Timeout:
            time.sleep(min(2 ** attempt, 20) + random.random())
            continue
        if r.status_code == 429 or r.status_code >= 500:
            time.sleep(min(2 ** attempt, 20) + random.random())
            continue
        if r.status_code >= 400:
            raise RuntimeError(f"{r.status_code}: {r.text[:500]}")
        return r.json()["id"]
    raise RuntimeError("submit retries exhausted")

def wait(task_id, deadline_seconds=900):
    deadline = time.time() + deadline_seconds
    delay = 5
    while time.time() < deadline:
        r = requests.get(
            f"{BASE}/contents/generations/tasks/{task_id}",
            headers=HEADERS, timeout=(5, 30),
        )
        if r.status_code == 429 or r.status_code >= 500:
            time.sleep(delay)
            delay = min(delay * 1.5, 30)
            continue
        r.raise_for_status()
        data = r.json()
        if data["status"] == "succeeded":
            return data["content"]["video_url"]
        if data["status"] in ("failed", "expired"):
            raise RuntimeError(f"{data['status']}: {data.get('error')}")
        time.sleep(delay)
        delay = min(delay * 1.5, 30)
    raise TimeoutError(task_id)

def download(url, path):
    with requests.get(url, stream=True, timeout=(5, 120)) as r:
        r.raise_for_status()
        with open(path, "wb") as f:
            for chunk in r.iter_content(1024 * 256):
                f.write(chunk)

Đoạn mã cố ý không thử lại 400, 401, 403. Lỗi tham số và lỗi xác thực dù thử lại bao nhiêu lần cũng không thành công, chỉ làm nhật ký và chi phí phình to.

9. Thử lại, idempotent và danh sách hỗ trợ

Thử lại chỉ phù hợp lỗi tạm thời: 429, 5xx, quá thời gian kết nối. 400, 401, 403 và kiểm duyệt từ chối không nên tự động thử lại. Chìa khóa của idempotent không phải số lần thử lại mà là mã đơn nghiệp vụ: tra bảng tác vụ trước khi gửi, lưu task_id sau khi gửi, yêu cầu lặp dùng lại tác vụ đã có.

Trước khi liên hệ bên cung cấp dịch vụ, sắp xếp thông tin theo danh sách:

  1. Ghi thời điểm xảy ra, mã trạng thái HTTP, mã lỗi và thông tin lỗi đầy đủ, chú ý khử nhận dạng.
  2. Ghi tên mô hình, thời lượng, độ phân giải, tỷ lệ và số lượng tư liệu tham chiếu.
  3. Ghi task_id, mã đơn nghiệp vụ, số lần gửi và số lần hỏi trạng thái.
  4. Giữ một yêu cầu tái hiện tối thiểu, đã bỏ quyền riêng tư người dùng và khóa.
  5. Phân biệt yêu cầu thất bại với tác vụ failed hoặc expired.
  6. Kiểm tra URL tư liệu có truy cập công khai được không, phản hồi có quá chậm không.
  7. Xác nhận hạn mức, đồng thời và quyền tài khoản, loại trừ 429 và 403.
  8. Kèm request ID và thời điểm tái hiện, rồi mới gửi điều tra.

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

Giao diện gửi trả 200, vì sao tác vụ vẫn thất bại?

200 chỉ có nghĩa tạo tác vụ thành công. Tạo video là bất đồng bộ; trạng thái cuối phải xem status và trường error trong kết quả truy vấn.

429 có phải do số dư không đủ không?

Không nhất thiết. 429 thường nghĩa là bị giới hạn tốc độ, đồng thời hoặc hạn mức; vấn đề số dư có thể trả lỗi khác. Kiểm tra đồng thời, Key dùng chung và chiến lược thử lại trước.

Tác vụ failed có thử lại trực tiếp được không?

Đọc error trước. Kiểm duyệt từ chối và tư liệu không hợp lệ, gửi lại nguyên trạng thường vẫn thất bại; lỗi mạng hoặc thượng nguồn có thể lùi rồi thử lại. Trước khi thử lại, dùng mã đơn nghiệp vụ kiểm tra idempotent.

Hỏi trạng thái bao lâu một lần là hợp lý?

Bắt đầu từ 5 giây, lùi dần đến 15–30 giây, đặt tổng thời gian chờ. Khi hỗ trợ callback thì ưu tiên callback, hỏi trạng thái làm lớp dự phòng.

URL kết quả không mở được thì làm sao?

Phần lớn là hết thời hạn hoặc chữ ký mất hiệu lực. Sau khi thành công nên chuyển ngay vào object storage; nếu đã hết hạn thì truy vấn lại tác vụ hoặc tạo lại tác vụ, đừng liên tục gọi liên kết cũ.

Bước tiếp theo

Trước hết tạo Key kiểm thử tại ZSQH AI Gateway, diễn tập lần lượt 401, 429, lỗi tham số và tác vụ thất bại, xác nhận cảnh báo và chiến lược thử lại có hiệu lực. Mô hình khả dụng và cách tính phí căn cứ theo giá mô hình.

Bài viết liên quan: