任务与结果

用幂等键安全提交异步任务、上传媒体、轮询状态并下载结果。

提交任务（异步）

不提供同步调用。POST /api/v1/jobs 校验输入、从额度中预留价格并立即返回：新任务返回 202，幂等重试命中已有任务返回 200。

请求头	值	说明
`Authorization`	`Bearer <API key>`	也可以通过 x-api-key 发送密钥。
`Content-Type`	`application/json`
`Idempotency-Key`	`<unique string ≤128>`	必填。仅在重试完全相同的请求时复用。

字段	类型	必填	说明
`model`	`string`	必填	目录中的模型 slug。
`input`	`object`	必填	模型输入 schema 中的字段。
`expectedPriceMicros`	`integer`	可选	你向用户展示的价格。不一致时在扣费前返回 409 PRICE_CHANGED。

安全重试

网络失败后重试时，保持 Idempotency-Key 和请求体不变。修改输入时使用新密钥。相同密钥配不同输入会返回 409 IDEMPOTENCY_CONFLICT。

上传媒体

图像和视频字段接受公开 HTTPS URL 或 media:<uuid> 引用。本地文件请先上传：

POST /api/v1/media

curl -X POST https://api.hermes-ai.net/api/v1/media \
  -H "Authorization: Bearer $HERMES_API_KEY" \
  -H "Content-Type: image/png" \
  --data-binary @input.png
# → { "reference": "media:<uuid>", ... }  Use the reference in an image or video field.

获取任务结果

轮询 GET /api/v1/jobs/{id} 每隔几秒轮询一次，到达终态后停止。不要自动重提 reconciliation_required 状态的任务。

状态	终态	含义
`queued`	否	已接收，等待执行。
`submitting`	否	正在提交给模型提供方。
`running`	否	模型生成中。
`succeeded`	是	已完成，结果位于 assets。
`failed`	是	未产生结果，预留额度已释放。
`reconciliation_required`	是	结果正在核实。请保留任务 ID，不要自动重新提交。

字段	类型	说明
`id`	`string`	Hermes AI 任务 ID，用于轮询。
`model`	`string`	模型 slug。
`status`	`string`	参见任务状态。
`errorCode`	`string \| null`	任务失败或需要核对时设置。
`priceMicros`	`integer`	接收时锁定的报价，美元微单位。
`currency`	`"USD"`
`createdAt / updatedAt`	`string`	ISO 8601 时间戳。
`assets[]`	`array`	{ id, type, url?, text? }。url 为同源 /api/v1/results/<uuid> 链接。
`replayed`	`boolean`	仅提交时返回。幂等重试命中时为 true。

结果 assets 包含文本或同源 /api/v1/results/<uuid> 地址。使用相同凭据下载文件（需要 media:read）。GET /api/v1/jobs 列出最近 100 个任务。