API 文件 · 任務

冪等性

Idempotency-Key 的語意與重試方式。

建立任務時必須帶 Idempotency-Key 請求標頭，最長 128 字元（缺少或超長時回傳 400 invalid_request）。建議使用業務端的唯一 ID，例如訂單編號加上版本。

相同的鍵、相同的請求內容：回傳 202 與第一次建立的任務（目前狀態），並帶有回應標頭 Idempotent-Replayed: true，不會重複凍結或扣款。
相同的鍵、不同的請求內容：回傳 409 idempotency_conflict。
冪等鍵保留 30 天，以帳號為範圍：同一帳號下的不同 Key 共用同一個冪等空間。

遇到網路逾時、5xx 或 internal_error 時，以同一個鍵重試即可。若要重新生成（例如更換提示詞），請使用新的鍵。

Node.js

// 以業務端唯一 ID 作為冪等鍵：逾時重試不會重複建立任務
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 {
      // 網路錯誤：繼續使用同一個 key 重試
    }
    await new Promise((r) => setTimeout(r, 2 ** attempt * 1000 + Math.random() * 500));
  }
  throw new Error("submit failed");
}