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

# 开发指南

> 异步调用、错误码与最佳实践

## 异步处理

<Steps>
  <Step title="提交任务">
    调用 `POST /v1/images` 或 `POST /v1/videos`，从 `data.task_id` 取得任务 ID。
  </Step>

  <Step title="轮询状态">
    用对应的 `GET .../{task_id}` 查询，直到 `status` 为终态。
  </Step>

  <Step title="获取结果">
    成功时读取 `data.result.image_url` 或 `data.result.video_url`；失败时查看 `data.error_message`。
  </Step>
</Steps>

建议轮询间隔 2–5 秒，并设置合理超时。

## 响应约定

成功时 `code` 为 `20000`，业务数据在 `data` 中。创建与查询接口返回同一套 `data` 结构。

### 常见 Code

| Code | 说明 | 处理建议 |
| - | - | - |
| 20000 | 成功 | — |
| 20002 | 参数错误 | 检查 `model`、时长、比例等约束 |
| 20001 | 鉴权失败 | 更换或重新创建 API Key |
| -1 | 服务器错误 | 稍后重试 |

## 最佳实践

1. **及时转存**：结果 URL 保存约 **3 天**，请尽快下载到自有存储。
2. **先查目录**：调用前用 [模型目录](/zh/api-reference/common/model-catalog) 确认可用 `model` 与单价。
3. **按 `cost` 对账**：创建/查询响应中的 `data.cost` 为实际扣费（积分）。
4. **妥善保管密钥**：勿写入前端公开仓库。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.