渠道对接完整版 · 依据 main 接口契约
AIGF-API 2.0 / CHANNEL INTEGRATION GUIDE

AIGF-API 2.0
渠道对接文档

从 AIGF-API 1.0 升级到以用量记账为核心的 2.0。覆盖用户创建、角色卡、房间、聊天、图片、视频、语音、剧本，以及 35 个接口的接入顺序、请求示例、返回字段与对账规则。聊天记录模型 token 消耗，媒体记录成功任务次数，渠道自行定价与扣费。

API-Key 识别渠道UID + AppID 归属聊天按 token 记账媒体按成功次数记账
渠道管理收费平台不预扣、不扣积分、不管理用户钱包
轮次可追溯turn_id → 模型调用 → 网关 request ID
一个查询口径本轮用量、用户明细、渠道每日汇总
01

2.0 做了哪些升级

核心变化：从平台按产品扣积分，调整为平台提供能力与用量、渠道完成自己的用户计费。

产品版本与请求路径分别看：本文的 AIGF-API 2.0 是产品名称；当前实际 HTTP 前缀仍是 /aigf/v1，WebSocket 也使用同一前缀。请直接使用本文地址，不要自行改成 /aigf/v2。
升级项AIGF-API 1.0AIGF-API 2.0
计费职责平台维护用户积分，按产品或模式扣费。平台记录消耗；用户价格、钱包、余额门槛和扣费由渠道管理。
文字 / 剧本聊天以产品价、模式价等固定积分为主。按轮次记录输入、输出 token，并提供模型分项与逐调用明细。
图片 / 视频 / 语音按对应产品价格扣积分。每个成功任务记 1 次；失败不记成功次数，不返回应扣积分。
用户与应用归属创建用户可带初始积分，app_id 可选。保留渠道 UID；app_id 必填并绑定身份。创建接口不接收积分参数。
鉴权部分入口使用渠道 API-Key，部分使用用户凭证。本文件的 35 个入口统一由渠道 API-Key 鉴权，按渠道与 UID 校验资源归属。
模型目录产品模型列表带 product_id、price 等计价信息。返回可选模型配置名与说明，不返回价格；普通聊天用 name 填 model_id。
回复与用量聊天受理、流式回复和固定扣费信息为主。支持同步回复、HTTP 异步受理与 WS；完成结果携带本轮 usage。
记忆与辅助调用已有聊天编排、状态栏与记忆能力。复用这些能力，将同轮主回复、辅助、记忆及有消耗的重试归入同一轮用量。
重试与重复提交不同入口有各自的任务与消息处理约定。聊天必传 client_request_id，媒体必传 Idempotency-Key；重复请求读取原结果。
对账与追溯以用户积分流水、产品消耗为主要依据。提供单轮、调用明细、用户 / App / 渠道每日模型用量；可关联网关请求 ID。
失败结果各入口的失败返回与扣费、退款规则有关。已保存的同步聊天失败返回 HTTP 200、data.status=failed，并保留 turn_id 与 usage。
存量数据接续已有角色房间、聊天历史、附件、记忆和剧本会话。同渠道、同 UID 归属核验通过后接续原数据；不补造历史 token 账单。

平台与渠道分别负责什么

AIGF-API 2.0

  • 执行聊天、剧本和媒体生成，保存历史与任务结果。
  • 记录本轮 token、成功媒体次数，提供查询和日汇总。
  • 维护渠道 / 用户隔离、请求幂等和平台侧用量追溯。

渠道

  • 维护自己的用户登录、可用余额、充值和终端用户价格。
  • 决定模型单价、产品系数、舍入规则及失败轮次收费规则。
  • 按 turn_id / 媒体任务 id 幂等记账，完成用户扣费与日对账。

2.0 保留用户 UID、角色房间和聊天编排。1.0 的充值、下分、积分清零、余额查询等资金接口不属于本次 2.0 接口范围。平台与渠道之间的合同单价、币种和结算周期另行约定，本文不提供真实费率。

本文依据 main 合并版本 5c907cdf（2026-10-17）整理。示例为占位内容；具体环境是否已部署相应接口，以平台发布通知及联调结果为准。

02

先看整体链路

先跑通文字聊天，再接媒体和剧本；所有业务数据都归属于当前渠道。

正常完成即返回本轮记账用量：本轮收齐主回复、状态栏、记忆等调用的 usage，保存快照后随完成结果返回 usage.status=final。渠道按 turn_id 幂等结算；统一单价可直接使用 usage.total_tokens，不同模型或输入 / 输出不同价时使用分项。缺少用量等异常返回 pending。
03

接入准备与身份约定

渠道只需要维护自己的用户标识，无需用户登录主站或获取主站 secret。

项目当前约定
生产 Base URLhttps://api.aiaigirl.com/aigf/v1；本文请求示例默认使用此地址。
UAT Base URLhttps://aigf-uat-api.abmylab.com/aigf/v1
dev Base URLhttps://aigf-dev-api.abmylab.com/aigf/v1
HTTP 鉴权所有接口携带 API-Key: YOUR_CHANNEL_API_KEY。
WebSocket 鉴权连接参数 ?api_key=YOUR_CHANNEL_API_KEY。由渠道服务端持有渠道密钥并转发前端请求。
dev 额外入口鉴权若测试入口启用 SSO，另带平台分配的 X-SSO-API-Key。它不能替代渠道 API-Key；示例省略该可选头。
user_id / uid同一个渠道用户标识：创建时是请求体的 user_id，后续路径和查询参数称为 uid。推荐使用稳定、可安全放入 URL 的字符串。
app_id创建用户时必传。身份按 渠道 + uid 唯一；AppID 是这份身份绑定的应用，不是额外的 UID 隔离层。
消息 / 媒体幂等聊天使用 client_request_id；媒体使用请求头 Idempotency-Key。业务重试必须复用原值。

联调前由平台分配渠道 API-Key、约定 AppID，并在需要时提供 dev 入口凭证。本文所有密钥、模型名及业务 ID 示例均为占位内容；请使用接口真实返回的角色、房间、消息、会话和任务 ID。

用户隔离

  • 不同渠道可传相同 UID 或相同用户名，数据相互隔离。
  • 同一渠道、同一 UID、同一 AppID 重复创建返回已有身份。
  • 同一渠道的同一 UID 换 AppID 返回 409，需先与平台确认迁移方案。

AIGF-API 1.0 存量渠道迁移

  • 经平台确认渠道凭证可用后，使用原渠道、原 UID 创建 2.0 身份。
  • 归属一致时接续已有房间、消息与记忆；无需用户登录主站。
  • 先抽样核对历史，再逐步切换入口；历史消息可能没有 turn_id。完整步骤见迁移清单。
本地示例参数 · 可替换本文代码中的地址、UID 与 AppID
只在本地更新文字，不发送请求、不保存密钥。示例中的角色和任务 ID 仍需替换为实际返回值。

04

跑通第一轮聊天

以下 ID 与 token 数均为示例。代码示例采用 curl / POSIX Shell 写法，其他工具按相同 HTTP 参数填写。

1

创建用户

由渠道提交自己的用户 ID、展示名称和 AppID；无积分、余额参数。

POST/users/create
创建请求 · JSON
curl 'https://api.aiaigirl.com/aigf/v1/users/create' \
  -H 'API-Key: YOUR_CHANNEL_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{
    "user_id": "channel-user-001",
    "username": "示例用户",
    "app_id": "channel-app"
  }'
创建响应示例
{
  "code": 0,
  "data": {
    "user_id": "channel-user-001",
    "username": "示例用户",
    "avatar": null,
    "app_id": "channel-app",
    "channel_id": 100
  }
}

必填：user_id、username（各 1–100 字符）、app_id（1–50 字符）；可选 avatar。user_id / app_id 不允许空白或首尾空格。重复创建不覆盖已有用户资料。

2

获取角色卡与可用模型

角色列表只返回当前渠道可访问的角色；选择模型是可选步骤。

角色列表 / 详情 / 模型列表
curl 'https://api.aiaigirl.com/aigf/v1/characters/list?page=1&size=20' \
  -H 'API-Key: YOUR_CHANNEL_API_KEY'

curl 'https://api.aiaigirl.com/aigf/v1/characters/20001' \
  -H 'API-Key: YOUR_CHANNEL_API_KEY'

curl 'https://api.aiaigirl.com/aigf/v1/models/list' \
  -H 'API-Key: YOUR_CHANNEL_API_KEY'
  • 角色列表在 data.items，保存其中的 id 作为 character_id。
  • 模型列表在 data 数组。需要指定模型时使用条目的 name 填写聊天 model_id；不传则按模式配置选择。
  • 实际执行可能触发辅助模型或兜底模型，最终按 usage.models[].model 记录和对账。

角色目录响应 data 包含 items、total、page、size；角色条目常用字段为 id、name、description、greeting、cover、reference、visibility、audit、attributes。模型条目含 name、model、remark、weight；不要使用 remark 展示文案代替模型标识，也不要从模型目录推导费率。

模型、模式与产品如何配合？
字段 / 概念作用接入约定
模型目录的 name平台开放的模型配置标识。普通聊天指定模型时，将此值原样填入 model_id。
模型目录的 model / remark配置的底层模型名 / 模型说明。用于了解当前配置，不代表执行时不会发生别名映射或兜底。
mode选择聊天编排、提示词及相关默认模型。同一主模型也可能因模式不同而产生不同的提示词、辅助调用和 token 数。
product_id普通聊天可选产品归因与可见性校验。不再决定平台积分价格，也不替代 model_id；不传时仍可按模式聊天。
usage.models[].model本轮用量记账的模型分项。渠道配置分模型费率时按此字段匹配；主回复 model 不能代表整轮全部调用。

模型目录会随平台配置变化，本文不固定某一批生产模型清单，也不虚构模型价格、速度或上下文上限。需要能力或价格对比时，以平台另行发布的模型说明和商务价目为准。渠道展示用名称可自行维护，提交模型标识始终使用实时目录。

3

创建或接续角色房间

取得 chat_id。相同用户、相同角色已有未删除房间时，复用最近的房间。

创建房间
curl 'https://api.aiaigirl.com/aigf/v1/chats/channel-user-001/create' \
  -H 'API-Key: YOUR_CHANNEL_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{"character_id": 20001}'

房间响应的 data.id 是后续使用的 chat_id。首次创建会写入角色开场白，开场白不计入聊天 token 用量。

展开建房响应示例
创建或接续房间 · data.id 是 chat_id
{
  "code": 0,
  "data": {
    "id": 10001,
    "uid": "channel-user-001",
    "character_id": 20001,
    "name": "示例角色",
    "created_at": "2026-10-15T08:00:00",
    "updated_at": "2026-10-15T08:00:00"
  }
}
读取开场白与最近消息
curl 'https://api.aiaigirl.com/aigf/v1/chats/channel-user-001/10001/messages?limit=50' \
  -H 'API-Key: YOUR_CHANNEL_API_KEY'
4

发送消息，拿到回复和本轮用量

先用同步方式联调；需要逐字显示时再接 WebSocket。

普通聊天 · 同步请求
curl 'https://api.aiaigirl.com/aigf/v1/messages/channel-user-001/create' \
  -H 'API-Key: YOUR_CHANNEL_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{
    "chat_id": 10001,
    "role_id": 20001,
    "content": "你好，我们从这里开始吧。",
    "client_request_id": "chat-request-001",
    "mode": "classic",
    "include_state": true,
    "include_actions": true,
    "stream": false
  }'
字段要求 / 用途
chat_id / role_id必填。role_id 是该房间绑定的角色 ID。
content必填，1–10,000 字符。
client_request_id必填，1–64 字符；同一渠道、同一 UID 内唯一。每次新消息生成新值，重试沿用原值。
mode可选，默认 regular；basic 等同 regular。常用模式含 classic、passion、unlimited、desire，是否开放以当前配置为准。
model_id可选，来自模型列表；不传则使用模式默认模型。
product_id可选，只作产品可见性校验和归因，不触发积分定价。
include_state / include_actions可选，默认分别为 true / false；控制状态栏和建议操作。
stream可选，默认 false；true 时先返回 running，再通过 WS 收取结果，或查询轮次。
同步生成成功响应节选 · 完整 usage 见第 06 节
{
  "code": 0,
  "data": {
    "turn_id": "8cb79214-3863-438f-9703-d67524c57b11",
    "client_request_id": "chat-request-001",
    "chat_id": 10001,
    "message_id": 30001,
    "ai_message_id": 30002,
    "status": "completed",
    "text": "你好，很高兴见到你。",
    "usage": {
      "status": "final",
      "prompt_tokens": 1700,
      "completion_tokens": 280,
      "total_tokens": 1980,
      "call_count": 2,
      "expected_call_count": 2
    }
  }
}
回复不是只计“用户输入 + AI 正文”。输入 token 包括本次模型实际接收的提示词、历史和注入的记忆；本轮另行触发的状态栏、评估、记忆摘要等模型调用也会汇入同一 turn。不要在渠道侧按文本字数再次估算。
展开聊天响应字段说明
data 字段含义 / 渠道处理
turn_id本轮唯一标识，用于查结果、查用量和渠道扣费幂等。
client_request_id渠道提交的业务请求标识，用于关联本地消息与重试。
message_id / ai_message_id用户消息 / AI 回复的 ID。消息配图、转视频、语音使用 ai_message_id。
status轮次状态 running / completed / failed。它与 usage.status 是两个不同字段。
text / modelAI 正文 / 回复模型。整轮可能包含多个模型，计费使用 usage.models。
character_state / suggested_actions模式支持时返回角色状态与建议操作，可为空。
chat_id / product_id / error所属房间、可选产品归因、失败原因。
usage本轮计费用量；只有 status=final 才作为完整计费用量处理。
HTTP 200 不等于生成成功。已保存的同步轮次，无论生成成功或失败，均返回 {"code":0,"data":…}，与查询和幂等重放的结构一致。请检查 data.status：completed 展示回复，failed 展示 data.error；另按 data.usage.status 判断用量是否可结算。失败轮次仍可能有消耗，是否向终端用户收费由渠道决定。参数、鉴权和服务异常仍按 HTTP 错误码处理。
展开同步生成失败响应示例 · HTTP 200

以下为字段节选：失败不会丢掉 turn_id、消息 ID 或用量；同一 client_request_id 重试只读取该轮结果，不重新生成。示例中的失败调用有消耗；若实际返回 usage.status=pending，先补查用量。

读取 data.status 与 data.error，不能只判断 HTTP 200 或 code=0
{
  "code": 0,
  "data": {
    "turn_id": "8cb79214-3863-438f-9703-d67524c57b12",
    "client_request_id": "chat-request-002",
    "chat_id": 10001,
    "message_id": 30003,
    "ai_message_id": 30004,
    "status": "failed",
    "error": "聊天生成失败",
    "usage": {
      "turn_id": "8cb79214-3863-438f-9703-d67524c57b12",
      "status": "final",
      "prompt_tokens": 1200,
      "completion_tokens": 200,
      "total_tokens": 1400,
      "call_count": 1,
      "expected_call_count": 1,
      "models": [
        {
          "model": "MODEL_MAIN",
          "prompt_tokens": 1200,
          "completion_tokens": 200,
          "total_tokens": 1400,
          "call_count": 1
        }
      ],
      "calls": [
        {
          "id": 90003,
          "trace_id": "8cb79214-3863-438f-9703-d67524c57b12",
          "status": "failed",
          "model": "MODEL_MAIN",
          "gateway_request_id": "GATEWAY_REQUEST_ID",
          "prompt_tokens": 1200,
          "completion_tokens": 200,
          "total_tokens": 1400,
          "stat_date": "2026-10-17",
          "created_at": "2026-10-17T08:48:05"
        }
      ]
    }
  }
}
05

流式聊天与 WebSocket

一条用户连接接收聊天流、剧本流和媒体终态。先建立连接，再提交异步请求。

WS/websocket/{uid}/message?api_key=…
连接地址 · 由渠道服务端连接
wss://api.aiaigirl.com/aigf/v1/websocket/channel-user-001/message?api_key=YOUR_CHANNEL_API_KEY

发起方式二选一：HTTP 聊天传 stream:true，连接只负责收流；或直接向 WS 发送以下帧。不要为同一用户消息同时发送两份新请求。

WS 发送聊天
{
  "type": "text",
  "body": {
    "chat_id": 10001,
    "role_id": 20001,
    "content": "你好，我们从这里开始吧。",
    "client_request_id": "chat-request-002",
    "mode": "classic"
  }
}
渠道服务端
AIGF-API 2.0
模型 / 网关
① 发消息：client_request_id →
校验用户与房间归属
← ② accepted：保存 turn_id
本轮状态 running
展示正文与状态
③ 主回复 + 辅助 / 记忆调用 →
← ④ text / state_stream
仍在生成，不重复累加用量
等待本轮结束
← ⑤ 收齐 usage，保存计费快照
← ⑥ end：turn_id + usage
final 或 pending
⑦ 正常 end 携带 final 用量，渠道以 turn_id 幂等扣费；OpenSealion 在后台核对，不阻塞下一轮。
服务端帧 type渠道处理
accepteddata 中取得 turn_id、消息 ID；这是受理，不是生成或用量完成。
textbody 是累计正文，覆盖当前显示内容；不要把每一帧都追加一次。
state_stream按模式显示状态；不在此阶段计算最终 token。
end顶层含 turn_id、client_request_id、status、usage；聊天 channel 为 chat，剧本为 scripts。
error / pongerror 为错误通知；发送 {"type":"ping"} 可获得 pong。
普通聊天 end 帧节选 · usage 与 HTTP / 查询结构一致
{
  "channel": "chat",
  "type": "end",
  "body": "",
  "turn_id": "0f5d384e-20fa-4d52-b4a7-2a42eae0b998",
  "client_request_id": "chat-request-002",
  "status": "completed",
  "text": "你好，很高兴见到你。",
  "usage": {
    "status": "final",
    "prompt_tokens": 1700,
    "completion_tokens": 280,
    "total_tokens": 1980,
    "call_count": 2,
    "expected_call_count": 2
  }
}
断线不等于重新生成。连接中断或未收到 end 时，用原 turn_id 查询结果；提交结果不确定时，用原 client_request_id 重试。当前接口不提供 webhook，不能仅依赖推送保存最终账单。
06

本轮用量与渠道扣费

平台给用量事实，渠道决定用户价格、计价单位、失败轮次收费规则。

1. 统一读取 usage

同步聊天读取 data.usage；WS 完成帧读取 usage；轮次查询和单轮用量查询读取 data.usage。以下示例表示主回复与一次本轮记忆调用，其他辅助调用也采用同样方式归集。

usage 示例 · 示例模型名不代表当前可选模型
{
  "turn_id": "8cb79214-3863-438f-9703-d67524c57b11",
  "status": "final",
  "prompt_tokens": 1700,
  "completion_tokens": 280,
  "total_tokens": 1980,
  "call_count": 2,
  "expected_call_count": 2,
  "models": [
    {"model": "MODEL_MAIN", "prompt_tokens": 1200,
     "completion_tokens": 200, "total_tokens": 1400, "call_count": 1},
    {"model": "MODEL_MEMORY", "prompt_tokens": 500,
     "completion_tokens": 80, "total_tokens": 580, "call_count": 1}
  ],
  "calls": [
    {"id": 90001, "trace_id": "8cb79214-3863-438f-9703-d67524c57b11",
     "uid": "channel-user-001", "app_id": "channel-app", "chat_id": 10001,
     "resource": "llm", "scene": "aigf_chat", "status": "succeeded",
     "model": "MODEL_MAIN", "profile": "MODEL_MAIN",
     "gateway_request_id": "gateway-request-a",
     "prompt_tokens": 1200, "completion_tokens": 200, "total_tokens": 1400,
     "quantity": 0, "purpose": "main_reply",
     "stat_date": "2026-10-15", "created_at": "2026-10-15T08:00:00"},
    {"id": 90002, "trace_id": "8cb79214-3863-438f-9703-d67524c57b11",
     "uid": "channel-user-001", "app_id": "channel-app", "chat_id": 10001,
     "resource": "llm", "scene": "aigf_chat", "status": "succeeded",
     "model": "MODEL_MEMORY", "profile": "MODEL_MEMORY",
     "gateway_request_id": "gateway-request-b",
     "prompt_tokens": 500, "completion_tokens": 80, "total_tokens": 580,
     "quantity": 0, "purpose": "memory_summary",
     "stat_date": "2026-10-15", "created_at": "2026-10-15T08:00:01"}
  ]
}

本例展示字段含义，数值与状态仅为示意，以实际返回为准；purpose、chat_id 等字段在部分调用中可为空。usage 读取暂不可用时，token 计数也可能为 null，不能当成 0。

usage 字段含义扣费判断
statuscollecting 运行中；final 本轮记账用量齐全且已保存；pending 实际用量缺失或系统异常。渠道以 final 作为本轮用量可结算的条件。
prompt_tokens / completion_tokens本轮所有模型调用的输入 / 输出 token 总和。分模型单价不同时，使用 models 分项计算，不能只套一个单价。
total_tokens本轮输入与输出 token 之和；统一 token 单价时可直接使用。输入 / 输出或模型单价不同则使用分项；不要再与输入 / 输出重复相加。
call_count / expected_call_count已记录 / 本轮应记录的模型调用数。final 要求调用记录齐全；一轮不固定只有一次调用。
models / calls按模型聚合 / 逐调用明细，表达同一份消耗。二者不能重复相加。
collecting

本轮仍在运行，token 尚未收齐。等待 end 或查询轮次。

pending

用量缺失、记录不全或读取异常。暂缓结算，补齐后再处理。

final · 可结算

本轮已结束且记账用量已固定，按 turn_id 和本轮 token 结算。

渠道只需使用本轮记账结果。平台按统一记账口径归集消耗，可能包含网关估算，不承诺每条均为模型原生分词器的精确计数。计数来源、精度和网关核对标记留作平台内部对账信息，不作为渠道接口字段返回；不要求渠道额外判断这些状态。

调用失败时，明细的 status=failed 保留。已确认无消费的调用计 0 token；存在消耗的失败调用仍记录用量。平台负责核对与收口，渠道使用本轮最终结果，不按失败调用自行猜测消耗。

2. 按模型输入 / 输出分别计算

能力平台提供的记账单位渠道计费方式幂等业务键
普通聊天 / 剧本聊天输入与输出 token，含本轮附属调用。统一 token 单价，或按模型输入 / 输出分别定价；可另设渠道自己的产品系数。当前环境、渠道内的 turn_id。
图片 / 视频 / 语音成功任务次数 quantity；每个成功任务为 1。成功次数 × 渠道对应能力的每次单价。当前环境、渠道内的媒体整数 data.id。
角色目录 / 房间 / 历史 / 上传不是聊天 token 轮次或媒体生成成功次数。不因调用这些接口生成上述消耗；其他商务约定另行确认。不作为生成扣费事件。
本轮用户费用 = Σ 每个模型（输入 token ÷ 1,000,000 × 该模型输入单价
＋ 输出 token ÷ 1,000,000 × 该模型输出单价）
  • 费率由渠道维护，币种、舍入精度、产品系数按渠道规则确定。平台接口只返回消耗，不返回应扣积分或余额。
  • 按 usage.models 求和即可；usage.calls 用于逐调用核查，不能在模型合计之外再加一次。
  • 以 turn_id 作为渠道账单唯一业务键；HTTP、WS、查询重复拿到相同轮次时只扣一次。
  • 生成失败也可能发生实际模型消耗。平台保留用量；是否向终端用户收费由渠道自行决定，并与渠道结算口径区分。
  • 平台不做余额拦截。余额门槛和用户风控由渠道在请求模型前完成。
渠道推荐处理顺序：收到同步结果或 WS end → 保存 turn_id 和 usage → 按轮次状态执行渠道自己的收费规则 → usage.status=final 时按统一单价或模型分项计费、以 turn_id 幂等记账 → 更新用户余额和界面。下一轮正常受理不需要等待网关核对。

3. 异常用量补查与 OpenSealion 追溯

查本轮 / 触发网关核对 · 同一个 turn_id
curl 'https://api.aiaigirl.com/aigf/v1/usage/turns/8cb79214-3863-438f-9703-d67524c57b11?uid=channel-user-001' \
  -H 'API-Key: YOUR_CHANNEL_API_KEY'

curl -X POST 'https://api.aiaigirl.com/aigf/v1/usage/turns/8cb79214-3863-438f-9703-d67524c57b11/reconcile?uid=channel-user-001' \
  -H 'API-Key: YOUR_CHANNEL_API_KEY'

turn_id = calls[].trace_id 将同轮所有调用串起来；有网关请求 ID 时，可用 gateway_request_id 精确追查对应记录。一轮对话可以对应多条 OpenSealion 记录。被上游直接拒绝且已确认无消费的调用可能没有消费日志，不能要求每条失败调用都存在消费记录。

渠道通过 AIGF 用量接口取得对应关系，无需拿 OpenSealion 管理员令牌。每次调用保留 gateway_request_id 供平台追溯；内部来源与核对信息不向渠道展开。已交付的 final 计费快照不会因后台核对而改写，异常差异由平台按双方约定处理。

建议由渠道后台按短间隔、逐步退避的方式补查 pending；这是接入策略建议，不是服务时效承诺。超出渠道可接受时限时保留 turn_id 排查，不要新建消息替代核对。

哪些情况才需要异常补查？
  • 模型返回正文但没提供 usage，或流式连接中断导致统计尾帧丢失。
  • 发生重试 / 兜底，部分调用的记账用量尚未取得。
  • 用量记录写入失败、记录不完整或查询暂不可用。

这些情况看 usage.status=pending，渠道将 turn_id 放入待结算列表，补齐后幂等结算。若 status=final，按已返回的记账用量结算，无需额外判断内部核对状态。模型返回的最后一个正文片段也不等于本轮完成，应以 end / 轮次终态为准。

07

图片、视频与语音

媒体均为异步任务：提交 → 保存任务 ID → 查询 / 接收终态 → 成功记 1 次。

先分清三个 ID

① message_id30002

已完成的 AI 回复 ID。用于消息配图、配图转视频和消息语音；不是用户消息 ID。

② data.id7001

AIGF 媒体任务整数 ID。查询 /tasks/7001，也用于渠道任务账单幂等。

③ data.task_id业务任务 UUID

配图转视频的 image_task_id 填图片响应中的这个值，不填整数 7001。

每个媒体 POST 必传：Idempotency-Key: media-request-001，长度 1–64。同渠道、同用户、同资源类型范围内使用唯一值；网络重试保持原键和原参数。

A. 聊天消息配图 → 图生视频

第一步 · 已完成的 AI 消息生成配图（无请求体）
curl -X POST 'https://api.aiaigirl.com/aigf/v1/media/channel-user-001/messages/30002/image' \
  -H 'API-Key: YOUR_CHANNEL_API_KEY' \
  -H 'Idempotency-Key: image-request-001'

配图需要消息所属角色具备可用封面或参考图。保存返回的整数 id 和 UUID task_id；等待图片 completed 后再转视频。

媒体提交响应示例
{
  "code": 0,
  "data": {
    "id": 7001,
    "uid": "channel-user-001",
    "resource": "image",
    "status": "pending",
    "task_id": "7d2aa971-df39-49ef-9548-b4eab8abc001",
    "trace_id": "ac5fd49f-8350-4a73-95fc-307d3d27f201",
    "result": [],
    "created_at": "2026-10-15T08:05:00"
  }
}
第二步 · 用整数 id 查询图片任务
curl 'https://api.aiaigirl.com/aigf/v1/media/channel-user-001/tasks/7001' \
  -H 'API-Key: YOUR_CHANNEL_API_KEY'

当返回 status=completed，从 result 取得资源地址。失败为 failed；提交阶段的 pending / dispatching / in_progress 等状态都不表示成功。HTTP 返回 200 代表提交接口成功返回，不能据此给用户展示“图片已生成”。

第三步 · 同一消息的已完成配图转视频
curl 'https://api.aiaigirl.com/aigf/v1/media/channel-user-001/messages/30002/image-to-video' \
  -H 'API-Key: YOUR_CHANNEL_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: video-request-001' \
  --data '{"image_task_id":"7d2aa971-df39-49ef-9548-b4eab8abc001"}'

视频是基于已完成配图生成，要求图片归属同一用户、同一条 AI 消息并已挂载；不提供仅凭消息正文直接生成视频的入口。视频提交后保存它自己返回的新 data.id 继续查任务。

B. 消息语音 / 文本语音

已有 AI 回复朗读 / 独立文本转语音
curl -X POST 'https://api.aiaigirl.com/aigf/v1/media/channel-user-001/messages/30002/audio' \
  -H 'API-Key: YOUR_CHANNEL_API_KEY' \
  -H 'Idempotency-Key: message-audio-request-001'

curl 'https://api.aiaigirl.com/aigf/v1/media/channel-user-001/audios' \
  -H 'API-Key: YOUR_CHANNEL_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: text-audio-request-001' \
  --data '{"text":"你好，很高兴见到你。"}'

文本语音可选 spk_id 指定音色，不传使用当前默认音色。两类语音都采用同一任务查询接口。

C. 相册生图 / 相册进阶视频

这条链路只要求用户已创建，不要求先有普通聊天房间。先查询风格 / 模板；自定义图片可先上传取得 URL。

能力路径（均基于 Base URL）关键参数
风格GET /media/styles?type=imagetype 可为 image / video / audio；提交任务使用返回的 key，不用展示名称。
模板GET /media/templates?type=image&category=posetype 为 image / video；category 可选 pose / action。
上传图片POST /upload/imagemultipart 文件字段名是 image；返回 URL。上传不计生成次数。
相册初级生图POST /media/{uid}/images/easyprompt、style 必填；ratio 默认 portrait，可为 landscape；character_id 可选。
相册进阶生图POST /media/{uid}/images/seniorperson_image_url、style 必填；pose_template_id 与 pose_image_url 至少一个；同传时模板优先。
相册进阶视频POST /media/{uid}/videos/seniorperson_image_url、style 必填；prompt 与 action_template_id 至少一个。特定渠道配置可能要求动作模板。
展开相册与上传请求示例
上传图片 · multipart
curl 'https://api.aiaigirl.com/aigf/v1/upload/image' \
  -H 'API-Key: YOUR_CHANNEL_API_KEY' \
  -F 'image=@person.jpg'
相册初级生图 · 替换 style 为实际 key
curl 'https://api.aiaigirl.com/aigf/v1/media/channel-user-001/images/easy' \
  -H 'API-Key: YOUR_CHANNEL_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: album-image-request-001' \
  --data '{"prompt":"在花园中散步的人物","style":"IMAGE_STYLE_KEY","ratio":"portrait"}'
相册进阶生图 · 使用上传后的图片 URL
curl 'https://api.aiaigirl.com/aigf/v1/media/channel-user-001/images/senior' \
  -H 'API-Key: YOUR_CHANNEL_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: album-senior-image-request-001' \
  --data '{
    "person_image_url":"https://YOUR_IMAGE_HOST/person.jpg",
    "pose_template_id":60001,
    "style":"IMAGE_STYLE_KEY",
    "ratio":"portrait"
  }'
相册进阶视频 · 使用动作描述或有效动作模板
curl 'https://api.aiaigirl.com/aigf/v1/media/channel-user-001/videos/senior' \
  -H 'API-Key: YOUR_CHANNEL_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: album-video-request-001' \
  --data '{
    "person_image_url":"https://YOUR_IMAGE_HOST/person.jpg",
    "prompt":"人物自然微笑，缓慢向前走。",
    "style":"VIDEO_STYLE_KEY",
    "ratio":"portrait"
  }'

人物图和参考图请使用平台可访问的 HTTPS 地址；模板 ID、风格 key 按接口实际返回填写。prompt 长度 2–1,000 字符；进阶视频的动作模板含提示词时优先采用模板内容。

D. 终态通知与计次

WS 媒体完成通知节选
{
  "channel": "image",
  "type": "completed",
  "user_id": "channel-user-001",
  "task": {
    "id": 7001,
    "status": "completed",
    "task_id": "7d2aa971-df39-49ef-9548-b4eab8abc001",
    "result": ["https://YOUR_MEDIA_HOST/output.jpg"]
  }
}
  • 媒体成功任务记 quantity=1，失败不计次数；不是每张图、每秒视频或每字语音各记一次。
  • 任务响应本身不带 token 用量或 quantity。渠道可按 completed 幂等计一次，随后从 /usage/calls、/usage/daily 对账。
  • 媒体内部提示词优化产生的 LLM token 不进入渠道对外用量；对外只记录成功媒体次数。
  • WS channel 为 image / video / audio，type 为 completed / failed；断线或漏通知时，用整数任务 ID 查询补齐。
  • 如遇 unresolved 或长时间未完成，保留原任务和幂等键联系平台。不要更换幂等键连续生成重复任务。
展开媒体任务返回字段与查询建议
data 字段说明
id / task_id整数 AIGF 任务 ID / 字符串业务任务 ID。查任务用 id；消息配图转视频的 image_task_id 用图片 task_id。
resourceimage / video / audio。
status以 completed / failed 判断终态；其他进行中状态等待后续查询。
result成功资源地址列表；进行中通常为空，失败为空。不要对结果列表长度再次按任务计数。
trace_id / uid / created_at追踪标识、所属用户、任务创建时间。

优先接 WS 终态通知，同时保留查询补偿。没有收到通知时可由渠道后台逐步退避查询；不要承诺固定生成耗时。网络超时重试提交沿用原 Idempotency-Key 和原参数，已经拿到 id 时优先查原任务。

08

剧本聊天

与普通房间分开创建剧本会话；token 归集和对账规则一致。

GET /scripts/list→GET /scripts/{script_id}→创建 sessions→POST messages / WS script→end.usage / 查轮次
查询剧本与创建会话
curl 'https://api.aiaigirl.com/aigf/v1/scripts/list?page=1&size=20' \
  -H 'API-Key: YOUR_CHANNEL_API_KEY'

curl 'https://api.aiaigirl.com/aigf/v1/scripts/40001' \
  -H 'API-Key: YOUR_CHANNEL_API_KEY'

curl 'https://api.aiaigirl.com/aigf/v1/scripts/channel-user-001/sessions' \
  -H 'API-Key: YOUR_CHANNEL_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{"script_id":40001}'

保存会话响应的 data.id 作为 session_id，可能复用已有会话。发送剧本消息：

剧本消息 · 异步受理
curl 'https://api.aiaigirl.com/aigf/v1/scripts/channel-user-001/messages' \
  -H 'API-Key: YOUR_CHANNEL_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{
    "session_id":50001,
    "script_id":40001,
    "content":"我走进房间，观察四周。",
    "client_request_id":"script-request-001"
  }'
  • 剧本消息立即返回 running，不使用普通聊天的 stream 开关。通过 WS 收取 scripts 的 end，或查 /scripts/{uid}/turns/{turn_id}。
  • 可选 role_id、model、mode。这里指定模型的字段叫 model，不是普通聊天的 model_id；不接收 product_id。
  • 直接走 WS 时发送 {"type":"script","body":{…相同消息字段…}}。
  • 剧情状态、选项等按实际帧展示；最终用量仍按 turn_id、usage.models 和 gateway_request_id 核对。
展开 WS 剧本发送帧示例
与普通聊天共用用户连接，type 使用 script
{
  "type": "script",
  "body": {
    "session_id": 50001,
    "script_id": 40001,
    "content": "我走进房间，观察四周。",
    "client_request_id": "script-request-002"
  }
}

受理后保存 turn_id；最终 channel=scripts, type=end 返回本轮 usage。剧本轮次字段包括 session_id、script_id、user_message_id、ai_message_id、text、status、error；正常 final 用量同样无需等待 OpenSealion。

09

历史记录与渠道每日对账

单用户查明细，全渠道查汇总；范围始终由当前 API-Key 限定。

用户会话与历史消息

房间列表 / 历史分页 / 轮次结果 / 剧本历史
GET /chats/channel-user-001/list?limit=20
GET /chats/channel-user-001/10001/messages?limit=50
GET /chats/channel-user-001/10001/messages?limit=50&before_id=30001
GET /messages/channel-user-001/turns/8cb79214-3863-438f-9703-d67524c57b11
GET /scripts/channel-user-001/sessions/50001/messages?page=1&size=100
  • 普通历史返回文本、角色状态、建议操作及图片 / 视频 / 语音附件。新 2.0 消息可通过 turn_id 补查用量。
  • 普通聊天历史使用 before_id 向前分页：取当前页最小消息 ID；每页最多 100 条，页内按时间正序。
  • 房间列表 limit 最多 100；剧本历史按 page / size 分页，size 最多 200。

普通房间列表和消息历史的 data 都是数组。消息字段含 id、turn_id、chat_id、sender_type、sender_id、text、status、model、created_at、character_state、suggested_actions 和 attachments；附件含 id、type、url、preview_url、task_id。旧消息与开场白的 turn_id 可为空，不能据此补造新的聊天账单。

渠道总量 / 按 App / 按用户 / 按模型

当前渠道全部用户的每日用量
curl 'https://api.aiaigirl.com/aigf/v1/usage/daily?start_date=2026-10-01&end_date=2026-10-15' \
  -H 'API-Key: YOUR_CHANNEL_API_KEY'
指定 App 汇总 / 指定用户调用明细
curl 'https://api.aiaigirl.com/aigf/v1/usage/daily?app_id=channel-app&start_date=2026-10-01&end_date=2026-10-15' \
  -H 'API-Key: YOUR_CHANNEL_API_KEY'

curl 'https://api.aiaigirl.com/aigf/v1/usage/calls?uid=channel-user-001&resource=llm&start_date=2026-10-01&end_date=2026-10-15&limit=100' \
  -H 'API-Key: YOUR_CHANNEL_API_KEY'
查询范围 / 分页返回口径
/usage/daily不传 uid / app_id 为全渠道；可按 uid、app_id 过滤。默认最近 7 个北京自然日；起止日期差不超过 31 天，含首尾最多 32 个自然日。按 date、app_id、resource、model 分组；含 call_count、prompt_tokens、completion_tokens、quantity。
/usage/calls可传 uid、app_id、trace_id、resource、start_date、end_date；limit 默认 100，最多 500。以返回页最小 id 作为下一页 before_id，按 id 倒序。逐调用 / 媒体计次明细；可检查 request ID、模型、token 和 quantity。
/usage/turns/{turn_id}必传 uid；仅查当前渠道所属轮次。本轮所有调用与最终记账 usage；普通聊天与剧本共用。
展开每日汇总响应示例
daily 示例 · 同一渠道、同一天的分组行
{
  "code": 0,
  "data": [
    {"date":"2026-10-15", "app_id":"channel-app", "resource":"llm",
     "model":"MODEL_MAIN", "call_count":1,
     "prompt_tokens":1200, "completion_tokens":200, "quantity":0},
    {"date":"2026-10-15", "app_id":"channel-app", "resource":"llm",
     "model":"MODEL_MEMORY", "call_count":1,
     "prompt_tokens":500, "completion_tokens":80, "quantity":0},
    {"date":"2026-10-15", "app_id":"channel-app", "resource":"image",
     "model":null, "call_count":1,
     "prompt_tokens":0, "completion_tokens":0, "quantity":1}
  ]
}

本例合计聊天输入 1,700 / 输出 280 token，图片成功 1 次。媒体按成功次数记账。

daily 不是单个“grand total”数字，渠道需把分组行相加：LLM 合计输入 / 输出 token；image、video、audio 合计 quantity。不同模型单价不同时，保留模型维度分别计算。

日对账以 date / stat_date 的北京自然日为准；resource=llm 的 call_count 是模型调用次数，不是聊天轮数。渠道统计用户聊天轮数时应按 turn_id 去重；媒体成功次数累加 quantity，不使用 LLM call_count 代替。

本轮、调用明细和每日汇总使用同一记账口径。已交付 final 的模型与 token 不会因后台核对而变化；每日汇总合并同一模型下的内部计数来源，返回统一记账总量。仍有 pending 轮次时，当日汇总可能随缺失用量补齐而更新；应在待结算轮次处理完成后做最终日对账。渠道按 turn_id 幂等处理，不把同一调用补查当成新增扣费。

建议渠道保留的对账索引

uid、app_id、client_request_id、turn_id、模型分项 token、用量状态、渠道应收 / 实收；媒体另存 data.id、data.task_id、资源类型和任务终态。渠道无需保存用户正文来完成用量对账。

10

从 1.0 迁移到 2.0

保留渠道自己的用户标识与可接续的历史；逐项调整请求、结果和自有计费逻辑。

渠道改造清单

顺序渠道要改什么完成标志
1确认当前渠道的 2.0 凭证与环境；切换 Base URL，统一携带 API-Key。目录接口可访问；不把 1.0 用户 secret 当作渠道 API-Key。
2使用原 user_id 创建用户，补齐 username 和稳定 app_id；删除积分初始化等旧字段。重复创建返回原身份；历史房间可见；同渠道同 UID 不能随意更换 app_id。
3使用 2.0 模型目录，按 name 填普通聊天 model_id；按接口返回确认角色和房间 ID。不继续把 1.0 的产品模型展示名、旧 id 或 price 当作新模型标识或新费率。
4为普通 / 剧本消息生成 client_request_id；为媒体请求生成 Idempotency-Key。同参数重试返回原结果，重试不会多生成一次；不同新消息使用新键。
5分别处理同步、异步和 WS；保存 turn_id、消息 ID、媒体整数 ID 与 UUID。可用原标识查回成功或失败结果；WS 累计正文不重复追加。
6从平台积分扣费切换到渠道自己的价格和钱包；读取 token / 成功次数。聊天按 final 用量幂等计费，媒体只在 completed 时记一次；pending 进入待结算队列。
7接入用户 / App / 渠道每日汇总，与渠道账单建立对账索引。分模型输入输出及媒体次数能核对；用户收费与平台合同结算分别保存。
8小批量验证新用户、存量用户及并发 / 失败 / 重试，再逐步切换流量。同一条业务请求只走一个生成入口，避免 1.0 和 2.0 同时生成、重复计费。

历史与余额怎样处理

  • 同一渠道与原 UID：归属确认后接续原房间、消息、附件、记忆和剧本会话，不要求用户重新聊天来建立历史。
  • 绑定冲突：若历史归属缺失、已有独立身份或 AppID 不一致，返回 409 后联系平台确认，不要通过更换 UID 绕开迁移核验。
  • 历史用量：1.0 历史消息可能没有 turn_id 或可用的逐调用用量。2.0 不为旧消息补造 token 消耗，不把可读历史当成新消费。
  • 原积分余额：2.0 不充值、不兑换、不清零，也不扣除 1.0 的积分；渠道如需承接旧余额，应在自己的钱包和结算规则中单独处理。
  • 配置边界：本文件覆盖 35 个对外入口。1.0 的资金、后台审核、独立管理配置等接口不视为在 2.0 自动获得同名入口；需要额外能力时与平台确认。
迁移验收不能只测已有账号。同时测一个全新 UID 和一个真实存量 UID：前者核对创建、建房、第一轮回复与用量；后者核对历史连续、原资源 ID、旧余额不受 2.0 请求影响，以及 1.0 用量不混入 2.0 对账。
11

接口总表

下面的相对路径统一加在 Base URL 后；除 WS 外均携带 API-Key 请求头。

完整接口目录
方法相对路径用途 / 备注
POST/users/create创建 / 绑定渠道用户；user_id、username、app_id 必填
GET/characters/list角色卡目录；keyword / tags / page / size
GET/characters/{character_id}可访问角色详情
GET/models/list模型目录；不返回价格或密钥
POST/chats/{uid}/create创建 / 接续角色房间；character_id
GET/chats/{uid}/list用户房间列表；limit
GET/chats/{uid}/{chat_id}/messages历史消息与附件；limit / before_id
DELETE/chats/{uid}/{chat_id}软删除房间、清理关联记忆；运行中返回 409
POST/messages/{uid}/create同步 / 异步聊天；client_request_id 幂等
GET/messages/{uid}/turns/{turn_id}查正文、轮次状态、本轮 usage
WS/websocket/{uid}/message?api_key=…聊天、剧本流与媒体终态；text / script / ping
GET/scripts/list剧本目录；page / size / keyword
GET/scripts/{script_id}剧本详情
POST/scripts/{uid}/sessions创建 / 接续剧本会话；script_id
POST/scripts/{uid}/messages异步剧本聊天；指定模型字段为 model
GET/scripts/{uid}/turns/{turn_id}剧本轮次与 usage
GET/scripts/{uid}/sessions/{session_id}/messages剧本历史；page / size
POST/media/{uid}/messages/{message_id}/image已完成 AI 消息配图；无请求体
POST/media/{uid}/messages/{message_id}/image-to-video同消息配图转视频；image_task_id 填图片任务 UUID
POST/media/{uid}/messages/{message_id}/audioAI 消息语音；无请求体
POST/media/{uid}/audios文本语音；text / spk_id?
POST/media/{uid}/images/easy相册初级生图；prompt / style / ratio
POST/media/{uid}/images/senior相册进阶生图；人物图 + 姿势参考
POST/media/{uid}/videos/senior相册进阶视频；人物图 + 动作描述 / 模板
GET/media/{uid}/tasks/{task_id}查媒体任务；路径 task_id 为整数 data.id
GET/media/stylestype=image / video / audio
GET/media/templatestype=image / video；category 可选
POST/upload/imagemultipart：image 文件
GET/usage/turns/{turn_id}?uid=…单轮调用与 usage；普通聊天 / 剧本通用
POST/usage/turns/{turn_id}/reconcile?uid=…触发网关核对 / 补齐缺失用量；不改已交付计费快照
GET/usage/calls调用与媒体计次明细；可按用户 / App / 日期过滤
GET/usage/daily渠道每日 / 模型 / 资源汇总
POST/characters/{uid}/create可选：创建角色；multipart image + character_data
POST/characters/{uid}/import可选：导入角色卡；multipart file
POST/characters/{uid}/{character_id}/update可选：编辑本人创建的角色
角色管理扩展 · 创建 / 导入 / 编辑参数与示例
  • 创建：multipart 必传 image，图片不超过 20 MiB；character_data 为 JSON 字符串，attributes 中 name、personality、background、greeting、user_appellation、user_background 均为非空文本。审核状态由服务端控制。
  • 导入：文件字段叫 file，可选 ai_model（默认 gemma）、tag_ids。
  • 编辑：image 可选，character_data 可更新 attributes / visibility / extend；仅允许编辑本人创建且有权限的角色。
  • 角色可见性和审核会影响是否能被当前渠道选用。新建 / 导入不是绕过审核的方式。
创建私有角色 · multipart 表单
curl 'https://api.aiaigirl.com/aigf/v1/characters/channel-user-001/create' \
  -H 'API-Key: YOUR_CHANNEL_API_KEY' \
  -F 'image=@character.jpg' \
  -F 'character_data={"visibility":"private","attributes":{"name":"示例角色","personality":"温和开朗","background":"住在海边的朋友","greeting":"你好，很高兴认识你。","user_appellation":"朋友","user_background":"新来到这座城市的旅行者"}}'

创建响应的 data 含 character 和 chat：角色 ID 在 data.character.id，自动创建 / 接续的房间 ID 在 data.chat.id。上传图片用于角色生成，不是用户聊天配图任务。

导入角色卡 / 编辑本人角色
curl 'https://api.aiaigirl.com/aigf/v1/characters/channel-user-001/import' \
  -H 'API-Key: YOUR_CHANNEL_API_KEY' \
  -F 'file=@character-card.png' \
  -F 'ai_model=gemma'

curl 'https://api.aiaigirl.com/aigf/v1/characters/channel-user-001/20001/update' \
  -H 'API-Key: YOUR_CHANNEL_API_KEY' \
  -F 'character_data={"attributes":{"greeting":"欢迎回来。"}}'
删除房间 · 请求示例
软删除指定房间并清理其关联记忆
curl -X DELETE 'https://api.aiaigirl.com/aigf/v1/chats/channel-user-001/10001' \
  -H 'API-Key: YOUR_CHANNEL_API_KEY'

成功响应为 {"code":0,"message":"删除成功"}；有运行中的聊天时返回 409。删除入口会清理该房间的记忆，请将它作为用户明确执行的删除操作。

12

错误、重试与接入验收

先保住同一业务请求的唯一标识，再补结果、补用量，避免重复生成与重复扣费。

常见响应与处理

正常 JSON 业务响应通常为 {"code":0,"data":…}。错误体可能由入口或中间件包装，同时检查 HTTP 状态与响应内容，不要只判断 code。

HTTP常见含义渠道处理
200已取得轮次结果；data.status 可为 running / completed / failed不要只判断 HTTP 或 code。生成失败读取 error、保存 turn_id 和 usage；渠道按失败收费规则及 usage.status 处理。
400 / 422参数不合法、字段缺失、模式未配置或角色不匹配修正参数；检查参数名、必填字段、枚举与类型。创建用户不允许带积分等额外字段。
403渠道密钥无效、用户禁用或资源不可用检查当前渠道凭证和资源可见性。测试入口额外鉴权失败需与平台核对。
404用户尚未创建，或房间 / 消息 / 任务不存在、不可访问确认 UID 与渠道一致，使用真实返回的 ID；不要借用其他用户的资源。
409AppID 绑定冲突、幂等参数冲突、同会话上一轮仍在运行先查询原身份 / 原轮次 / 原任务。不是所有 409 都能用新 request ID 重试解决。
503手动网关核对暂不可用或未配置稍后补查并反馈平台；已取得 final 用量可正常扣费。实际缺失用量不能当 0。
超时 / 断线 / 5xx客户端无法确认是否受理聊天用原 client_request_id、媒体用原 Idempotency-Key 重试，并优先查询已知 turn_id / task id。

并发约定

普通聊天同一房间只运行一轮，等该轮结束再发下一条；并非“同一用户全局只能聊一个房间”。剧本同一会话也应按顺序提交。幂等只避免同一业务请求重复执行，不代替渠道自身的钱包并发控制。

反馈问题时提供

环境、请求时间与时区、UID / AppID、HTTP 方法与路径、client_request_id、turn_id 或媒体整数 ID 和 UUID、HTTP 状态、错误摘要。请勿把渠道密钥、SSO key 或用户正文放入普通工单。

渠道接入验收清单

  • 全新 UID 可创建；重复创建不新增身份；不同 AppID 的冲突能正确提示。
  • 角色列表、角色详情可读；模型选择使用当前目录返回的配置名。
  • 创建房间后可读开场白；历史分页和附件展示正常。
  • 普通聊天能取到正文、消息 ID、turn_id 与 usage；已保存的同步失败轮次返回 HTTP 200、data.status=failed 和 error。
  • WS accepted / text / end 处理正确，累计正文不重复拼接；成功和失败轮次的同请求重放均返回原 turn_id 与原用量。
  • 本轮辅助与记忆调用归集；正常完成返回 final，网关核对单独进行。
  • pending 可补查；重复收到 HTTP / WS / 查询结果只扣一次。
  • 消息配图完成后可转视频；整数任务 ID 与图片 UUID 使用正确。
  • 消息语音、文本语音与所需相册能力均能取得任务终态。
  • 媒体完成记 1 次、失败不计次；渠道自己的重复通知处理幂等。
  • 需要剧本时，完成剧本会话、异步回复、历史与 token 核对。
  • 用户明细、App 汇总和渠道每日汇总能与自有账单对上。
  • 跨渠道、跨用户资源不可互查；密钥仅保存在渠道服务端。
  • 存量切换先抽样核对原房间、消息和记忆，再逐步放量。
推荐交付顺序：渠道后端跑通主聊天链路 → 接 usage 与幂等账单 → 接 WS 和历史 → 接所需媒体 / 剧本 → 双方核对每日用量 → 平台确认生产地址与开放时间后切换。