Tài liệu API · Tác vụ

Tính lũy đẳng

Ý nghĩa của Idempotency-Key và cách thử lại an toàn.

Yêu cầu tạo tác vụ bắt buộc có header Idempotency-Key, dài tối đa 128 ký tự (nếu thiếu hoặc quá dài sẽ nhận 400 invalid_request). Nên dùng ID duy nhất từ hệ thống nghiệp vụ của bạn, ví dụ mã đơn hàng kèm số phiên bản.

Cùng khóa, cùng nội dung yêu cầu: trả về 202 cùng tác vụ đã tạo lần đầu (trạng thái hiện tại), kèm header phản hồi Idempotent-Replayed: true; không tạm giữ hay trừ phí thêm lần nào.
Cùng khóa, khác nội dung yêu cầu: trả về 409 idempotency_conflict.
Khóa lũy đẳng được giữ 30 ngày và tách biệt theo tài khoản: các Key khác nhau trong cùng một tài khoản dùng chung một không gian lũy đẳng.

Khi gặp lỗi hết thời gian chờ, 5xx hoặc internal_error, chỉ cần thử lại với cùng một khóa. Nếu muốn tạo lại (ví dụ đổi prompt), hãy dùng khóa mới.

Node.js

// Dùng ID nghiệp vụ duy nhất làm khóa lũy đẳng: thử lại sau khi hết thời gian chờ sẽ không tạo trùng tác vụ
async function submit(order) {
  const key = `order-${order.id}-v${order.revision}`;
  for (let attempt = 0; attempt < 5; attempt++) {
    try {
      const res = await fetch("https://cn-api.aitoken.tools/v1/videos/generations", {
        method: "POST",
        headers: {
          Authorization: `Bearer ${process.env.AITOKEN_API_KEY}`,
          "Idempotency-Key": key,
          "Content-Type": "application/json",
        },
        body: JSON.stringify(order.payload),
      });
      if (res.status < 500 && res.status !== 429) return res.json();
    } catch {
      // Lỗi mạng: tiếp tục thử lại với cùng key
    }
    await new Promise((r) => setTimeout(r, 2 ** attempt * 1000 + Math.random() * 500));
  }
  throw new Error("submit failed");
}