Appearance
接入检查清单
这份清单用于在接入 MoonApiX API 前后快速确认关键事项。建议在本地调试、灰度发布和正式上线前各检查一次。
准备阶段
| 项目 | 检查内容 |
|---|---|
| API Key | 已创建 MoonApiX API Key，并只在服务端保存。 |
| Base URL | 已按访问场景选择 MoonApiX API 域名；OpenAI-compatible 客户端已确认是否需要 /v1。 |
| 模型权限 | 已确认账号可用模型和能力。 |
| 余额额度 | 已确认账号余额、额度和任务限制。 |
| 回调地址 | 异步任务已准备 HTTPS 回调地址。 |
开发阶段
| 项目 | 检查内容 |
|---|---|
| 鉴权 | 所有请求都带 Authorization: Bearer <MOONAPIX_API_KEY>。 |
| 错误处理 | 已处理 400、401、402、403、429 和 5xx。 |
| 任务保存 | 异步任务提交后保存 task_id、模型名和业务订单 ID。 |
| 主动查询 | 已实现任务查询，避免只依赖回调。 |
| 幂等处理 | 回调接收端按 task_id 做幂等。 |
| 素材引用 | 已区分客户公网 URL、MoonApiX 托管 URL、模型素材 ID 和二进制文件直传。 |
| Trace | 已保存 MoonApiX 返回的 trace_id / request_id，方便排障。 |
上线前自测
- 调用
GET /v1/models，确认 API Key 可用。 - 用目标模型提交一个最小请求。
- 如果是异步任务，查询到成功状态并读取结果 URL。
- 模拟一次失败请求，确认错误码能被业务系统识别。
- 模拟重复回调，确认不会重复创建订单或重复发放结果。
- 检查日志，确认没有记录真实 API Key。
- 检查前端页面和客户端包，确认没有包含 API Key。
- 如果使用素材接口，确认
mode=oss或mode=asset符合目标模型能力；只有同时需要托管 URL 和Asset://asset_xxx时才使用mode=both。 - 如果使用不支持素材引用的模型，确认没有调用
mode=asset。
推荐记录字段
| 字段 | 说明 |
|---|---|
request_id | 业务系统请求 ID。 |
trace_id | MoonApiX 链路 ID。 |
task_id | MoonApiX 任务 ID。 |
model | 请求使用的模型。 |
status | 当前任务状态。 |
callback_url | 回调地址。 |
created_at | 任务创建时间。 |
completed_at | 任务完成时间。 |
result_url | 成功后的结果地址。 |
result_url_policy | 结果 URL 策略，例如直返、代理或转存。 |
error_code | 失败时的错误码。 |