跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.vmeg.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
为什么需要

超时或不确定的 5xx 后常会重试。若没有幂等键，服务端可能把每次重试当成新请求 — 产生重复任务、多扣积分或重复 Webhook。 X-Idempotency-Key 标识同一次业务提交。在同一 API Key 下，相同路径 + Key 在 TTL 内（默认 24 小时）只接受一次。相同意图的重试用同一个 Key；新任务用新 Key。
幂等防的是同一次提交的重复投递，不是禁止发起两次不同的任务。

​
怎么用

对 Open API 的每一个 POST 请求（/openapi/v1/**）都加上该请求头： 
X-Idempotency-Key: <unique-string>
规则：
  • 去空格后非空，最长 64 字符
  • 在第一次请求前生成 Key，并随本次尝试保存，便于安全重试
  • 不要用同一 Key 提交不同内容的请求 — 会返回 409 Conflict

​
Key 已被占用时

  • HTTP 409 Conflict
  • 响应头 Retry-After: 2
  • 响应体：code: 409，message 含 Idempotency key already used

​
安全重试 vs 新任务

场景Key
首次提交新的唯一 Key
超时后重试（相同意图）相同 Key
新任务或新写入新 Key

​
示例

export IDEM_KEY="job-$(date +%s)-$RANDOM"

curl -X POST "https://api.vmeg.ai/openapi/v1/task/tts/create" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Idempotency-Key: $IDEM_KEY" \
  -H "Content-Type: application/json" \
  -d @payload.json
若结果不确定，用同一个 Key 重试。不要在每次重试时换新 Key，否则可能重复写入。