渠道对接完整版 · 依据 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

一个查询口径本轮用量、用户明细、渠道每日汇总

2.0 做了哪些升级

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

产品版本与请求路径分别看：本文的 AIGF-API 2.0 是产品名称；当前实际 HTTP 前缀仍是 /aigf/v1，WebSocket 也使用同一前缀。请直接使用本文地址，不要自行改成 /aigf/v2。

升级项	AIGF-API 1.0	AIGF-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）整理。示例为占位内容；具体环境是否已部署相应接口，以平台发布通知及联调结果为准。

先看整体链路

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

主链路 · 文字聊天编号表示推荐的接入顺序

STEP 01领取接入凭证渠道 API-Key
约定 AppID

STEP 02创建渠道用户传 user_id / username
以及 app_id

STEP 03选择角色与模型取得 character_id
按需选择 model_id

STEP 04创建 / 接续房间取得 chat_id
读取开场白与历史

STEP 05发起一轮聊天同步返回或 WS 流式
保存 turn_id

STEP 06用量确认与扣费usage.status = final
渠道自行计算费用

聊天媒体

已完成 AI 回复→消息配图→图片完成→图生视频；AI 回复也可生成语音

独立媒体

用户已创建→上传图片 / 选择风格与模板→相册生图 / 相册进阶视频 / 文本语音→成功记 1 次

剧本聊天

用户已创建→剧本列表→创建剧本会话→发消息 / 收流→按本轮 token 记账

AIGF-API 2.0：执行能力与记录消耗渠道：用户体验、价格、钱包与扣费

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

接入准备与身份约定

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

项目	当前约定
生产 Base URL	`https://api.aiaigirl.com/aigf/v1`；本文请求示例默认使用此地址。
UAT Base URL	`https://aigf-uat-api.abmylab.com/aigf/v1`
dev Base URL	`https://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

Base URL渠道 UIDAppID

只在本地更新文字，不发送请求、不保存密钥。示例中的角色和任务 ID 仍需替换为实际返回值。

跑通第一轮聊天

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

创建用户

由渠道提交自己的用户 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 不允许空白或首尾空格。重复创建不覆盖已有用户资料。

获取角色卡与可用模型

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

角色列表 / 详情 / 模型列表

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 不能代表整轮全部调用。

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

创建或接续角色房间

取得 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'

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

先用同步方式联调；需要逐字显示时再接 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 / model`	AI 正文 / 回复模型。整轮可能包含多个模型，计费使用 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"
        }
      ]
    }
  }
}

流式聊天与 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	渠道处理
`accepted`	`data` 中取得 turn_id、消息 ID；这是受理，不是生成或用量完成。
`text`	`body` 是累计正文，覆盖当前显示内容；不要把每一帧都追加一次。
`state_stream`	按模式显示状态；不在此阶段计算最终 token。
`end`	顶层含 `turn_id`、`client_request_id`、`status`、`usage`；聊天 channel 为 chat，剧本为 scripts。
`error / pong`	error 为错误通知；发送 `{"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，不能仅依赖推送保存最终账单。

本轮用量与渠道扣费

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

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 字段	含义	扣费判断
`status`	collecting 运行中；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 / 轮次终态为准。

图片、视频与语音

媒体均为异步任务：提交 → 保存任务 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=image`	type 可为 image / video / audio；提交任务使用返回的 key，不用展示名称。
模板	`GET /media/templates?type=image&category=pose`	type 为 image / video；category 可选 pose / action。
上传图片	`POST /upload/image`	multipart 文件字段名是 image；返回 URL。上传不计生成次数。
相册初级生图	`POST /media/{uid}/images/easy`	prompt、style 必填；ratio 默认 portrait，可为 landscape；character_id 可选。
相册进阶生图	`POST /media/{uid}/images/senior`	person_image_url、style 必填；pose_template_id 与 pose_image_url 至少一个；同传时模板优先。
相册进阶视频	`POST /media/{uid}/videos/senior`	person_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 '[email protected]'

相册初级生图 · 替换 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。
`resource`	image / video / audio。
`status`	以 completed / failed 判断终态；其他进行中状态等待后续查询。
`result`	成功资源地址列表；进行中通常为空，失败为空。不要对结果列表长度再次按任务计数。
`trace_id / uid / created_at`	追踪标识、所属用户、任务创建时间。

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

剧本聊天

与普通房间分开创建剧本会话；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。

历史记录与渠道每日对账

单用户查明细，全渠道查汇总；范围始终由当前 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、资源类型和任务终态。渠道无需保存用户正文来完成用量对账。

从 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 对账。

接口总表

下面的相对路径统一加在 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}/audio`	AI 消息语音；无请求体
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/styles`	type=image / video / audio
GET	`/media/templates`	type=image / video；category 可选
POST	`/upload/image`	multipart：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 '[email protected]' \
  -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 '[email protected]' \
  -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。删除入口会清理该房间的记忆，请将它作为用户明确执行的删除操作。

错误、重试与接入验收

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

常见响应与处理

正常 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；不要借用其他用户的资源。
409	AppID 绑定冲突、幂等参数冲突、同会话上一轮仍在运行	先查询原身份 / 原轮次 / 原任务。不是所有 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 和历史 → 接所需媒体 / 剧本 → 双方核对每日用量 → 平台确认生产地址与开放时间后切换。