ส่งซ้ำอย่างปลอดภัยด้วย Idempotency-Key
เฮดเดอร์ Idempotency-Key ทำให้การส่งซ้ำปลอดภัย คีย์เดิมกับเนื้อหาเดิมคิดเครดิตครั้งเดียวและได้ผลลัพธ์เดิม ทั้งการ replay กรณีขัดแย้ง และวิธีตั้งคีย์
Idempotency ทำให้การส่งซ้ำไม่ต่างจากการส่งครั้งแรก แนบเฮดเดอร์ Idempotency-Key แล้วคำขอที่เหมือนเดิมทุกประการจะถูกคิดเครดิตครั้งเดียว ไม่ว่าส่งกี่ครั้ง คีย์เป็นสตริงอะไรก็ได้ยาว 1 ถึง 200 ตัวอักษร ASCII ที่พิมพ์ได้ และแยกตามคีย์ API ของคุณ จึงไม่มีทางชนกับบัญชีอื่น
curl -X POST https://api.paxalabs.com/v1/tts \
-H "Authorization: Bearer $PAXA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-8146-confirmation" \
-d '{"text": "สวัสดีครับ ยินดีต้อนรับสู่ Paxa Labs", "voice": "khanomkrok", "model": "paxa-tts-flash-v2"}' \
--output speech.mp3// Reuse the same key when retrying the identical request: the charge
// happens once and the same audio is served again.
const idempotencyKey = `order-${order.id}-confirmation`;
const response = await fetch("https://api.paxalabs.com/v1/tts", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.PAXA_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": idempotencyKey,
},
body: JSON.stringify({ text: "สวัสดีครับ ยินดีต้อนรับสู่ Paxa Labs", voice: "khanomkrok", model: "paxa-tts-flash-v2" }),
});เอนด์พอยต์ที่รองรับ#
เอนด์พอยต์ HTTP ที่คิดค่าบริการทั้งเจ็ดตัวรับเฮดเดอร์นี้ คือ POST /v1/tts เอนด์พอยต์เสียงแบบ OpenAI POST /v1/translate POST /v1/ocr POST /v1/extract POST /v1/stt และเอนด์พอยต์ถอดเสียงแบบ OpenAI ส่วน WebSocket สด ไม่รับ เพราะคิดค่าบริการสะสมต่อการเชื่อมต่อ การเชื่อมต่อใหม่จึงเป็นรอบบิลใหม่ การใช้งานหลักคือคู่กับการสตรีม สตรีมที่หลุดแล้วส่งซ้ำด้วยคีย์เดิมจะ replay โดยไม่คิดเครดิตซ้ำ
การส่งซ้ำ#
คำขอแรกภายใต้คีย์หนึ่งบันทึกการคิดเครดิตไว้ การส่งซ้ำด้วยคีย์เดิมและเนื้อหาเดิมทุกประการ จะถูกตรวจกับบันทึกนั้นแล้วส่งผลลัพธ์ให้โดยไม่คิดเครดิตใหม่ เฮดเดอร์ x-credits-charged หรือ usage.credits ในเนื้อหาคำตอบสำหรับการถอดเสียง OCR การสกัดข้อมูล และการแปล รายงานเครดิตของคำขอเดิม ระบบยอมให้คำขอภายใต้คีย์เดียวกันทำงานทีละหนึ่งคำขอ คำขอซ้ำที่มาพร้อมกันตอบกลับเป็น 409 idempotency_in_flight
กรณีขัดแย้ง#
| การตอบกลับ | เกิดเมื่อ | วิธีแก้ |
|---|---|---|
| 409 idempotency_in_flight | คำขออื่นที่ใช้คีย์นี้กำลังทำงานอยู่ | รอให้เสร็จ แล้วส่งซ้ำเพื่อรับผลลัพธ์เดิม |
| 409 idempotency_refunded | คำขอเดิมล้มเหลวและคืนเครดิตแล้ว | ส่งใหม่ด้วย Idempotency-Key ใหม่ |
| 422 idempotency_mismatch | คีย์นี้เคยถูกใช้กับเนื้อหาอื่นแล้ว | ใช้คีย์เดิมซ้ำเฉพาะกับคำขอที่เหมือนเดิมทุกประการ |
ตั้งคีย์#
ตั้งคีย์จากรหัสที่มีอยู่แล้วในระบบของคุณ เช่น order-8146-confirmation หนึ่งคีย์แทนเสียงหนึ่งชิ้น หากต้องการสังเคราะห์เนื้อหาใหม่ ให้ใช้คีย์ใหม่
หมายเหตุ
หากไม่แนบเฮดเดอร์นี้ แต่ละคำขอจะถูกคิดเครดิตหนึ่งครั้งภายใต้รหัสภายในของตัวเอง ซึ่งผูกกับเฮดเดอร์ x-request-id สำหรับการติดต่อฝ่ายสนับสนุน