星途绘梦 Agent API 完整使用指南

本指南供 AI Agent 通过 REST API 独立完成「找项目 → 建卡片 → 传参考图 → 出图 → 查历史 → 下载原图」的整套漫画/条漫制作流程，无需操作浏览器。

0. 核心规则（必须遵守）

1. 认证：所有 /api/agent/* 接口必须带请求头 Authorization: Bearer <AGENT_API_KEY>；否则返回 401。
2. 密钥获取：用户在网页 /agent 点「＋ 添加密钥」生成，绑定到该用户的注册邮箱；Agent 侧只需要拿到密钥字符串。密钥可被用户停用/重新启用/解绑——停用或解绑后，Agent 再用该密钥调用会立即收到 401。
3. 出图提示词硬约束：prompt 必须是无文字、无气泡、无对话框、无旁白框、无拟声字、无水印的画面描述；文字/气泡一律在本地后期排版。
4. 画幅必须显式指定：size 不传默认是 1:1，不是 9:16。竖屏条漫请每次都传 size=9:16。
5. 状态以生图历史为准：卡片按钮/前端提示可能滞后或误报；判断是否成功生图，必须查 GET /api/agent/assets/:assetId/history。
6. 原图必须校验：下载后必须用 PNG 文件头、真实 MIME、像素尺寸核验。2K 竖屏（9:16）最终原图应为 1152×2048 PNG。禁止用缩略图/WebP 预览冒充原图。
7. 卡片按 asset_id 定位：绝不按列表索引操作卡片。新增卡片用新的 asset_id，绝不覆盖已有卡。
8. 积分消耗：每次出图完成会扣积分；任务完成响应和 /api/agent/credits 都能查到余额与消耗。

1. 前置信息

Base URL：生产 https://xingtuhuimeng.cn；本地开发 http://localhost:3002。

关键概念：

概念	含义	怎么拿
AGENT_API_KEY	Agent 密钥	用户在 /agent 页面添加
project_id	项目ID	GET /api/agent/projects
asset_id	资产卡片编号（项目内唯一）	GET /api/agent/assets?project_id=... 的 asset_id 字段；新建卡时自己命名
asset_type	卡片类型	character（角色）/ item（道具）/ scene（场景/分镜）
task_id	生图任务ID	POST .../generate 的响应
storageKey	对象存储键（原图地址）	生图历史接口返回

通用请求头：

Authorization: Bearer <AGENT_API_KEY>
Content-Type: application/json      # JSON 接口
Content-Type: multipart/form-data   # 上传/出图接口

2. 接口速查表

#	方法	路径	用途
1	GET	/api/agent/me	认证自检 + 用户信息 + 积分余额
2	GET	/api/agent/credits	积分余量 / 每日限额 / 消耗明细
3	GET	/api/agent/projects	项目列表
4	POST	/api/agent/projects	创建项目
5	GET	/api/agent/script	查询已有剧本（按 project_id）
6	POST	/api/agent/script	导入剧本（正文/资产，按 project_id upsert）
7	GET	/api/agent/assets	资产卡片列表（含历史摘要/参考图数量）
8	POST	/api/agent/assets	创建/更新资产卡片（按 asset_id 隔离）
9	PUT	/api/agent/assets/:assetId	更新卡片名称/集数/描述
10	GET	/api/agent/assets/:assetId/references	查询参考图（返回该卡全部参考图）
11	POST	/api/agent/assets/:assetId/references	上传参考图（multipart，响应返回该卡全部参考图）
12	DELETE	/api/agent/assets/:assetId/references	删除参考图（?id=单张 / ?all=true 全部删除，响应返回剩余参考图）
13	POST	/api/agent/assets/:assetId/generate	提交生图任务（gpt-image2 / banana-2 / banana-pro）
14	GET	/api/agent/tasks/:taskId	轮询任务状态
15	POST	/api/agent/assets/:assetId/generate/cancel	取消任务
16	GET	/api/agent/assets/:assetId/history	生图历史（权威状态来源）
17	GET	/api/agent/download	按 storageKey 获取原图下载直链

3. 端到端标准流程（一步步照着做）

流程 A：开始前的自检

1. GET /api/agent/me
   ├─ 401 → 密钥失效，停止并提示用户重新添加密钥
   └─ 200 → 记录 credits.credits（余额）
2. GET /api/agent/credits?transactions=true&type=consume
   → 了解近期消耗，确认额度足够

流程 B：找到或创建项目

1. GET /api/agent/projects
2. 若存在目标项目 → 记录其 id 为 PROJECT_ID
3. 若不存在 → POST /api/agent/projects  { "name": "项目名" } → 取 project.id

流程 C：导入 / 查询已有剧本

1. GET /api/agent/script?project_id=PROJECT_ID
   ├─ data 存在 → 读取 original_script_content（剧本正文）、storyboard_result（分镜结果）、script_progress_step（进度）
   │              （返回不含资产卡片数据，资产走 /api/agent/assets）
   └─ data null → 该项目暂无剧本
2. 查看不同剧本记录（每次生成的剧本会保存为一条记录）：
   GET /api/agent/script?project_id=PROJECT_ID&records=true
   → records[] 为剧本记录列表（含 content，按创建时间倒序）
   GET /api/agent/script?project_id=PROJECT_ID&record_id=<RECORD_ID>
   → records 仅含该条记录，直接读取其 content 即为该版本剧本文本
3. 需要导入剧本时：
   POST /api/agent/script
   {
     "project_id": PROJECT_ID,
     "project_name": "《...》第一话",
     "original_script_content": "第一幕……"
   }
   → 只写入显式传入的字段，未传字段保留项目原值，不会误清空
   → 导入成功会自动写入剧本记录（script_records），前端「剧本列表」立即显示；
     可选 name 字段指定记录名（默认取 project_name）；与最近一条记录内容相同时不会重复插入

流程 D：创建资产卡片（角色/场景/分镜）

POST /api/agent/assets
{
  "project_id": PROJECT_ID,
  "asset_id": "P01",          ← 自行命名，项目内唯一
  "asset_type": "scene",      ← character/item/scene
  "name": "P01-分镜标题"
}

关键：每张新画面都用新的 asset_id。若该编号已存在且 historyCount>0，不要覆盖，换新编号或直接用已有卡。

流程 E：上传参考图（人物定妆等）

POST /api/agent/assets/<asset_id>/references   (multipart)
  字段: projectId, files[]（可多张）
  :asset_id 必须用资产卡片的 asset_id（创建卡片响应里的 assetId），
          不要用资产列表返回的卡片记录 id（UUID）；误传记录 id 会自动映射
→ 响应同时返回该卡片当前全部参考图（references[]，含 id/storageKey/url/originalName/…），
  可据此同步参考组件状态；删除参考图用 DELETE 同路径
  （单张: ?id=<referenceId>&projectId= ；全部清空: ?all=true&projectId= ）

流程 F：出图（完整一步步）

步骤1：检查积分  GET /api/agent/me → 余额足够才继续

步骤2：提交生图  POST /api/agent/assets/<asset_id>/generate   (multipart)
  字段: projectId, assetType, assetName, prompt(无字无气泡无水印),
        size=9:16, resolution=2k,
        images=<参考图URL...>, imageStorageKeys=<storageKey...>
   → 得到 taskId

步骤3：轮询（3 秒间隔，最多 20 分钟）
  循环 GET /api/agent/tasks/<taskId>
  ├─ processing → 等 3s 继续
  ├─ completed  → 记录 storageKey、creditsUsed、remainingCredits → 步骤4
  ├─ failed     → 步骤5
  └─ cancelled  → 结束

步骤4：下载并校验原图
  GET /api/agent/download?key=<storageKey>&filename=<asset_id>.png → 下载 url
  → 校验：PNG 文件头 + 可解码 + 1152×2048（2K 9:16）
  → 通过才保存为正片；不通过不得当作成图

步骤5：失败处理
  GET /api/agent/assets/<asset_id>/history?projectId=PROJECT_ID
  ├─ 历史已有 success 记录 → 以历史为准，直接下载，不重试
  └─ 历史为空/无图 → 检查积分后重试（最多再试1次，仍失败则标记阻塞并记录）

流程 G：核验某卡是否已成功（避免重复出图）

GET /api/agent/assets/<asset_id>/history?projectId=PROJECT_ID
最近一条 status=success 且 storageKey 非空 → 已成功，跳过出图

流程 H：取消进行中的任务

POST /api/agent/assets/<asset_id>/generate/cancel  { "taskId": "<taskId>" }

4. 各接口参数明细

4.1 提交生图（核心）

POST /api/agent/assets/:assetId/generate    (multipart/form-data)

字段	必填	说明
projectId	是	项目ID
assetType	是	character / item / scene
prompt	是	出图提示词（无文字无气泡无水印）
assetName	否	卡片名（建议填 asset_id）
size / aspectRatio	建议	画幅：9:16/3:4/16:9/1:1/4:5/21:9/1:4/4:1 等；竖屏条漫传 9:16。两个字段等价，按模型自动映射
resolution	建议	2k / 1k（各模型所有分辨率均可，原样透传）
images / imageUrls	否	参考图 URL（可多个，两种命名均兼容）
imageStorageKeys	否	参考图 storageKey（与参考图一一对应）
model	否	gpt-image2（默认）/ banana-2 / banana-pro

不同模型的响应差异（重要）：

• gpt-image2：返回 { taskId, status: 'processing' }，异步，需用 GET /api/agent/tasks/:taskId 轮询。
• banana-2 / banana-pro：返回最终结果 { url, storageKey, ossReady }（部分场景后台异步写历史），无需轮询任务；等待几秒后用 GET /api/agent/assets/:assetId/history 核验权威结果与 storageKey。

响应（gpt-image2，立即返回，异步处理）：

{ "success": true, "taskId": "9bdd566c-...", "status": "processing" }

4.2 轮询任务状态

GET /api/agent/tasks/:taskId

status	含义	下一步
processing	生成中	等 3 秒再查（最长 20 分钟）
completed	完成	取 storageKey 下载原图；记录 creditsUsed/remainingCredits
failed	失败	先查历史，有图以历史为准；否则按需重试
cancelled	已取消	结束

4.3 生图历史（权威状态）

GET /api/agent/assets/:assetId/history?projectId=<PROJECT_ID>

最近一条的 resolution/aspectRatio/model/storageKey 才是真实规格；status=success 且有 storageKey 即视为已成功，直接下载。

4.4 原图下载

GET /api/agent/download?key=<STORAGE_KEY>&filename=<文件名>
→ { "success": true, "url": "https://...", "storageKey": "..." }

4.5 查询参考图

GET /api/agent/assets/:assetId/references?projectId=<PROJECT_ID>

返回该资产卡片参考组件中当前全部参考图及其参数：

{
  "success": true, "assetId": "P01", "referenceCount": 3,
  "references": [
    { "id": "...", "assetId": "P01", "storageKey": "...", "url": "...",
      "originalName": "祁夜.png", "fileSize": 123456, "mimeType": "image/png",
      "sortIndex": 0, "createdAt": "2026-08-13T..." }
  ]
}

每张参考图含：id（删除时用）、storageKey（出图参考图用）、url、originalName、fileSize、mimeType、sortIndex、createdAt。

4.6 上传参考图

POST /api/agent/assets/:assetId/references    (multipart/form-data)
字段: projectId（必填）、file（单张）或 files（批量）

响应除本次上传结果 data 外，还会返回该卡片参考组件中当前全部参考图：

{
  "success": true, "count": 1,
  "data": [{ "id": "...", "storageKey": "...", "url": "...", "originalName": "祁夜.png" }],
  "assetId": "P01", "referenceCount": 3,
  "references": [
    { "id": "...", "assetId": "P01", "storageKey": "...", "url": "...",
      "originalName": "祁夜.png", "fileSize": 123456, "mimeType": "image/png",
      "sortIndex": 0, "createdAt": "2026-08-13T..." }
  ]
}

每张参考图含：id（删除时用）、storageKey（出图参考图用）、url、originalName、fileSize、mimeType、sortIndex、createdAt。

4.7 删除参考图

单张删除：

DELETE /api/agent/assets/:assetId/references?id=<参考图记录ID>&projectId=<PROJECT_ID>

• id 取上传响应 references[].id；同时删除对象存储文件与数据库记录
• 响应返回该卡片剩余全部参考图（referenceCount + references）

删除该卡片全部参考图（内置在同一接口，仅作用于单个资产卡片）：

DELETE /api/agent/assets/:assetId/references?all=true&projectId=<PROJECT_ID>

• all=true 时忽略 id，删除该资产卡片（asset_id）下的全部参考图（不区分上传账号，与查询该卡片参考图的范围一致）
• 响应返回 deletedAll: true、deletedCount 以及删除后该卡片剩余参考图（references 应为空数组）
• 注意：删除范围始终限定在单个资产卡片，不会影响同项目其它卡片

4.8 其它

• GET /api/agent/me：认证自检 + 积分余额
• GET /api/agent/credits?transactions=true&type=consume：积分明细
• GET /api/agent/projects / POST /api/agent/projects：项目
• GET /api/agent/script?project_id=&records=&record_id=：查询已有剧本（正文/结果/进度，不含资产数据；records=true 列出剧本记录，record_id 查看指定版本）
• POST /api/agent/script：导入剧本正文（只写传入字段，未传字段保留原值）
• GET /api/agent/assets?project_id= / POST /api/agent/assets / PUT /api/agent/assets/:assetId：卡片
• POST /api/agent/assets/:assetId/generate/cancel：取消任务（body {taskId}）

5. 错误码与处理策略

状态码	含义	Agent 处理
401	未认证/密钥无效	停止，提示用户重新添加密钥
403	无权限 / 模型停用	检查密钥绑定账号权限；模型停用需管理员启用
402	积分不足 / 今日额度不足 / 项目限额超限	提示用户充值或等待，不要重试
400	参数错误	按响应 error 修正参数
404	任务/卡片/文件不存在	检查 asset_id / taskId / storageKey
409	项目名称已存在	换项目名
500	服务器错误	稍后重试一次；仍失败记录并跳过

6. 常见问题（FAQ）

Q1：出图任务一直 processing？ 等待，最长 20 分钟；期间不要重复提交。可查历史确认是否已回写。

Q2：卡片前端显示「图片加载失败」？ 不一定失败。以历史接口为准；有 success 记录直接下载，不重试。

Q3：下载文件尺寸不对？ 只有通过 1152×2048 校验的 2K PNG 才能入正片；否则按历史/原图重新下载，禁止用缩略图/WebP 冒充。

Q4：卡片已存在历史图，能覆盖重出吗？ 不要覆盖。老卡只读，新增画面用新 asset_id。

Q5：参考图传几张？ 至少传关键人物定妆图 1 张，建议正脸/全身各一张。上传后记住 storageKey。

7. 参数速查

参数	推荐值
model	gpt-image2（默认）/ banana-2 / banana-pro
size（画幅）	竖屏条漫 9:16；其它按构图：3:4/16:9/1:1/4:5/21:9/1:4/4:1 等
resolution	2k / 1k（所有模型所有分辨率均可）
提示词	必须无文字/气泡/对话框/旁白框/拟声字/水印
最终原图规格	2K 竖屏 = PNG 1152×2048
积分查看	GET /api/agent/credits、任务完成响应的 creditsUsed/remainingCredits