> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yir.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 生产集成

> 使用幂等提交、有界轮询、安全重试和明确失败处理构建可靠的 Yir 客户端。

<Info>
  本指南只描述当前开发者预览合同：GPT Image 2 文生图的 KIE 兼容与 APIMart 兼容入口。
</Info>

<CardGroup cols={3}>
  <Card title="保护密钥" icon="key-round" href="/zh/getting-started/authentication">
    Yir API Key 只保存在服务端，并且只作为 Bearer Credential 发送。
  </Card>

  <Card title="跟踪逻辑请求" icon="fingerprint" href="#提交合同">
    在开始轮询前持久化幂等键和任务 ID。
  </Card>

  <Card title="处理未知结果" icon="refresh-cw" href="#轮询与恢复">
    重试查询，不要把超时变成第二次生成请求。
  </Card>
</CardGroup>

## 提交合同

<Steps>
  <Step title="生成幂等键">为一个逻辑生成请求生成一个不透明值。</Step>
  <Step title="提交请求">选择已有集成熟悉的 KIE 或 APIMart 兼容格式。</Step>
  <Step title="保存任务 ID">先将任务 ID 写入本地业务记录，再启动后台轮询。</Step>
  <Step title="查询到终态">使用有界轮询；临时网络错误后继续查询同一个任务。</Step>
</Steps>

<Warning>
  提交响应超时后不要直接生成新的幂等键。原请求可能已经被接受，并可能产生费用事实。
</Warning>

<ParamField header="Authorization" type="string" required>
  使用 `Bearer $YIR_API_KEY` 格式的 Yir Credential。
</ParamField>

<ParamField header="Idempotency-Key" type="string" required>
  调用方为逻辑请求生成的不透明标识。相同键配合不同请求数据会被拒绝。
</ParamField>

## 两种兼容入口

<Tabs>
  <Tab title="KIE 兼容">
    使用 `createTask` 提交，读取 `data.taskId`，然后通过 `recordInfo` 查询。
  </Tab>

  <Tab title="APIMart 兼容">
    使用 `images/generations` 提交，读取 `data[0].task_id`，然后通过任务路径查询。
  </Tab>
</Tabs>

## 轮询与恢复

| 情况     | 安全处理方式             |
| ------ | ------------------ |
| 返回活动状态 | 等待后继续查询相同任务 ID。    |
| 查询请求超时 | 将结果视为未知，并重试查询。     |
| 提交响应超时 | 使用相同幂等键和完全相同的数据重试。 |
| 返回终态失败 | 停止轮询，处理稳定的公开错误。    |
| 返回终态成功 | 在结果保留期结束前保存结果。     |

<AccordionGroup>
  <Accordion title="应该多快轮询？">
    从保守间隔开始，加入抖动，并在应用侧设置总期限。轮询超时不是任务失败事实。
  </Accordion>

  <Accordion title="任务变慢时要不要重新提交？">
    不要。继续查询现有任务 ID。除非是相同数据和相同幂等键的重试，否则会成为第二个逻辑请求。
  </Accordion>

  <Accordion title="支持工单可以提供什么？">
    可以提供任务 ID、来源路径、大致 UTC 时间、HTTP 状态、公开错误码和安全的 Key 前缀；不要提供完整 Key、Prompt、原始素材或 Provider 响应。
  </Accordion>
</AccordionGroup>

<Check>
  当你的实现能够保存两个标识、正确重试提交、持续查询同一任务，并且不会向浏览器暴露 API Key 时，就可以进行受控测试。
</Check>