Getting Started

这份指南面向接入 HPRT AI Platform 的 App 开发者。完成后，你的客户端能够使用已有 Atlas 登录态换取平台会话、直传图片、创建异步任务并取得处理结果。

接入前获取

平台管理员会分配：

X-Client-App 应用代码，例如 heyphoto；
国内或海外环境的 API Base URL；
当前应用可用的 Atlas realm；
测试账号和已开放的 AI 能力清单。

App 不保存平台供应商密钥、OSS 密钥或 Atlas appKey。它们只存在于后端。

API 鉴权分级

X-Client-App 用于识别接入应用、能力开关和灰度策略，不代表用户已登录。只有明确标为 “用户鉴权”的接口才允许携带并要求 Authorization: Bearer <platform access token>；客户端不能在公共目录请求前自动换票，也不能在用户接口 401 后自动降级为匿名。

分级	典型接口	访问要求
公共只读目录	`GET /features`、`GET /features/{code}/presets`、`GET /workflows`	只需 `X-Client-App`，未登录用户可访问
Workflow 策略	Job 创建、单条查询、交互、取消	按返回的 `auth_mode`；匿名模式还需稳定的 `X-Anonymous-Id`
用户私有数据	Asset、EditSession、Job 历史列表、工单日志上传	必须使用平台 Bearer；所有查询同时按应用和用户归属过滤
平台管理与运维	不属于客户端契约，不在本站展示	App 用户 token 无效

公共滤镜目录只返回展示需要的名称、描述、预览图、palette 与 tags。服务端 Prompt、负向 Prompt 和实际渲染参数不会通过匿名目录下发；任务只提交 preset_code + preset_version，由后端读取完整配方。

1. 使用 Atlas 登录态换票

用户在 App 中完成 Atlas 登录后，将登录 token 发送给平台：

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

{
  "realm": "cn",
  "atlas_token": "<Atlas 登录 token>",
  "device_id": "<本次安装的稳定随机 ID>"
}

成功后仅在系统安全存储中保存平台 access_token 和 refresh_token。后续需要身份的请求使用 Authorization: Bearer <access_token>，不要继续向 AI 接口发送 Atlas token。

2. 未登录查询当前可用能力

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

能力返回 interaction_mode、Workflow 版本和灰度比例。模板型能力再调用：

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

以上两个请求禁止附带用户 Bearer，也不应触发 Atlas 登录或换票；App 冷启动和退出登录后都能继续显示已开放能力与滤镜目录。

3. 申请图片上传地址

POST /api/v1/assets/uploads
X-Client-App: heyphoto
Authorization: Bearer <platform access token>
Content-Type: application/json

{
  "file_name": "portrait.jpg",
  "media_type": "image/jpeg",
  "size_bytes": 123456,
  "sha256": "<可选的 64 位十六进制 SHA-256>",
  "content_md5": "<可选的 Base64 MD5，推荐提供>"
}

按照响应中的 upload.method + upload.url + upload.headers 直接上传二进制图片；不要在 Job JSON 中传 Base64。OSS 返回 2xx 只表示传输完成，还必须调用 POST /api/v1/assets/{asset_id}/complete。平台会核对对象大小、类型和签名元数据并执行内容审核；只有返回 status=ready 后才能创建 EditSession。上传或确认失败时调用 DELETE /api/v1/assets/{asset_id}/upload，也可由后端维护任务超时清理。

4. 建立图片编辑主任务

一张图片上传成功后立即创建 EditSession。它代表用户对这张图片的一次编辑生命周期：

POST /api/v1/edit-sessions
X-Client-App: heyphoto
Authorization: Bearer <platform access token>
Idempotency-Key: <本次进入编辑器的稳定 UUID>
Content-Type: application/json

{
  "source_asset_id": "<上传响应的 asset_id>",
  "title": "portrait.jpg",
  "metadata": { "editor_entry": "ai_filter" }
}

同一编辑页面内的全部 AI 操作复用这个 edit_session_id 和原图；重新选图或退出后再次进入编辑器要创建新的 EditSession，即使本地文件相同。

5. 创建异步子操作

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

{
  "workflow_code": "image.filter.generate",
  "workflow_version": 1,
  "edit_session_id": "<第 4 步返回的 id>",
  "input": {
    "source": {
      "asset_id": "...",
      "url": "...",
      "media_type": "image/jpeg"
    },
    "preset_code": "illustration-pop"
  }
}

接口立即返回 202 和 Job。input.source.asset_id 必须与 EditSession 原图一致。网络重试必须复用相同 Idempotency-Key 和相同 Body。

6. 查询、交互和取消

GET /api/v1/jobs/{job_id}：查询状态和进度；
GET /api/v1/jobs/{job_id}/detail：查询 Step 和事件时间线；
GET /api/v1/edit-sessions/{edit_session_id}/detail：恢复整个图片编辑会话、当前结果和全部子操作；
POST /api/v1/jobs/{job_id}/cancel：请求取消；
POST /api/v1/jobs/{job_id}/actions：Job 为 waiting_input 时提交用户选择。
POST /api/v1/edit-sessions/{edit_session_id}/complete：退出编辑页或更换图片时结束主任务。

App 前台可以每 2 秒轮询一次；进入后台后停止高频轮询。无论推送或 SSE 是否接入， Job 查询接口始终是恢复任务状态的事实入口。

交互式功能会在同一个 Job 内暂停等待输入。例如光线重塑第一次使用 image.light.reshape，分析后返回 waiting_input + configure_lights；客户端把可编辑光源提交为 Action 后才进入渲染。用户再次调整光源时使用 image.light.render 新建轻量重绘 Job，并继续归入同一个 EditSession。

7. 联调完成标准

Atlas 换票成功，刷新 token 会轮换；
图片通过签名请求上传，不经过 API 进程中转；
同一编辑页面重复操作不重复上传原图，并归入同一个 EditSession；
重复提交不会创建两个 Job；
App 能展示排队、运行、等待输入、成功、失败和取消；
客户端日志保留 request_id、edit_session_id 和 job_id，不记录密码和服务端密钥；
401 只刷新一次，失败后回到登录流程，不无限重试。

字段、响应和错误结构以自动生成的 API Reference 为准；更完整的状态与错误说明见中文接入指南。

On this page