冪等 - Blon

網路逾時後，你無法確定工作是否已建立。POST /jobs 帶上 Idempotency-Key header，就能安全地重送同一個請求。

curl https://api.blon.ai/v1/jobs \
  -H "Authorization: Bearer $BLON_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"model":"gpt-image-2","input":{"prompt":"A ceramic teapot on a linen table, soft morning light"},"webhook_url":"https://example.com/hooks/blon","metadata":{"order":"A-17"}}'

規則

鍵為 1–255 個可見 ASCII 字元，用 UUID 即可。
鍵以送出它的 API 金鑰為範圍。
同一把鍵、同一份內容：回原本的工作與 idempotency_hit: true，不論工作狀態。
同一把鍵、不同內容：409 idempotency_conflict。新的請求請換一把鍵。
逾時、標示可重試的 5xx 或 429 時，以同一把鍵重送。

POST /jobs 不強制帶這個 header，但建議一律帶上；啟動工作流時則為必填。 POST /estimate 會忽略此 header：估價不會建立任何東西。