AI Platform 接入指南（简体中文）

协议约定

API 版本：v1
Content-Type：application/json
每个请求必须带：X-Client-App: <平台分配的应用代码>
客户端建议生成：X-Request-Id
时间使用 UTC ISO 8601。
ID 一律按字符串处理。
客户端根据稳定 error.code 分支，不解析 message。
X-Client-App 是应用级路由标识，不是用户鉴权；公共目录不得因为用户未登录而阻塞。
用户私有接口必须显式携带平台 Bearer，401 只刷新一次，绝不降级为匿名重试。

1. Atlas 换票

POST /api/v1/auth/exchange/atlas
X-Client-App: heyphoto
Content-Type: application/json

{
  "realm": "cn",
  "atlas_token": "<Atlas 登录 token>",
  "device_id": "<安装实例 ID>"
}

成功返回：

{
  "token_type": "Bearer",
  "access_token": "<15 分钟平台 token>",
  "expires_in": 900,
  "refresh_token": "<轮换 refresh token>",
  "refresh_expires_in": 2592000,
  "user_id": "<平台 UUID>",
  "realm": "cn",
  "data_home": "cn-east"
}

refresh token 只在安全存储中保存。刷新成功后必须立即覆盖旧 refresh token。

2. 刷新与退出

POST /api/v1/auth/refresh
X-Client-App: heyphoto

{"refresh_token":"..."}

POST /api/v1/auth/revoke
X-Client-App: heyphoto

{"refresh_token":"..."}

3. 查询可用 Workflow

GET /api/v1/workflows
X-Client-App: heyphoto

返回包含 workflow code、version、多语言名称、auth_mode 和 JSON Schema。客户端提交前可以按 Schema 组装参数，但服务端仍会再次校验。

该接口以及 /api/v1/features、/api/v1/features/{feature_code}/presets 属于公共只读目录，只要求 X-Client-App。它们不会返回用户、任务、素材、工单信息，也不会返回预设的服务端 Prompt 与完整渲染参数。

4. 提交异步任务

POST /api/v1/jobs
X-Client-App: heyphoto
Authorization: Bearer <platform access token>
Idempotency-Key: <本次用户操作的稳定 UUID>

{
  "workflow_code": "image.enhance",
  "workflow_version": 1,
  "input": {
    "asset_id": "...",
    "strength": 0.8
  }
}

立即返回 HTTP 202。网络重试必须复用相同 Idempotency-Key 和相同 body：

相同 key + 相同 body：返回同一个任务；
相同 key + 不同 body：返回 IDEMPOTENCY_CONFLICT。

5. 查询和取消

GET /api/v1/jobs/{job_id}
POST /api/v1/jobs/{job_id}/cancel

首期使用带退避的轮询：前 30 秒每 2 秒一次，之后逐步降至 5～10 秒；App 进入后台时停止高频轮询。后续可增加 SSE、Webhook 和 APNs/FCM，但任务查询接口始终是最终恢复入口。

状态：

状态	含义
`accepted`	已持久化，等待可靠分发
`queued`	已进入编排队列
`running`	Worker 正在执行
`waiting_external`	等待外部 GPU/供应商
`cancel_requested`	已请求取消，等待安全点
`succeeded`	成功
`failed`	失败，不再自动重试
`cancelled`	已取消
`expired`	超过任务生命周期

7. 统一错误

{
  "error": {
    "code": "AUTH_UPSTREAM_UNAVAILABLE",
    "message": "Atlas identity service is temporarily unavailable",
    "request_id": "...",
    "details": null
  }
}

客户端只根据稳定 code 选择本地化、面向用户的文案，不直接显示后端 message、节点名、 Provider、请求地址或“上传凭证”等实现细节。message/request_id/details 只进入按任务前缀可检索的诊断日志。功能入口先请求：

GET /api/v1/features/{feature_code}/availability
X-Client-App: heyphoto-cn

此接口是公开能力目录，不要求用户登录。available 可以进入；degraded 必须继续查看目标 workflow 的状态；unavailable 或目标 workflow 不可用时，App 使用“这个功能正在短暂休息，请稍后再试”一类产品文案，并在用户重新尝试时刷新。当前稳定原因码包括：

原因码	客户端语义
`MEDIA_SERVICE_UNAVAILABLE`	图片服务暂不可用，不开始上传
`PROCESSING_SERVICE_UNAVAILABLE`	异步处理服务暂不可用
`PROCESSING_CAPACITY_UNAVAILABLE`	目标 GPU/供应商能力当前不可用
`FEATURE_CONFIGURATION_UNAVAILABLE`	当前应用没有可执行的工作流版本
`FEATURE_UNDER_MAINTENANCE`	功能被平台整体关闭，入口显示维护中

所有上传和任务提交仍在服务端重新鉴权与校验；公开预检不赋予私有素材、历史或任务权限。

核心错误码：CLIENT_APP_UNKNOWN、AUTH_REQUIRED、AUTH_INVALID_TOKEN、AUTH_UPSTREAM_REJECTED、AUTH_UPSTREAM_REQUEST_INVALID、AUTH_UPSTREAM_UNAVAILABLE、WORKFLOW_NOT_FOUND、IDEMPOTENCY_CONFLICT、JOB_NOT_FOUND、JOB_NOT_CANCELLABLE、RATE_LIMITED、INTERNAL_ERROR。