跳到主要内容

幂等

会启动工作的请求——带第一条消息的会话、一条消息、一次生成——可能在工作已经开始后才超时。盲目重试可能把工作启动两次，也被计费两次。Idempotency-Key 能让重试变得安全：

curl -s "$NEWEYES_API_BASE/v1/sessions/$SESSION_ID/messages" -X POST \
  -H "Authorization: Bearer $NEWEYES_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0b7c5f1e-2d1a-4c4e-9a53-6c1f0e8b9d21" \
  -d '{"text": "Summarize what we found."}'
  • 每件工作生成一个新的键（UUID 是不错的选择）；重试时发送同一个键和同一个请求。
  • 用已经用过的键重试，会返回第一次的答复，不会再启动新的工作。
  • 带这个键的第一次请求还在处理时到达的重试，会被拒绝，返回 409 idempotency_in_progress：按它的 Retry-After 响应头给出的秒数等待后，用同一个键重试同一个请求。
  • 同一个键配上不同的请求，会被拒绝，返回 409 idempotency_conflict。不要重试：新的请求要用新的键。
  • 键保留 24 小时。失败的请求可以带着它的键重试。
  • 键属于终端用户：两个用户即使用了同一个键也不会冲突。

API 参考注明了哪些接口接受这个请求头：创建会话、发送消息，以及发起图片、视频或音乐生成。

重试流式消息​

带 "stream": true 发送的消息，响应就是它的任务的事件流。答复以什么方式送达不属于请求本身：用同一个键重试——无论是否流式——返回的都是同一个任务；流式重试会从任务的第一帧重新发送。详见事件流。