版本:2026-10-06。读者:P02、P03、P08、P04 互动应用及现场展示程序的开发者。本文回答“我的页面在什么时机调用什么接口、传什么、拿到什么、下一步怎么走”。示例值均为占位内容,不是默认配置。
互动应用开发接入文档 / 开始接入
开始接入|先选择你的点位
先确认联调条件:路由存在不等于现在能走通整段流程。 当前后台生产配置发布仍受生成/结算等门禁限制;无已发布版本时,互动配置接口返回409。请先与AgentOS负责人确认测试门店、设备凭证、已发布配置是否可用,不能通过后台测试接口代替正式互动,也不能绕过发布门禁。
开始前向部署方领取:业务API Base URL、已绑定门店和点位的设备凭证、测试身份卡或有效会员临时凭据、可联调的配置版本。文档网站 http://aiva.docs.vavedigital.com 只是文档站,不是业务API地址 。
点位由设备凭证确定。P02和P08可以使用相同URL,但必须使用各自设备凭证;请求Body不能传pointId来切换点位。
后台配置、模型密钥、素材上传审核由AgentOS运营后台负责;客户端只读取下发内容。AIVA会员认证(AIVA 会员码由 AgentOS 服务端调 AIVA 识别)、作品同步到 AIVA 和集团全量数据同步由可信服务端负责;点位客户端不调用这些接口,AIVA服务端接口见《ONEID 会员对外接口文档》(api-docs/oneid.html)。
互动应用开发接入文档 / 开始接入
公用|连接与鉴权
错误响应中的 error 是说明文本,不是稳定业务码。下文按场景说明处理方式,不应在代码中硬编码匹配整句中文错误。
设备与用户会话请求头
设备凭证由AgentOS系统生成:每个互动点位一个互动客户端设备(设备编号 {门店编号}-{点位编号}-APP),密钥为256比特随机数(64位十六进制字符);新建门店时随互动点位自动生成,已有点位在后台“点位详情 → 设备接入”点“生成设备凭证”,在同一处默认脱敏显示、点“复制”取用、可“重新生成”(旧密钥立即失效)。一台设备绑定具体门店/点位。安全提醒 :凭证写在网页的配置文件里时,任何能打开该网页地址的人都能看到,可冒充本点位调用接口;建议互动网页地址只在门店专用局域网可访问(待部署方确认),发现泄露立即在“设备接入”重新生成。用户sessionToken来自扫码登录响应,两者不可互换;不使用后台Cookie,不在客户端持有集团应用密钥。退出后清除本地用户会话和用户画面,不把凭证写入日志。
curl -X POST "http://localhost:60662/api/identity/point-login" \
-H "Authorization: Bearer REPLACE_WITH_DEVICE_CREDENTIAL" \
-H "Content-Type: application/json" \
--data '{"kind":"card","code":"REPLACE_WITH_CARD_CODE"}'
互动应用开发接入文档 / 开始接入
隐私声明与体验须知(2026-10-12)
AIVA面基(含第二台)、AI音乐、灵感探索的点位配置增加 experienceNotice(不超过16000字),与 privacyNotice 分开编辑和保存。客户端依次展示两页;任一拒绝即退出,未登记文案拒绝开始,不用网页固定文案替代。文本随点位配置版本保存,无新增数据库迁移。
面基 Demo 的 config/start 返回两段文案。:id/consent 请求 {accepted, phase:'privacy'|'experience', storeId};先确认 privacy,再确认 experience,后者才放行照片处理。会话绑定本店及P02/P02B,确认事件记录配置版本。
灵感 Demo config 返回两段文案,沿用 privacy-consent → consent 的顺序;两步完成后才申请摄像头。
音乐台 GET /api/p03/notices(设备或已鉴权Demo)返回 {noticeVersion,privacyNotice,experienceNotice},按已鉴权租户/门店/实际点位读取。匿名或授权测试读最新保存版本,正式设备读active或单独明确发布告知的版本。POST /api/p03/chat/start 须带 {noticeVersion,privacyAccepted:true,experienceAccepted:true};文案更新或缺任一确认返回409,开始DJ会话时保存确认事件。文案版本变化时返回 code:MUSIC_NOTICE_UPDATED;客户端须返回重新读取两段文案并取得两次同意,不能重发旧版本或自动同意新版本。读取配置不清空本次已确认版本,退出或新身份/新体验时清除确认。本接口不替代正式互动API的授权策略确认,也不改变计费。
音乐台上机配置提供 GET/PUT /api/admin/stores/:storeId/points/:pointId/music-notices,支持P03目录的实际点位(包括D100)。PUT须有point:edit及prompt:edit权限,提交expectedRevision和两段文案;仅追加告知配置修订、标记noticePublished,保留其他配置,不发布旧版音乐流程。跨店/非音乐点位/旧版本拒绝写入,操作留审计。
更新部署后,运营需在各点位后台登记并保存两段文案;参考草稿按钮仅填空白项,须核对后人工保存,不自动写库。
面基扫码关联体验(2026-10-12)
P02/P02B的demo/start支持播控桥接userSession(转发为X-Identity-Session);后端先核对设备与用户会话,创建记录时事务复核并沿用卡AgentOSID。匿名入口不传用户会话,仍独立建档。客户端不得提交AgentOSID指定归属;失效/跨店会话拒绝,不回退匿名。作品、作答、对话记录归到当前卡,但不代表正式Token扣费、共享画像累计或跨次自动回忆已验收。扫码解析与内存令牌模块为公共基础,本轮只接面基,不改音乐及灵感的身份流程。
音乐台现场 Demo(2026-10-12)
已绑定且启用的P03/D100音乐设备无需临时后台测试授权。GET /api/p03/player-demo 返回 enabled:true, expiresAt:null;POST /api/p03/player-demo/start 签发绑定租户、门店、点位和设备的匿名Demo会话,后续请求通过原播控身份桥接传递。保留后台登记的空闲超时、真实模型用量、双告知版本校验和资源隔离;服务器重启后可直接重新开始,无需管理员登录。正式会员身份/Token结算与普通浏览器配对入口不变。旧后台 POST /api/admin/stores/:id/points/:pointId/player-demo 返回409提示临时授权已取消,不再伪称可授权或撤销。停用/解绑设备仍拒绝调用。
互动应用开发接入文档 / 互动点位
P02|AIVA面基 接口一览
AIVA面基(P02):访客扫码登录、授权拍照、作答5道单选题,服务端据此生成专属助手形象(单张图片)和一段介绍,组成“助手名片”;名片完成后可以文字或语音与助手聊天,助手回复可语音播报。本章先给出页面调用顺序,再说明AIVA面基特有的下发内容、作答格式和名片规则,最后是本章独有的语音接口(语音接口同样供AI图片生成使用)。授权、作答、文本/图片任务等公用接口的字段与错误见各自接口卡片。
页面操作与调用顺序
U 表示设备凭证 + 用户会话(X-Identity-Session),D 表示只用设备凭证。
AIVA面基下发内容
公共配置字段见读取互动配置 。AIVA面基的配置有以下特点:
后台发布配置时校验:必须正好5道单选题、每个选项只映射1个属性、每个属性都在“属性音色映射”中登记了音色(播报用)。助手为静态图片;聊天中的循环箭头是“重新回答”,不是重播。
五题作答格式
提交到提交作答 的Body:5道题各提交一个 optionId,ID 全部取自本次配置;AIVA面基不接受自由文本(text),也不接受客户端提交标签或权重。
{"answers":[
{"questionId":"q1","optionId":"q1_a"},
{"questionId":"q2","optionId":"q2_c"},
{"questionId":"q3","optionId":"q3_b"},
{"questionId":"q4","optionId":"q4_a"},
{"questionId":"q5","optionId":"q5_d"}
]}
成功返回(HTTP 200):
{"state":"ready","tags":["attr_curious","attr_calm"],"scores":[{"tag":"attr_curious","count":2},{"tag":"attr_calm","count":2},{"tag":"attr_bold","count":1}],"scoringRule":"p02-v2-q1-q4-q5-q2-q3"}
五题选出的属性少于两个时返回400,请运营核对题目映射;服务端不会补造第二个属性。
同一份答案原样重发返回第一次的结果并带 idempotentHit:true;已提交后改答案返回409,不能覆盖原作答。
每次作答的属性贡献全部累计进该用户的共享画像(重复作答累加),客户端无需另行提交。
名片与重新回答(2026-10-06确认)
名片按“体验”保存:一次体验只生成一张名片。名片完成后,同一体验内不能再生成形象,也不能改答案(409)。
用户点“重新回答”调用重新回答 :只在本次名片已完成(state 为 generated 或 chat)时可用;名片未完成时应调用结束体验 ;有模型任务正在运行或待核对时返回409。
重新回答会在同一事务内结束原体验(结束原因 user_restart)并新开一次体验。新体验需重新授权、拍照、作答五题、生成形象和介绍并完成名片,每次模型调用正常计费。
原体验的作答、属性贡献和名片都保留;新名片完成后,我的当前助手 返回新名片。
正式语音(AIVA面基与AI图片生成共用,2026-10-06)
以下接口(语音合成、查询语音任务、语音识别握手凭据、流式语音识别、上传录音识别)供AIVA面基、AI图片生成与AI车衣共创的设备使用。AI车衣共创:语音识别(流式或 2026-10-14 新增的上传录音识别 )用于自由描述;语音合成 2026-10-20 开通,2026-10-22 起可直接传一段文字合成(见语音合成 )。语音识别用哪种方式由点位配置里选的识别模型决定。其他点位调用返回400/403。AI图片生成的差异见P08章节。
计费规则:调用前按单次上限冻结 Token;成功后按实际用量结算、多余部分释放;厂商明确失败则冲正冻结;通信中断、超时或结果无法确认时记为“结果未知”,冻结保留,由运营人工核对后结算或释放,服务端不自动重试。用量折算出现小数 Token 时向上取整。
功能描述
把本次体验中一条已完成的助手消息合成为语音,同步返回音频(base64)。文字取自服务端已保存的消息,客户端只传消息编号。AIVA面基可播报介绍(intro,播报其中的 description)和聊天回复(chat);AI图片生成可播报旅程引导回复(guide);AI车衣共创可播报风格对话回复(style,2026-10-20 开通)——播的是返回里的 style_reply 那一句,不会把风格名和配色念出来(2026-10-22 起模型输出不符合约定时风格对话直接失败,没有可播的回复)。
AI车衣共创可直接传一段文字(2026-10-22 用户确认,共创工坊提出) :Body 传 text 代替 messageId(二选一),前端传什么就念什么,例如页面引导语或前端自己拼的句子。规则:
只开给AI车衣共创;AIVA面基、AI图片生成传 text 仍返回 400。
这段文字不送内容安全审核 (用户确认),由前端对传入内容负责;服务端只保存文字摘要(哈希),不保存原文。
其余与播报消息相同:须在已授权、未结束的体验中调用;去掉首尾空白后的字数不能超过 voice.tts_max_chars(超过返回 409 VOICE_TEXT_TOO_LONG,不截断);按字数计费;音色取车衣配置里登记的 voice.params.voice;同一 requestId 重发返回缓存音频、不重复计费,同一 requestId 换了文字返回 409。
只想播风格对话的回复时,直接在风格对话请求里带 speak:true 更省事(一次调用拿到文字和语音)。
计费:调用前按模型单次上限冻结;超过 voice.tts_max_chars 直接拒绝(不截断、不分段)。成功后按本次提交合成的字符数(去掉首尾空白后的字符数)结算;厂商若返回计费字符数则以厂商为准(当前火山接口不返回,billedCharacters 恒为 null)。
缓存与重发(2026-10-07确认):合成成功的音频加密缓存到本次体验结束。同一个 requestId 原样重发不会再次调用厂商、不再计费,返回第一次的结果和缓存的音频(idempotentHit:true)。体验结束(完成、放弃、撤回授权)后重发只返回任务状态,audio 为 null;需要再播放须换新的 requestId 重新合成并计费。缓存由定时任务删除。
调用时机:介绍或聊天回复的文本任务查询到 completed 之后。
请求参数Path / Body
AIVA面基、AI图片生成的 Body 只允许 requestId、messageId,带其他字段(包括 text)返回400;AI车衣共创只允许 requestId 加 messageId、text 其中一个。传 text 时响应里的 messageId 为 null,其余字段相同。
请求示例
curl -X POST "$BASE/api/interactions/ix_6f2c/tts" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "X-Identity-Session: $SESSION_TOKEN" \
-H "Content-Type: application/json" \
--data '{"requestId":"tts-intro-001","messageId":"msg_9a1d"}'
AI车衣共创直接传文字:
curl -X POST "$BASE/api/interactions/ix_6f2c/tts" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "X-Identity-Session: $SESSION_TOKEN" \
-H "Content-Type: application/json" \
--data '{"requestId":"tts-wrap-guide-001","text":"请说出你想要的车衣风格"}'
返回示例HTTP 200
首次合成成功:
{
"replayCached": true,
"taskId": "task_0b7e…",
"status": "completed",
"messageId": "msg_9a1d",
"usage": { "characters": 38, "billedCharacters": null },
"billing": { "status": "settled", "frozenAmount": 50, "settlementAmount": 4, "reason": null },
"audio": { "base64": "SUQzBAAAAAAA…", "mimeType": "audio/mpeg", "durationMs": 5120 },
"reason": null,
"note": "音频加密缓存至本次体验结束,同一requestId重放不再计费;体验结束后删除。结果未知时保留冻结待人工核对,不自动重试。"
}
同一 requestId 重发(体验未结束、缓存可用):
{
"taskId": "task_0b7e…",
"kind": "tts",
"status": "completed",
"messageId": "msg_9a1d",
"usage": { "characters": 38, "billedCharacters": null },
"providerRequestId": "3c1f…",
"failureKind": null,
"reason": null,
"billing": { "status": "settled", "frozenAmount": 50, "settlementAmount": 4, "reason": "success" },
"idempotentHit": true,
"audio": { "base64": "SUQzBAAAAAAA…", "mimeType": "audio/mpeg", "durationMs": 5120 },
"note": "本次体验内缓存的同一合成结果,重放不再计费(用户2026-10-07确认)。"
}
功能描述
查询一次语音合成或语音识别任务的状态、用量与计费,用于网络中断后确认结果、或核对计费。服务端不保存音频和识别原文,此接口的 audio 恒为 null;需要音频请用原 requestId 重发语音合成 (体验未结束时可取回缓存音频)。
请求示例
curl "$BASE/api/interactions/ix_6f2c/voice-tasks/task_0b7e" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "X-Identity-Session: $SESSION_TOKEN"
返回示例HTTP 200
语音合成任务:
{
"taskId": "task_0b7e…",
"kind": "tts",
"status": "completed",
"messageId": "msg_9a1d",
"usage": { "characters": 38, "billedCharacters": null },
"providerRequestId": "3c1f…",
"failureKind": null,
"reason": null,
"billing": { "status": "settled", "frozenAmount": 50, "settlementAmount": 4, "reason": "success" },
"audio": null,
"note": "语音任务不保存音频与识别原文,只提供状态、用量与计费。"
}
语音识别任务的 kind 为 asr、messageId 为 null、usage 为 { "audioSeconds": 6.4 }(厂商未返回时长时为 null)。
功能描述
浏览器建立 WebSocket 时不能附带 Authorization 与 X-Identity-Session 请求头,因此先用正常请求头调用本接口,换取一张一次性握手凭据,再把它放在流式语音识别 地址的 ticket 参数里。凭据只对本次体验和本台设备有效,60秒内有效,用一次即作废(握手失败也算用过)。非浏览器客户端可以不用凭据,直接带请求头升级。
本接口只核对设备、会话和体验归属;授权状态、名片是否完成、上限与模型登记等在握手时才检查。凭据保存在服务端内存中,服务重启后失效。
请求示例
curl -X POST "$BASE/api/interactions/ix_6f2c/asr-ticket" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "X-Identity-Session: $SESSION_TOKEN" \
-H "Content-Type: application/json" \
--data '{}'
返回示例HTTP 200
{
"ticket": "9f4c2b…(64位十六进制)",
"expiresAt": "2026-10-08T10:01:00.000+08:00",
"singleUse": true,
"path": "/api/interactions/ix_6f2c/asr"
}
功能描述
边说边识别:客户端通过 WebSocket 推送麦克风音频,服务端转发给语音识别厂商并实时回传识别文字。每一轮识别用一个新的 requestId。
升级前服务端依次核对:设备、会话、体验归属(租户、门店、点位、设备、用户、会话)、授权未撤回、体验未结束、点位在互动模式、阶段(AIVA面基须名片已完成;AI图片生成须在提交答案前且有允许自由文本的题目)、上限与模型登记,并在同一事务内创建任务、冻结 Token。任一项不通过直接拒绝升级,不连接厂商。连接期间每30秒重新核对会话与体验,失效即断开。
识别文字只返回客户端,服务端不保存原文、不送模型。 客户端拿到 final.text 后自行作为聊天内容提交(AIVA面基:创建文本任务 purpose:"chat";AI图片生成:purpose:"guide"),由文本入口做内容安全审核和计费。识别为空时不要提交。
计费:握手成功即冻结;收到厂商最终结果后按厂商返回的音频时长(秒)结算。
请求参数Path / Query / 消息
单轮最多接收 voice.asr_max_sec 秒音频(按 32000 字节/秒计算),超出部分不转发。
请求示例
// 1. 换一次性凭据($BASE 为 https 地址)
const t = await fetch(`${BASE}/api/interactions/${interactionId}/asr-ticket`, {
method: 'POST',
headers: { 'Authorization': `Bearer ${DEVICE_CREDENTIAL}`, 'X-Identity-Session': SESSION_TOKEN, 'Content-Type': 'application/json' },
body: '{}'
}).then(r => r.json());
// 2. 建立连接(https 换成 wss)
const ws = new WebSocket(`${BASE.replace(/^http/, 'ws')}${t.path}?requestId=${encodeURIComponent('asr-chat-003')}&ticket=${t.ticket}`);
ws.binaryType = 'arraybuffer';
ws.onmessage = (e) => {
const m = JSON.parse(e.data);
if (m.type === 'ready') startMicrophone(pcm => ws.send(pcm)); // 每200ms一包PCM
if (m.type === 'final') submitChat(m.text); // 作为聊天文本提交
};
// 3. 用户说完
stopMicrophone(); ws.send('done');
返回示例服务端消息,JSON 文本帧
{ "type": "ready", "taskId": "task_51ac…", "maxSeconds": 30, "audio": { "format": "pcm", "rate": 16000, "bits": 16, "channel": 1 } }
{ "type": "text", "text": "今天适合去", "definite": false, "utterances": [ { "text": "今天适合去", "definite": false } ] }
{ "type": "limit", "maxSeconds": 30, "message": "已达到登记的单次识别最长秒数,停止接收音频并等待最终结果" }
{ "type": "final", "taskId": "task_51ac…", "text": "今天适合去哪里玩?", "utterances": [ { "text": "今天适合去哪里玩?", "definite": true } ], "audioSeconds": 6.4, "billing": { "status": "settled", "frozenAmount": 30, "settlementAmount": 2, "reason": null } }
{ "type": "error", "taskId": "task_51ac…", "outcome": "unknown", "message": "厂商连接在最终结果前关闭,保留冻结待核对", "billing": { "status": "unknown", "frozenAmount": 30, "settlementAmount": null, "reason": null } }
{ "type": "notice", "message": "识别尚未就绪,就绪前的音频未转发" }
错误情况
握手被拒时,服务端直接返回 HTTP 状态行并关闭连接,没有响应正文和 code ;浏览器只能看到 onerror 与关闭码 1006,看不到具体状态,请先确认前置条件(已授权、名片已完成、请求号未用过)。
功能描述
录完整段再识别(2026-10-14,按共创工坊开发方案):客户端把整段录音作为 WAV 文件一次上传,服务端调用火山“录音文件识别极速版”,一次返回识别文字 。与流式语音识别 同一地址:POST 是上传方式,WebSocket 升级是流式方式,两者并存。
用哪种方式由后台点位配置里选的语音识别模型决定:选“录音文件识别极速版”只能上传,选“大模型流式语音识别”只能流式;用错方式返回 409 VOICE_MODEL_MISMATCH,不会自动换用另一种。
前置核对与流式相同:设备、会话、体验归属、授权未撤回、体验未结束、阶段(AIVA面基须名片已完成;AI图片生成须在提交答案前且有允许自由文本的题目;AI车衣共创须开放AI共创、已授权且没有运行中的任务)、单次最长秒数与模型登记。
录音时长超过后台登记的“单次语音识别最长秒数”(voice.asr_max_sec)直接返回 400 VOICE_TOO_LONG,不调用厂商、不冻结 Token ;客户端应按最长秒数控制录音。
识别文字只返回客户端,服务端不保存原文、不送模型。 客户端拿到 text 后自行提交(AIVA面基 purpose:"chat";AI图片生成 purpose:"guide";AI车衣共创 purpose:"style"),由文本入口做内容安全审核和计费。识别为空(text 为空字符串,silent:true 表示厂商判定为静音)时不要提交。
计费:核对通过后冻结;厂商返回结果后按厂商返回的音频时长(秒)结算。
请求参数
请求体上限 8 MB(传输保护);实际可识别时长以 voice.asr_max_sec 为准。
请求示例
const form = new FormData();
form.append('requestId', 'asr-style-003');
form.append('audio', wavBlob, 'speech.wav'); // PCM 16kHz/16bit/单声道 WAV
const r = await fetch(`${BASE}/api/interactions/${interactionId}/asr`, {
method: 'POST',
headers: { 'Authorization': `Bearer ${DEVICE_CREDENTIAL}`, 'X-Identity-Session': SESSION_TOKEN }, // 不要手动设 Content-Type
body: form
}).then(r => r.json());
// r.text → 作为风格对话 / 聊天文本提交
curl -X POST "$BASE/api/interactions/$IX/asr" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" -H "X-Identity-Session: $SESSION_TOKEN" \
-F requestId=asr-style-003 -F "audio=@speech.wav;type=audio/wav"
返回示例
{ "taskId": "task_51ac…", "text": "我想要炫酷一点的风格", "utterances": [ { "text": "我想要炫酷一点的风格" } ], "silent": false, "audioSeconds": 3.2, "billing": { "status": "settled", "frozenAmount": 600, "settlementAmount": 32, "reason": null } }
错误情况
错误响应为 {"error":"…","code":"…"};已创建任务的错误另带 taskId 与 billing。
功能描述
2026-09-28 首批问卷阶段留下的公开接口:按门店读取旧问卷表中已发布的AIVA面基问卷。正式互动的题目以读取互动配置 下发的 questions 为准 ,本接口读取的旧问卷表与正式配置不同源,后台旧问卷编辑页已改为跳转到点位配置页,返回内容可能已过时。新开发的客户端不要调用;是否下线(待确认)。
请求示例
curl "$BASE/api/p02/questions?storeId=CQ-GUANGHUAN"
返回示例HTTP 200
{
"storeId": "CQ-GUANGHUAN",
"pointId": "P02",
"version": 3,
"publishedAt": "2026-09-28T08:00:00.000Z",
"questions": [ { "id": "q1", "title": "题目示例", "options": [ { "id": "q1_a", "label": "选项示例", "detail": "补充说明" } ] } ]
}
互动应用开发接入文档 / 互动点位
P03|车机互动台 · AI音乐 接口一览
公开网页 Demo(2026-10-12 用户确认)
此入口独立于下方正式设备与会员协议,不代表正式 Token 结算验收。公开双屏入口为 /?debug=multiscreen&storeId=<门店编号>。浏览器点击开始时 POST /api/p03/public-demo/session,JSON { "storeId": "CQ-GUANGHUAN" },无需登录、配对码或临时授权。点位须已启用且模型/告知文案就绪;响应签发 HttpOnly、SameSite=Strict 会话 Cookie,后续 /api/p03/* 沿用原 Demo 调用,资源按随机会话隔离。真实模型调用有用量费用;后台与设备权限不开放。
灵感探索公开五屏入口为 /inspiration/?debug=multiscreen&storeId=<门店编号>,不传配对码。总览自动建立仅本窗口使用的同步通道,POST /api/p08/demo/start 传 publicPreview:true,体验配置快照保存该标记;公开体验不广播到现场硬件屏,现场重连也不选取公开体验。用户主动确认隐私告知、浏览器摄像头/麦克风权限仍保留。既有打印提示不等于真实打印。
2026-10-14 灵感探索最终图分层:点位配置 journeyLayers.enabled=true 时,journeyImage 须选 Seedream 5.0 Flash 或 Pro。先生成完整场景,再以该图为唯一输入拆分底图和最多16个透明PNG图层;两次调用各有任务号与用量,不自动重试或退回单图。拆分档位独立配置为 1K / 1.5K / 2K / auto,不接受自定义宽高。接口原有 imageUrl、assetId 指向服务端按 bounding_box.absolute 与 z_index 合成的最终JPEG(不包含UI文字);五屏、打印和小程序共用此作品。分层结果额外返回 sourceTaskId、decompositionUsage、layerManifest(持久资产地址、底图尺寸、各层坐标与层级)。原始场景及图层为非最终资产,不打印、不推小程序;运营在体验记录的 answers.journeyLayers 查看清单。先部署新后端,再应用分层配置;旧体验快照不改变。像素合成使用独立worker,运行时需Node>=20.9.0。此链路仍为Demo语义,不宣称正式Token结算。
AI音乐(P03)的访客在车机互动台上先选曲风、再选人声,讲两轮自己的故事,由文本模型写出歌词与“音乐DNA”,访客可以手动改词并确认,最后由后台配置的豆包音乐模型生成正式歌曲,同时生成一张封面。本章接口都由 AI音乐点位客户端调用,鉴权均为设备凭证 + 用户会话(U);Path 中的 :id 为创建体验返回的 interactionId,必须属于当前设备和当前登录用户。AI音乐旧链路 /api/p03/*(数字DJ对话、故事对话、旧生成任务等)在服务端继续保留,但不属于本文档的正式接入协议,新客户端不要调用。
页面操作与调用顺序
改曲风或人声:再次保存选择后,本次体验回到“未确认”,须重新确认,并重新生成歌词(新的付费文本任务),旧歌词不能再确认。重新生成歌词:用新的 requestId 再创建一次 purpose=lyrics 文本任务,正常计费。音乐明确失败(failed)后,本次体验回到可提交状态,可用新的 requestId 再提交一次音乐任务(重新计费);结果未知(unknown)时不能这样做。
曲风人声与歌词修订规则
功能描述
保存访客在曲风页、人声页的选择。分两次调用:曲风页只传 genreId;人声页再传 genreId+timbreId(曲风必须重复携带)。每次保存都生成新的修订号,并把本次体验的“已确认”状态清掉,之后需重新确认曲风人声 。
调用时机:授权之后、提交故事之前;故事提交后也可以修改(修改后须重新确认并重新生成歌词)。只有本次体验已授权、且处于“作答中”或“已就绪”(没有运行中的任务、音乐未完成)时可以保存。同一个请求号原样重发不会重复执行,返回第一次的结果。
请求示例
curl -X PUT "$BASE/api/interactions/ix_example/music-selection" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "X-Identity-Session: $SESSION_TOKEN" \
-H "Content-Type: application/json" \
--data '{"requestId":"sel-20261008-0002","expectedRevision":1,"genreId":"genre_folk","timbreId":"timbre_female_warm"}'
返回示例HTTP 200
{
"revision": 2,
"design": {
"genreId": "genre_folk",
"genre": "民谣",
"genreModelValue": "Folk",
"timbreId": "timbre_female_warm",
"timbre": "温暖女声",
"timbreModelValue": "Warm",
"stage": "preferences-complete"
},
"state": "questions",
"confirmed": false
}
同一请求号原样重发时返回:
{ "revision": 2, "design": { "genreId": "genre_folk", "stage": "preferences-complete" }, "idempotentHit": true }
功能描述
读取本次体验当前的曲风人声选择、修订号和是否已确认。用于返回页面恢复界面,或保存时遇到修订冲突后重新取最新修订号。
请求示例
curl "$BASE/api/interactions/ix_example/music-selection" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "X-Identity-Session: $SESSION_TOKEN"
返回示例HTTP 200
{
"revision": 2,
"design": {
"genreId": "genre_folk",
"genre": "民谣",
"genreModelValue": "Folk",
"timbreId": "timbre_female_warm",
"timbre": "温暖女声",
"timbreModelValue": "Warm",
"stage": "preferences-complete"
},
"confirmed": true
}
功能描述
访客确认最新的曲风人声选择。只有已授权、已选人声、故事已提交(体验状态为 ready)且所传修订号是最新时才能确认。确认之后才能生成歌词;确认本身不调用任何模型、不计费。已确认的情况下重复调用仍返回确认成功。
请求示例
curl -X POST "$BASE/api/interactions/ix_example/music-selection/confirm" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "X-Identity-Session: $SESSION_TOKEN" \
-H "Content-Type: application/json" \
--data '{"revision":2}'
返回示例HTTP 200
{ "confirmed": true, "revision": 2 }
功能描述
读取本次体验的全部歌词修订,最新的排在最前。歌词修订由两种方式产生:歌词文本任务(purpose=lyrics)成功后由服务端自动写入;访客手动修改歌词 。只能确认最新一条。
请求示例
curl "$BASE/api/interactions/ix_example/lyrics" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "X-Identity-Session: $SESSION_TOKEN"
返回示例HTTP 200
{
"items": [
{
"revision": 1,
"selection_revision": 2,
"source_task_id": "task_2b8f…",
"result": {
"title": "晚风回家路",
"lyrics": "[verse]\n路灯一盏一盏亮起\n……\n[chorus]\n……",
"theme": "归途",
"mood": "温暖",
"scene": "夜晚的城市公路",
"dna": { "persona": "夜行的讲述者", "description": "……", "keywords": ["归途", "灯光", "陪伴"] }
},
"confirmed_at": null,
"created_at": "2026-10-08T06:00:00.000Z"
}
],
"note": "只确认最新歌词修订;修改或重新生成后须重新确认,确认不提交音乐模型。"
}
还没有歌词时 items 为空数组。
功能描述
访客在歌词页手动修改曲名和歌词,生成一条新的歌词修订(未确认)。主题、情绪、场景、音乐DNA 和所属曲风人声修订沿用上一条,不调用生成模型、不计费。
因为改后的曲名和歌词确认后会发给音乐模型,保存前会把“曲名+歌词”送内容安全审核:未通过返回422,审核未配置或不可用返回503,都不写入修订。同一个请求号原样重发不会重复执行(也不再审核),返回第一次的结果。
调用时机:至少已有一条由歌词任务生成的歌词,且没有运行中的任务、音乐尚未完成。
请求参数Path / Body
只接受以上四个 Body 字段,多传任何字段返回400。
请求示例
curl -X PUT "$BASE/api/interactions/ix_example/lyrics" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "X-Identity-Session: $SESSION_TOKEN" \
-H "Content-Type: application/json" \
--data '{"requestId":"lyr-edit-0001","expectedRevision":1,"title":"晚风回家","lyrics":"[verse]\n路灯一盏一盏亮起\n[chorus]\n晚风陪我回家"}'
返回示例HTTP 200
{
"revision": 2,
"confirmed": false,
"result": {
"title": "晚风回家",
"lyrics": "[verse]\n路灯一盏一盏亮起\n[chorus]\n晚风陪我回家",
"theme": "归途",
"mood": "温暖",
"scene": "夜晚的城市公路",
"dna": { "persona": "夜行的讲述者", "description": "……", "keywords": ["归途", "灯光", "陪伴"] }
}
}
同一请求号原样重发时返回:
{ "revision": 2, "idempotentHit": true }
功能描述
访客确认最新一条歌词。必须同时满足:所传修订是最新歌词修订、这条歌词所属的曲风人声修订就是当前最新修订、且曲风人声已确认。确认只做登记,不会提交音乐模型;提交音乐时服务端会再次核对。已确认的修订重复确认仍返回成功。
请求示例
curl -X POST "$BASE/api/interactions/ix_example/lyrics/confirm" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "X-Identity-Session: $SESSION_TOKEN" \
-H "Content-Type: application/json" \
--data '{"revision":2}'
返回示例HTTP 200
{ "revision": 2, "confirmed": true, "note": "尚未提交音乐模型;音乐任务必须再次校验本修订。" }
功能描述
用已确认的歌词和曲风人声提交正式音乐生成。服务端在同一事务里登记音乐任务、按后台登记的单次冻结上限冻结 Token,并同时登记第一次封面任务及其冻结,然后在后台把请求提交给豆包音乐模型(GenSongForTime),只提交一次。接口立即返回 taskId,客户端用查询音乐任务 看进度。
提交前服务端会逐项核对:本次体验已授权且授权未撤回、曲风人声已确认、所传两个修订号都是最新且歌词已确认、没有运行中的任务、点位处于可接收互动的状态,以及音乐模型、封面模型、查询间隔与最长等待、作品存储与留存等配置都已登记。任何一项不满足都直接拒绝,不冻结、不提交厂商。提交内容与时长算法见下方“正式音乐提交内容与时长”。
同一个请求号原样重发不会重复执行,返回第一次的 taskId(status=existing)。网络错误时请用原请求号重发或直接查询原 taskId,不要换新请求号。
请求参数Path / Body
只接受以上三个 Body 字段,多传任何字段返回400。
请求示例
curl -X POST "$BASE/api/interactions/ix_example/music-tasks" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "X-Identity-Session: $SESSION_TOKEN" \
-H "Content-Type: application/json" \
--data '{"requestId":"music-0001","lyricsRevision":2,"selectionRevision":2}'
返回示例HTTP 200
{
"taskId": "task_5d0c2f7e-…",
"status": "queued",
"idempotentHit": false,
"note": "任务已持久化并冻结;查询原taskId。结果未知时只核对原厂商任务,不用新requestId重新生成。"
}
功能描述
按 taskId 读取音乐任务的当前状态、失败分类、封面状态与 Token 冻结结算情况。只读,不触发任何厂商调用;服务端自己会按后台登记的查询间隔查询原厂商任务。轮询直到 status 不再是 prepared/dispatched/submitted;音乐完成后封面可能仍在生成,继续轮询到 cover.status 不是 pending。
状态与提示码的含义见下方“音乐任务状态与提示码”。completed 表示音频已保存为作品(2026-10-13 起以原文件存入公开读的对象存储;音频不在内容安全审核范围,保存即为已通过,可直接取件)。
请求示例
curl "$BASE/api/interactions/ix_example/music-tasks/task_5d0c2f7e-example" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "X-Identity-Session: $SESSION_TOKEN"
返回示例HTTP 200
{
"taskId": "task_5d0c2f7e-…",
"status": "completed",
"code": null,
"lyricsRevision": 2,
"selectionRevision": 2,
"providerTaskRecorded": true,
"failure": null,
"reason": null,
"assetId": "asset_9a1f…",
"submittedAt": "2026-10-08T06:00:02.000Z",
"deadlineAt": "2026-10-08T06:10:02.000Z",
"checkedAt": "2026-10-08T06:01:32.000Z",
"cover": { "status": "completed", "assetId": "asset_3c7e…", "reason": null, "placeholder": false },
"billing": { "status": "settled", "frozenAmount": 300, "settlementAmount": 124, "reason": "success" },
"note": "completed不等于审核通过;unknown只能核对原厂商任务,不用新requestId重新生成。"
}
厂商明确失败时的示例片段:
{
"status": "failed",
"code": "P03_MUSIC_CONTENT_REJECTED",
"failure": { "kind": "moderation", "errorNumber": "300062" },
"reason": "内容未通过审核:……",
"assetId": null,
"billing": { "status": "reversed", "frozenAmount": 300, "settlementAmount": 0, "reason": "failed" }
}
结果未知时的示例片段:
{
"status": "unknown",
"code": "P03_MUSIC_RESULT_UNKNOWN",
"providerTaskRecorded": true,
"reason": "超过已登记最长等待仍未确认结果;保留冻结,只能按原厂商TaskID核对,不重新提交",
"billing": { "status": "unknown", "frozenAmount": 300, "settlementAmount": null, "reason": "厂商结果未知;保留冻结,核对原任务,不自动重试" }
}
billing 只反映音乐本身;封面每次尝试单独冻结与结算,不在此显示。
功能描述
在结果未知(unknown)或作品保存待处理(save_pending)时,让服务端再核对一次原任务。按当前状态处理:
请求示例
curl -X POST "$BASE/api/interactions/ix_example/music-tasks/task_5d0c2f7e-example/check" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "X-Identity-Session: $SESSION_TOKEN" \
-H "Content-Type: application/json" \
--data '{}'
返回示例HTTP 200
返回结构与查询音乐任务 完全相同,例如核对后仍未确认:
{
"taskId": "task_5d0c2f7e-…",
"status": "unknown",
"code": "P03_MUSIC_RESULT_UNKNOWN",
"lyricsRevision": 2,
"selectionRevision": 2,
"providerTaskRecorded": true,
"failure": null,
"reason": "超过已登记最长等待仍未确认结果;保留冻结,只能按原厂商TaskID核对,不重新提交",
"assetId": null,
"submittedAt": "2026-10-08T06:00:02.000Z",
"deadlineAt": "2026-10-08T06:10:02.000Z",
"checkedAt": "2026-10-08T06:12:40.000Z",
"cover": { "status": "completed", "assetId": "asset_3c7e…", "reason": null, "placeholder": false },
"billing": { "status": "unknown", "frozenAmount": 300, "settlementAmount": null, "reason": "厂商结果未知;保留冻结,核对原任务,不自动重试" },
"note": "completed不等于审核通过;unknown只能核对原厂商任务,不用新requestId重新生成。"
}
音乐任务状态与提示码
查询原厂商任务号出错时,服务端在后台登记的最长等待(music.max_wait_sec,从厂商受理起算)内继续按原任务号查询;超过最长等待仍无确定结果才记为 unknown。服务重启时:尚未提交厂商的任务冲正冻结并记 cancelled;已开始提交但没拿到厂商任务号的记 unknown;已有厂商任务号的继续查询。任何情况都不会重新提交或重新生成。
正式音乐提交内容与时长
模型:使用后台为 AI音乐绑定的豆包音乐模型,型号/版本按后台登记原样提交,不设版本白名单;只接入按时长计费的 GenSongForTime。
提交字段:Lyrics(已确认歌词)、ModelVersion、Duration、SkipCopyCheck=false(保留厂商歌词版权检测)、Genre/Timbre(所选曲风人声的厂商参数,须在官方枚举内)、Prompt(后台“音乐生成要求”+曲风、人声、主题、情绪、场景)。厂商按版本忽略不支持的字段。
时长(2026-10-06 确认沿用旧原型完整公式):
目标秒数 = 145 + 故事长度加成 + 曲风偏移,限制在 30—175 秒。故事长度加成 = 本次全部故事回答(去空白)字数 ÷ 4,四舍五入,最多 25 秒。曲风偏移按曲风中文名:民谣 +15、爵士 +12、R&B +8、国风 +8、流行 0、摇滚 −5、电子 −8、嘻哈 −12,其他名称为 0。
最终秒数 = 已确认歌词字数(去空白,不计以 [ 开头的结构标记行)÷ 1.6,限制在“目标 −15%(不低于 30 秒)”到“目标 +25%(不高于 180 秒)”之间,四舍五入为整数;歌词字数为 0 时取目标秒数。
曲风偏移按后台配置的显示名称匹配,名称不是上述八种时偏移为 0。
封面
随音乐任务同时生成一张封面:使用 AI音乐绑定的图片模型,提示词为“生成原创歌曲封面,不复刻歌手形象或唱片封面”+后台“歌曲封面的整体要求”+歌词的主题、情绪、场景。每次尝试都是一次独立的正式单图任务,单独冻结、按真实张数结算。
第一次失败后自动重试一次;第二次仍失败(或重试无法登记),cover.status=placeholder,界面显示自身占位图(服务端不生成占位图片),并发出站内告警 content.cover_failed 给内容运营和门店运营;告警发送失败只记录,不影响占位处理。音乐失败或取消时未开始的封面不再生成(skipped)。封面失败不影响音乐作品保存。
结算
音乐按调用时快照的兑换比例与厂商返回的成品时长(秒)计算,小数 Token 向上取整。厂商未返回时长或费用超过冻结上限时,音频照常保存,但任务记为 unknown、冻结保留(billing.status=review),由运营人工处置。明确失败、提交前取消冲正冻结;unknown 不自动退款、不自动重试。
P03剩余边界
内容安全代码已接入,但火山内容安全尚未开通、未真实联调:在登记前,手动改词、含自由文本的故事与封面都不送审、按通过处理,封面作品标记“未审核”(2026-10-13 确认)。
可冻结 Token 不足时,提交音乐任务返回 409 code:"TOKEN_INSUFFICIENT"(2026-10-08 修复,原为 500)。
音乐结果为 unknown 时,本次体验保持“运行中”:不能改词、不能再提交音乐;访客可以用结束体验 以“放弃”结束(2026-10-08 修复,此前返回409),冻结的 Token 留待后台人工核对。
服务端不强制“恰好两轮”故事,故事题数以后台配置的 questions 为准,须一次提交完整题集。
音乐作品集团同步未接入;真实音乐厂商、存储、数据库端到端未联调(沿用原文结论,本轮未重新核对,待确认)。
不要把旧原型、后台模型测试接口或旧链路 /api/p03/* 当作正式客户端协议。10月6日失败方案已批准:审核/厂商失败分类、未知只核对原任务不重试、停止本地模板歌词及话术,明确失败按已批准账本冲正。
互动应用开发接入文档 / 互动点位
P08|AI图片生成
AI图片生成(P08)引导用户回答旅程问题,每答一题由助手实时回复,答完后点击“出发”,用用户照片和全部回答生成一张旅程图片。本点位没有专属接口,全部使用公用的互动会话、正式任务和语音接口;本章说明调用顺序与 AI图片生成特有的规则。
页面操作与调用顺序
自由文本与选择题
只在该题 allowText=true 时显示自由输入能力。每题提交 optionId 或 text 二者之一;text 非空、最多 2000 字符。题目和选项来自本次配置,用户输入目的地不等于可以任意增加新 questionId。
{"answers":[{"questionId":"configured_choice_question","optionId":"configured_option"},{"questionId":"configured_text_question","text":"用户明确输入的旅程想法"}]}
此例仅演示两类答案混用;实际题数、ID 和自由文本开关均以配置为准。成功返回 {state:"ready",tags:[...]}。每条 text 在写入前送内容安全审核:未通过 422 CONTENT_REJECTED、未配置/不可用 503 MODERATION_*,整份答案均不写入(见“内容安全 ”)。
旅程引导回复(2026-10-06确认)
每步“助手回复”由模型实时生成,走 创建文本任务 并计费(冻结/结算同公用规则)。请求 Body:
只能在授权后、提交全部 answers 之前、且没有运行中任务时调用(状态为 questions);生成期间状态为 running,完成或明确失败后回到 questions 再继续作答或提交 answers。answers 最终一次性提交的规则不变。结果为 unknown 时体验停留在 running,不能继续作答(见 任务状态与 Token 冻结 )。
服务端从配置读取题目文本,使用 AI图片生成配置的“旅程引导回复”说话方式(chatPrompt)与 chat 绑定模型;上下文为本次体验此前已完成的引导步骤(题目与回答,含自由文本)及回复,并注入结构化记忆(条数未登记时 409);配置指定了知识库时附带知识全文。
结果在 查询文本任务 的 response 中,为纯文本,不截断;模型未返回正文按“结果不符合约定”记 unknown 并保留冻结,不补固定文案。同一题可用新请求号再次调用,每次独立计费。
引导步骤会出现在 查询体验 的 messages 中(purpose=guide,user_text 为该步题目与回答的 JSON 文本)。
出发与生成旅程图片
先提交全部答案,再调用 确认输入 (出发),之后调用 创建图片任务 ,photo 必填(PNG/JPEG data URL,不超过 5MiB)。未确认出发返回 409。
照片在建任务前送内容安全审核,审核期间以临时对象存在,审核结束即删除,不保存为作品。生成提示词由后台配置与本次各题回答(选项文本或自由文本原文)组成。
生成图审核通过:任务 completed,作品自动审核通过可取件(子类 journey),体验状态变为 generated,本次体验不能再生成第二张。审核未通过:任务 failed、冻结冲正、不保存,体验回到 ready,用户可用新请求号再次生成(重新计费)。未登记内容安全或审核服务临时不可用:按通过处理,同“审核通过”,作品标记“未审核”(2026-10-13 确认)。
AI图片生成正式语音(2026-10-06,A13)
接口、计费与错误同 AIVA面基正式语音。差异:
语音合成 只能合成本次体验已完成的旅程引导回复(purpose=guide)。音色取 AI图片生成配置中后台登记的 voice.params.voice(助手播报音色);未登记返回 409 VOICE_NOT_CONFIGURED,不使用默认音色或模型绑定上的音色。
语音识别 仅在授权后、提交全部 answers 之前(状态 questions),且本次配置有允许自由文本的题目时可用;final.text 由客户端作为该题 text 提交到旅程引导回复(purpose=guide),届时做内容安全审核。
尚未验收
配置中的 stages 为 consent, photo, questions, departure-confirmation, focus, generation,它是页面流程清单,不代表都有对应接口:拍照没有单独上传接口,专注阶段(focus)没有采集或事件接口。专注阶段实际采集、终端 UI 和真实模型联调均未验收。
互动应用开发接入文档 / 互动点位
P04|共创工坊 · AI车衣共创 接口一览
AI车衣共创(P04):访客授权后选择“AI共创”或“DIY涂鸦”。AI共创(2026-10-10 Agent 配置):前端从全部已启用风格中随机显示5个,用户点选,或说话/打字由模型从全部已启用风格中替用户选一个(2026-10-21 起不在库中时原样返回,服务端不替换);配色由用户点选(前端从该风格全部配色中随机显示4种);确认后服务端按三步生成:文本模型写绘图提示词 → 纸膜(参考图=纸膜模板)→ UV 贴图(参考图=纸膜结果;2026-10-14 起原“侧身效果图”改为 UV 贴图,Pad 做 360° 车模查看)。打印的是纸膜图。DIY 的取色、笔刷、图案与 3D 涂画由前端控制;2026-10-15 起点“确认打印”时前端上传手绘 UV 图与底色,由服务端合成纸膜打印图 (底色非白色时先由模型改色),既是作品也可打印。打印(2026-10-11 起)改由独立的“作品打印台”完成:用户在打印台扫码查看并打印自己的作品,互动 Pad 不再发起打印。本章说明页面调用顺序、车衣配置、DIY数据结构,以及本章独有的接口。
AI车衣共创不提交问卷 answers,也不调用通用的确认输入 (会返回400)。2026-10-14 起一个按钮一次调用 :风格对话一次返回风格;“去生成”一次提交风格配色并开始生成;DIY“确认打印”一次上传手绘 UV 与底色(2026-10-15 起服务端合成,立即返回任务号)。原“保存 / 读取 / 确认车衣方案”三个接口已删除。风格对话(2026-10-10 确认,2026-10-21 调整):无论用户输入什么都由模型从库中选一个风格;模型给的风格不在库中时原样返回 (带模型原文 raw),由前端自己决定怎么处理,服务端不再替换成兜底风格,见风格对话 。
页面操作与调用顺序
车衣配置与素材
读取互动配置 对AI车衣共创除公共字段外另返回:
assets 保留下划线命名。底图、图案或资源包素材缺失、未审核、不在本门店范围或没有 HTTPS 地址时,读取配置直接报错;客户端不能改用其他图片替代。
DIY数据结构
2026-10-15 起 DIY 确认打印不再提交 design :服务端按上传的底色保存方案 {mode:"diy",baseColor,strokes:[],stickers:[]},下表仅作历史结构说明。所有坐标、大小都是相对画布的 0—1 比例。
颜色大小写不限,服务端统一保存为大写。
体验结束(完成、放弃、撤回授权)后,服务端清除方案明细:AI方案只保留风格与颜色,DIY方案只保留 baseColor,并带 cleared:true;笔画、图案不再保留。
功能描述
登记客户端能观察到的操作事件(E01—E11),用于统计分析。服务端只接受白名单字段,不接受原始文字、涂鸦轨迹、URL 等内容;事件不改变生成任务、计费或打印状态,“打印发送”事件也不代表后台已接收或已出纸。各事件的业务含义以AI车衣共创埋点设计为准(待确认)。
同一个 requestId 连同相同内容原样重发不会重复登记,返回第一次的事件编号。
字段取值:mode/fromMode/toMode 为 ai、diy;source 为 preset、voice、text、start、switch;stage 为 preset、style、color、effect;observedResult 为 started、success、failed、cancelled、unknown;tool 为 color、brush、opacity、pattern_select、pattern_apply、rotate、undo、reset;exitType 为 manual、after_send、idle;action 为 continue、exit;count 为正整数,durationMs 为非负整数;printInitiated 为布尔值;其余字段为 1—64 位字母、数字或 _.:- 组成的编码。
请求示例
curl -X POST "$BASE/api/interactions/ix_7d3e/events" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "X-Identity-Session: $SESSION_TOKEN" \
-H "Content-Type: application/json" \
--data '{"requestId":"evt-0007","code":"E09","occurredAt":"2026-10-08T10:00:00+08:00","payload":{"creationId":"c1","tool":"brush","count":3}}'
返回示例HTTP 200
{
"eventId": "obs_4be1…",
"received": true,
"source": "point",
"note": "只登记客户端可观察事件。打印发送不代表后台接收、送达或实际出纸;任务状态以ai_task为准。"
}
同一 requestId 原样重发:{"eventId":"obs_4be1…","idempotentHit":true}。
风格对话(文字 / 语音)
🔴 2026-10-22 用户确认(共创工坊提出,docs/develops/42):默认风格与自由输入分开。
默认风格 :wrap.styles 里的风格与配色是共创工坊上的默认选项,用户点选时直接用,去生成传 styleId+colorId,不调大模型。
自由输入 :用户说话或打字时,一律由大模型现编一个风格名和 4 个配色(名称+色值) ,即使用户说中默认风格名(如“赛博朋克”)也现编一套;不再从风格库里匹配(取代 2026-10-10 D1/D2 与 2026-10-21 的“原样返回库匹配结果”)。
后台可关闭自由输入(wrap.freeStyle.enabled=false,freeDescription="disabled"),关闭后风格对话返回 409。
文字:调用 创建文本任务 ,Body {"requestId","purpose":"style","text"},text 1—2000 字;用户文字先送内容安全审核。可在授权后、没有运行任务时调用(state 为 questions、ready、generated),可反复调用(用户回上一步重说),本次配置须开放AI共创并开启自由输入。正常计费。
语音:点位选“录音文件识别极速版”时,录完整段用 上传录音识别 拿到 text;选“大模型流式语音识别”时,先 语音识别握手凭据 → 流式语音识别 拿到 final.text。拿到文字后按上一条提交。请求里带 speak:true 时这句回复的语音随结果一起返回(voice.audio);播的是 style_reply,音色取车衣配置里登记的 voice.params.voice,未登记返回 409 VOICE_NOT_CONFIGURED。
结果(同一次调用直接返回 ):status=completed 时 response 为 JSON 字符串:
{"code":0,"mode":"generated","style_task_id":"task_3f1e…","raw":"{\"reply\":\"海边日落很浪漫呀!给你设计一款落日海岸风,暖橙渐变到海蓝,像把黄昏披在车身上。\",\"style\":\"落日海岸\",\"colors\":[…]}","style_name":"落日海岸","style_reply":"海边日落很浪漫呀!给你设计一款落日海岸风,暖橙渐变到海蓝,像把黄昏披在车身上。","colors":[{"index":0,"name":"落日橙","hex":"#F39C4A"},{"index":1,"name":"晚霞珊瑚","hex":"#E8735A"},{"index":2,"name":"海岸蓝","hex":"#2E86C1"},{"index":3,"name":"沙滩金","hex":"#F7DC6F"}],"reply_text":"海边日落很浪漫呀!给你设计一款落日海岸风,暖橙渐变到海蓝,像把黄昏披在车身上。,落日海岸,落日橙#F39C4A,晚霞珊瑚#E8735A,海岸蓝#2E86C1,沙滩金#F7DC6F"}
style_name:模型现编的风格名(2—12 字,服务端校验不超过 16 字)。
style_reply:给用户看、也是播报的那一句(不含色值)。
colors:恰好 4 个,按顺序带 index(0—3)、name(配色名)、hex(#RRGGBB,大写)。没有图标 ,前端按色值画色球。
style_task_id:本次风格对话的任务号(与返回外层的 taskId 相同);去生成时传 styleTaskId,再传用户选的配色 colorIndex。
raw:模型原文,排查用。reply_text:兼容字段,回复,风格名,配色名#色值×4 的逗号串(给原来的 parse_style_and_colors 用),不是回复正文 。
模型输出不符合约定 (不是 JSON、缺回复、风格名为空或过长、配色不是恰好 4 个、色值不是 #RRGGBB、配色名重复):本次任务 status=failed,failure.code="STYLE_PARSE_FAILED",failure.message 写明哪一项不符合,不扣 Token;服务端记一条事件日志 p04.style_parse_failed(含模型原文),不补兜底风格、不补默认配色 。前端提示“没听清,请再说一次或选择默认风格”,用户可直接重说(新的 requestId)。
用户点“去生成”时调用 创建图片任务 :AI 生成风格提交 {requestId,styleTaskId,colorIndex,source:"text"|"voice"};默认风格提交 {requestId,styleId,colorId,source:"preset"}。一次完成保存方案与开始生成。
生成时:风格名、配色名与色值都写进绘图提示词({color_text} 形如“海岸蓝(#2E86C1)”),“用户原始想法”由服务端取本次体验中用户在风格对话里说过的话(未说话为空),客户端不用传。
画像:默认风格按风格、配色编号记标签;AI 生成风格统一记“风格·AI自由创作”,具体风格名保存在方案里。
播报任意一段文字(2026-10-22,共创工坊提出):调 语音合成 ,Body {requestId,text},前端传什么念什么(如页面引导语);不送内容安全审核,按字数计费,字数上限为 voice.tts_max_chars,音色同上。只播风格对话回复时用 speak:true 即可。
功能描述
DIY 页面点“确认打印”时调用一次(2026-10-15,依据共创工坊开发 ai_align.py)。前端用 multipart/form-data 上传用户在 3D 车模上画好的手绘 UV 图 与底色 ,服务端:
保存并确认方案(DIY、底色);手绘 UV 统一转成 PNG;
底色为白色 #FFFFFF:直接用后台配置的纸膜底图;其他颜色:由图像模型把纸膜底图的车漆改成该颜色(冻结一次图片调用的 Token;改色图按其他生成图同样做内容审核);
把手绘 UV 按后台贴合参数切成三块、贴到纸膜的左侧面 / 俯视 / 右侧面,最上层盖光影蒙版;调了模型改色时在右下角空白处加“AI 生成”标识;
纸膜打印图(JPEG)保存为 DIY 作品 (asset_subtype=car_wrap_diy,同步 AIVA 小程序、可在作品打印台按 A4 打印);手绘 UV 原图保存为本次体验的记录(car_wrap_diy_uv,不进作品列表、不能打印、不推送)。
接口立即返回 taskId ,前端用查询图片任务 取结果(完成时返回 paperUrl 与 uvUrl)。白色底几秒内完成、不扣 Token;其他颜色通常数十秒。手绘 UV 不做内容审核(2026-10-09 确认 DIY 成图不审)。DIY 不计入“单次体验最多生成次数”。
失败处理:改色明确失败、改色图审核不通过或合成失败 → 任务 failed、冻结全额冲正、不出图(不会改用白色出图),可换 requestId 重新提交;通信结果未知 → unknown、保留冻结待运营核对。同一 requestId 原样重发返回原任务、不重复扣 Token。同一次体验里手绘 UV 与底色都相同的再次提交 (即使 requestId 不同,如连点或调试工具自动换号)也返回第一次的任务(status:"existing"、duplicate:true),不重新合成、不新增作品、不扣 Token;原任务失败或取消的可以重新提交,改过画或颜色照常提交(2026-10-15)。
请求示例
curl -X POST "$BASE/api/interactions/ix_7d3e/diy-works" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "X-Identity-Session: $SESSION_TOKEN" \
-F "file=@uv.png;type=image/png" \
-F "color=#1F4FD8" \
-F "requestId=diy-submit-001"
返回示例HTTP 200
{ "taskId": "task_5b1e…", "status": "queued", "idempotentHit": false, "designRevision": 3, "note": "(说明文字,内容以实际返回为准)" }
查询完成时(status=completed):
{ "taskId": "task_5b1e…", "status": "completed", "assetId": "asset_77c2…", "uvAssetId": "asset_77c2…", "paperAssetId": "asset_e0a4…",
"uvUrl": "https://cdn.example.com/generated/…/uv.png", "paperUrl": "https://cdn.example.com/generated/…/paper.jpeg", "billing": null }
功能描述
2026-10-11 停用 :打印改由独立的“作品打印台”完成(用户在打印台扫码、选作品打印,见 docs/ux/作品打印台-简版PRD-V0.2.html),互动 Pad 不再发起打印,本接口一律返回 410 code=PRINT_MOVED_TO_STATION。以下为停用前的说明,供已建立的打印单对照。
为一个作品(AI共创侧身作品或 DIY 成图)分配作品号码并建立打印单;AI共创作品由服务端自动换成对应的纸膜图打印(2026-10-10),返回打印共享文件夹地址与建议文件名。打印由前端完成:前端读取作品内容(作品内容 的 content 接口),把作品经局域网写入共享文件夹,再回报打印结果 。AgentOS 不连门店局域网。
作品号码:门店每天从 001 编起(北京时间0点重新开始,同门店所有点位共用,显示至少3位)。号码显示在 iPad 上,用户凭号码到纸膜打印处领取;号码不打印在图纸上(2026-10-09 确认),打印处可按文件名中的号码对应作品。
同一作品只分配一次号码:再次请求(换 requestId 也一样)返回原打印单与原号码,idempotentHit:true。
只给可取件的作品分配:审核通过、计费已核对(DIY 无计费)、授权未撤回、未删除未过期。
请求示例
curl -X POST "$BASE/api/interactions/ix_7d3e/print-jobs" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "X-Identity-Session: $SESSION_TOKEN" \
-H "Content-Type: application/json" \
--data '{"requestId":"print-001","assetId":"asset_1c9e"}'
返回示例HTTP 200
{
"printJobId": "wpj_5b2a…",
"assetId": "asset_1c9e",
"workNo": "023",
"bizDate": "2026-10-09",
"sharedFolder": "\\\\192.168.1.20\\车衣打印",
"fileName": "20261009_023.png",
"status": "pending",
"attempts": 0,
"lastError": null,
"sentAt": null,
"createdAt": "2026-10-09T02:30:15.000Z",
"idempotentHit": false
}
功能描述
2026-10-11 :Pad 已不再新建打印单(打印改由作品打印台完成),本接口只用于改版前已建立的打印单。
前端把作品写入共享文件夹后回报结果。写入失败可再次写入并再次回报,号码不变。查询打印单 可读取最新状态。
请求示例
curl -X POST "$BASE/api/interactions/ix_7d3e/print-jobs/wpj_5b2a/report" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "X-Identity-Session: $SESSION_TOKEN" \
-H "Content-Type: application/json" \
--data '{"result":"sent"}'
返回示例HTTP 200
{ "printJobId": "wpj_5b2a…", "assetId": "asset_1c9e", "workNo": "023", "bizDate": "2026-10-09", "sharedFolder": "\\\\192.168.1.20\\车衣打印", "fileName": "20261009_023.png", "status": "sent", "attempts": 1, "lastError": null, "sentAt": "2026-10-09T02:30:20.000Z", "createdAt": "2026-10-09T02:30:15.000Z" }
功能描述
2026-10-11 :Pad 已不再新建打印单(打印改由作品打印台完成),本接口只用于改版前已建立的打印单。
读取打印单与作品号码,用于页面恢复。
请求示例
curl "$BASE/api/interactions/ix_7d3e/print-jobs/wpj_5b2a" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "X-Identity-Session: $SESSION_TOKEN"
功能描述
2026-10-11 :Pad 已不再新建打印单(打印改由作品打印台完成),本接口只用于改版前已建立的打印单。
取得打印单对应的打印文件字节,前端写入打印PC共享文件夹。AI共创作品的打印文件是对应的纸膜图;纸膜图不进入作品列表,只能经打印单取得(Pad 不显示)。
请求示例
curl "$BASE/api/interactions/ix_7d3e/print-jobs/wpj_5b2a/file" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "X-Identity-Session: $SESSION_TOKEN" -o 20261010_023.jpg
返回示例HTTP 200
图片字节,Content-Type 为 image/jpeg 或 image/png,Content-Disposition 带建议文件名(与打印单 fileName 一致)。
功能描述
取一个作品的小程序码图片,显示在互动最终结果页 (AI共创效果图、DIY 完成后),用户扫码在 AIVA 小程序查看/下载该作品。与打印无关:打印由作品打印台完成(用户在打印台扫自己的体验码),不再有作品号码。
一个作品一个小程序码参数 scene(随机,不含作品编号),重复请求返回同一个 scene;图片每次向 AIVA 现取,可直接重复调用。
只能取本次体验中可取件的作品:AI共创的侧身效果图(纸膜图不进小程序)或 DIY 成图;须已审核通过、计费已核对、授权未撤回、未删除。
AIVA 后端接口尚未就绪(2026-10-11) :M01 作品码请求体 {"type":"work","scene"} 与小程序取作品接口为 AgentOS 拟定,收到 AIVA 接口文档后按其契约调整;联调前本接口会因 M01 未登记返回 409 SUNCODE_NOT_CONFIGURED。
请求示例
curl "$BASE/api/interactions/ix_7d3e/works/asset_1c9e/mini-code" -H "Authorization: Bearer $DEVICE_CREDENTIAL" -H "X-Identity-Session: $SESSION_TOKEN"
返回示例HTTP 200
{ "assetId": "asset_1c9e…", "scene": "w3f9a…(31字符)", "image": "data:image/png;base64,iVBOR…" }
功能描述
2026-10-11 :新作品改用作品小程序码 按作品取。本接口只对改版前已建立的打印单有效。
生成打印单对应作品的小程序码图片,扫码后在 AIVA 小程序查看/下载本次作品。AIVA 后端接口尚未就绪(2026-10-09) :以下 M01 作品码请求方式为 AgentOS 拟定,收到 AIVA 接口文档后按其契约调整,联调前本接口会因 M01 未登记返回409。AgentOS 调用已登记的 AIVA 太阳码接口(M01,请求带 type:"work"、scene、workNo);小程序凭 scene 与会员 ONEID 向 AgentOS 查作品。M01 未登记、调用失败或返回非图片时直接报错,不出占位码;每次调用都会请求 AIVA,前端可自行缓存本次页面的图片。
请求示例
curl "$BASE/api/interactions/ix_7d3e/print-jobs/wpj_5b2a/mini-code" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "X-Identity-Session: $SESSION_TOKEN"
返回示例HTTP 200
{ "printJobId": "wpj_5b2a…", "workNo": "023", "scene": "w3f9a…(32字符)", "image": "data:image/png;base64,iVBOR…" }
再生成与生成次数(2026-10-06确认)
点“去生成”即调用创建图片任务 (默认风格 Body {requestId,styleId,colorId,source};AI 生成风格 Body {requestId,styleTaskId,colorIndex,source}),生成成功即保存为作品。DIY 不调用生成模型。
生成完成(state 为 generated)后,同一体验内可换风格或配色再点“去生成”(新的 requestId)。每次正常计费,每次结果各自保存为作品。
次数上限为配置 wrap.maxGenerations(含首次):排队、执行中、完成和待核对的任务都计入,明确失败或取消(已冲正)的不计;未登记或已达上限返回409。
生成中或结果待核对时不能再次生成(返回409“上一次生成还没有结束”)。
内容安全与未开放能力
AI车衣共创审核用户自由描述文字(发给模型前,见内容安全 )和生成图片;DIY 成图不在已确认的审核范围。生成图片:通过则作品自动审核通过、可取件;不通过(BLOCK/REVIEW)任务失败(code 为 CONTENT_REJECTED),冲正冻结、不保存、不计入次数上限;未登记内容安全或审核服务临时不可用时按通过处理,作品标记“未审核”(2026-10-13 确认)。详见“公用·正式文本与图片任务·内容安全”。
打印(2026-10-11 起)由独立的作品打印台完成,互动 Pad 不再发起打印;AI共创打印的是纸膜图(Pad 不显示)。作品打印台的接口另行提供。
内容安全未开通期间,平台可临时打开“跳过内容安全审核(调试)”,见内容安全 。
互动应用开发接入文档 / 公用接口
公用|正式文本与图片任务(2026-10-06) 接口一览
AIVA面基(P02)、AI音乐(P03)、AI图片生成(P08)、AI车衣共创(P04)调用模型时,都通过本章的“正式任务”接口:客户端提交请求后立即拿到任务号,服务端在后台调用模型,客户端用原任务号查询结果。每次调用先按后台登记的单次上限冻结 Token,结束后按厂商实际用量结算。生成的图片以原文件保存为作品(2026-10-13 起不再加密,存入公开读的对象存储),审核通过后通过本章的作品接口取得公开地址。本章接口全部由互动点位客户端调用,鉴权均为 U(设备凭证 + X-Identity-Session)。
归属 :Path 中的 :id 是创建体验返回的 interactionId。体验必须由同一台设备、同一个登录会话 创建;换设备或重新扫码登录后,旧体验的任务与作品返回 404(“我的作品”“当前助手”除外,它们按用户读取)。
准入 :创建任务前须完成授权、问卷或设计;点位须是 Agent 互动应用(展示点位、普通展示应用返回 409)。2026-10-13 起不再要求本点位播控电脑正在显示互动应用 (取代 10-10“实际 Agent 画面准入”):播控关机、重启、断电,或开发者在播控未开机时调试,都可以正常调用。所用模型须在后台“模型”页配置好连接与凭证,并在点位配置里选定(缺少时 409)。2026-10-13 起 :不再要求登记参数定义或模型版本;模型没填 Token 兑换比例或单次冻结上限时照常调用、不冻结也不扣 Token ,任务计费的冻结额与结算额为 0,计费说明(billing.reason)写明“未计费:模型未填……”,正式运营前须补齐。当前生产发布仍有语音、画像等门禁,联调不绕过门禁(具体门禁清单待确认)。
请求号 requestId :由客户端生成,最长 64 字符,在同一次体验内唯一。同一个请求号原样重发不会重复执行,返回第一次的任务号(status:"existing"、idempotentHit:true);同一个请求号换了内容再发返回 409。
作品基础数据 (2026-10-09):作品保存时读作品文件本身实测并保存——图片宽高(像素)、音频时长(毫秒)、文件大小(字节),在作品列表与 B06 assets 中返回。读不出(文件异常或格式不支持)时该作品保存失败并报错,不保存空值;本功能上线前保存的作品不补算,宽高/时长为 null。
作品名称 (2026-10-09):作品保存时按 {点位名称}_{生成完成时间 yyyyMMddHHmmss,北京时间} 生成并固定,如 AI音乐_20261009103015。点位名称由门店在后台点位详情填写;未填写时作品名称为空。音乐封面随音乐作品,不单独命名。
新请求号 = 新的一次付费调用 。网络错误或结果未知时,客户端只能用原任务号继续查询,不能自动换一个请求号重新生成。
文本限制 :所有文本字段不能为空白,不能包含换行、制表符等控制字符,超长返回 400。
创建接口返回的 status 只有 queued(新任务已登记)和 existing(请求号重放)两种;任务的真实进度以查询接口的 status 为准:
billing.status 是这次调用的冻结记录状态:frozen 冻结中、settled 已结算、reversed 已冲正(全额释放)、unknown 结果未知、review 用量待核对(缺用量或超上限)。人工处置后 billing.status 变为 settled 或 reversed,但任务 status 仍保持 unknown。
文本任务例外(2026-10-14) :模型已正常返回、只是计费转待核对(如真实用量费用超过冻结上限)时,任务 status 为 completed,照常返回 response,体验恢复可继续操作(如重新风格对话、保存方案);billing.status 为 review,冻结保留待运营人工核对。
任务进行期间体验状态为 running,此时不能再提交新任务。任务结束后:成功或明确失败回到提交前的状态(AIVA面基聊天成功后为 chat;AI图片生成、AI车衣共创生成图成功后为 generated)。任务为 unknown 时体验保持 running ,不能再提交任务;访客可以用结束体验 以“放弃”(abandoned)结束(2026-10-08 修复,此前无法结束)。冻结的 Token 不释放,由工作人员在后台核对厂商记录后人工处置;之后迟到的结果不再附加到已结束的体验。
服务端不规定轮询间隔和最长等待(待确认),客户端不要根据自己的轮询超时推断失败。
功能描述
提交一次文本模型调用。AI车衣共创(2026-10-14):同一次调用等模型返回后直接给出结果 ,返回内容与查询文本任务 相同(含 status、response、billing),不需要再查询;其他互动立即返回任务号,再用查询接口取结果。
AI车衣共创要播报这句回复时,请求里带 speak: true 即可(2026-10-20) :响应会多一个 voice 字段,内容与语音合成 的返回一致(含 audio),不用先取 messageId 再调一次。语音的请求号由文本任务号派生,所以用同一个 requestId 重发拿到的是同一条语音,走缓存不重复计费。语音合成失败不影响文本结果:文本照常返回,失败原因放在 voice.error(不自动重试)。
各互动可用的用途(purpose):
服务端从本次体验的配置读取提示词与模型。chat、suggestions、guide 会附带后台指定知识库全文与该用户的结构化记忆(见本章末尾)。用户输入文字(chat 的 text、guide 的自由文本)在建任务、冻结 Token 之前 送内容安全审核,未通过时本次不建任务、不冻结;未登记内容安全或审核服务临时不可用时不送审、按通过处理(2026-10-13 确认,见内容安全 )。
调用成功即已冻结 Token。同一个请求号原样重发不会重复执行,返回第一次的任务号,也不会再次审核。
请求参数Path / Body
Body 只能包含上表字段,多余字段返回 400。
请求示例
curl -X POST "$BASE/api/interactions/ix_6f1c/text-tasks" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "X-Identity-Session: $SESSION_TOKEN" \
-H "Content-Type: application/json" \
--data '{"requestId":"guide-q1-001","purpose":"guide","questionId":"q_destination","optionId":"opt_sea"}'
返回示例HTTP 200
{
"taskId": "task_2b7e0c3a-9d41-4f7e-8a51-0c6d2f1e9b10",
"status": "queued",
"idempotentHit": false,
"note": "任务已持久化并冻结;查询原taskId,不用新requestId重试未知调用。"
}
错误情况
错误响应为 {"error":"说明"},内容安全相关错误另带 code(审核未通过另带 failureKind:"moderation")。客户端按 HTTP 状态 + code 分支,不匹配中文文案。
功能描述
用创建时返回的任务号查询文本任务的进度、结果与 Token 结算情况。只有 status=completed 时返回模型正文;其他状态 response 为 null。任务状态与 Token 规则见 任务状态与 Token 冻结 。
各用途的 response 格式:
模型返回不符合上述格式(如介绍字数不对、建议不足三条、引导回复为空)时任务记为 unknown 并保留冻结,不补模板或固定文案。
请求示例
curl "$BASE/api/interactions/ix_6f1c/text-tasks/task_2b7e0c3a-9d41-4f7e-8a51-0c6d2f1e9b10" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "X-Identity-Session: $SESSION_TOKEN"
返回示例HTTP 200
{
"taskId": "task_2b7e0c3a-9d41-4f7e-8a51-0c6d2f1e9b10",
"purpose": "guide",
"status": "completed",
"messageId": "msg_5a0d7e21-3c8b-4b1f-9e64-2f7a1c0d8e33",
"response": "海边的日落很适合慢下来,你想和谁一起出发?",
"usage": { "input_token": 812, "output_token": 46 },
"providerRequestId": "0217…",
"billing": { "status": "settled", "frozenAmount": 50, "settlementAmount": 3, "reason": "success" },
"note": "通信未知结果保留冻结,不能自动重试;此同步厂商接口尚无按原请求查询结果的适配器。"
}
功能描述
提交一次单图生成。不同互动的输入:
用户照片在建任务、冻结 Token 之前 送内容安全审核:照片以临时对象 + 短时签名链接提交审核,审核结束立即删除,不保存为作品。审核未通过时本次不建任务、不冻结;未登记内容安全或审核服务临时不可用时不送审、按通过处理。
生成图在保存为作品前再审核一次,结论决定任务结果(见 生成图片审核结论 )。生成图以原文件保存到公开读的对象存储(2026-10-13 起不再加密,对象名为随机编号,审核通过后才给出地址)。同一个请求号原样重发不会重复执行,返回第一次的任务号。
请求参数Path / Body
Body 只能包含上表字段,多余字段返回 400。AI车衣共创二选一:默认风格 {styleId,colorId},或 AI 生成风格 {styleTaskId,colorIndex},混传返回 400;styleTaskId 不是本次体验已完成的风格对话返回 404/409,不是 AI 生成结果(如 2026-10-22 之前的库匹配结果)返回 400。
请求示例
curl -X POST "$BASE/api/interactions/ix_6f1c/image-tasks" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "X-Identity-Session: $SESSION_TOKEN" \
-H "Content-Type: application/json" \
--data '{"requestId":"journey-img-001","photo":"data:image/jpeg;base64,/9j/4AAQ..."}'
# AI车衣共创“去生成”
curl -X POST "$BASE/api/interactions/ix_7d3e/image-tasks" -H "Authorization: Bearer $DEVICE_CREDENTIAL" -H "X-Identity-Session: $SESSION_TOKEN" -H "Content-Type: application/json" --data '{"requestId":"wrap-go-001","styleId":"style_cyber","colorId":"color_blue","source":"voice","matchTaskId":"task_3f1e..."}'
AI车衣共创的返回另带 designRevision(服务端保存的方案修订号,仅供记录)。
返回示例HTTP 200
{
"taskId": "task_8c4d1f02-6b3e-4a7d-9c15-3e2b0a9f7d64",
"status": "queued",
"idempotentHit": false,
"note": "(说明文字,内容以实际返回为准)"
}
功能描述
用原任务号查询图片任务的进度、作品编号、生成图审核结论与 Token 结算。生成图审核结论对任务的影响:
另外:审核通过但厂商用量缺失或超过冻结上限时,任务为 unknown(billing.status=review),作品已保存,但要等运营核对结算后才能取件。
AI车衣共创(2026-10-14) :completed 时直接带两张图的地址,不用再调“读取作品预览”:uvUrl(UV 贴图,Pad 做 360° 车模查看用;assetId/uvAssetId 为其作品编号)与 paperUrl(纸膜打印图,paperAssetId)。某张图地址取不到时对应 uvUrlError/paperUrlError 给出原因(如存储访问域名未配置)。
厂商内容拒绝(2026-10-15) :火山因版权或敏感内容拒绝出图(如用户要求画布丁狗等版权角色时返回 OutputImageSensitiveContentDetected.PolicyViolation)时,AI车衣共创生成与 DIY 改色任务按审核失败结案:status:"failed"、failureKind:"moderation"、code:"CONTENT_REJECTED",reason 写明哪一步、哪种拒绝(如“审核未通过:图片厂商拒绝:生成的图片可能涉及版权或敏感内容(…)(纸膜)”),冻结全额冲正、不计生成次数。前端可提示“换个说法试试”。
配置版本(2026-10-15) :返回 configVersion(本次体验开始时所用的配置版本,整次体验都用它)与 latestVersion(当前最新已应用版本);两者不同时另带 configNote 说明。后台发布新版本后,正在进行的体验仍用旧版本——要看新配置的效果,须重新读取互动配置 、确认配置版本 并开始新的体验。
**DIY 确认打印的任务(2026-10-15)**也用本接口查询:completed 时 paperUrl/paperAssetId 为服务端合成的纸膜打印图(DIY 作品),uvUrl/uvAssetId(以及 assetId)为本次上传的手绘 UV(只作记录,不进作品列表、不能打印)。白色底不调模型、没有冻结,billing 为 null;其他颜色冻结一次图片调用,规则同上(改色图审核不通过 failed 并冲正;改色或合成失败 failed 并冲正,reason 写明原因;通信结果未知 unknown 保留冻结)。
{ "taskId": "task_8c4d…", "status": "completed", "assetId": "asset_3f0a…", "uvAssetId": "asset_3f0a…", "paperAssetId": "asset_91bc…",
"uvUrl": "https://cdn.example.com/generated/…/uv.jpeg", "paperUrl": "https://cdn.example.com/generated/…/paper.jpeg", "billing": { "status": "settled", "frozenAmount": 1200, "settlementAmount": 310 } }
请求示例
curl "$BASE/api/interactions/ix_6f1c/image-tasks/task_8c4d1f02-6b3e-4a7d-9c15-3e2b0a9f7d64" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "X-Identity-Session: $SESSION_TOKEN"
返回示例HTTP 200
成功:
{
"taskId": "task_8c4d1f02-6b3e-4a7d-9c15-3e2b0a9f7d64",
"status": "completed",
"assetId": "asset_3f0a9c1e7b2d4c6a8e0f1a2b3c4d5e6f7a8b9c0d",
"reason": null,
"moderation": { "verdict": "pass", "decision": "PASS" },
"billing": { "status": "settled", "frozenAmount": 80, "settlementAmount": 20 },
"note": "(说明文字,内容以实际返回为准)"
}
生成图审核未通过:
{
"taskId": "task_8c4d…",
"status": "failed",
"assetId": null,
"reason": "内容审核未通过(审核失败):BLOCK/…",
"moderation": { "verdict": "rejected", "decision": "BLOCK" },
"failureKind": "moderation",
"code": "CONTENT_REJECTED",
"billing": { "status": "reversed", "frozenAmount": 80, "settlementAmount": 0 },
"note": "…"
}
功能描述
AIVA面基专用。把本次体验已审核通过的助手图片和已完成的介绍消息组合成电子名片并保存,体验状态变为 generated,之后可以聊天。名片内容(名称、介绍)由服务端从介绍消息读取,客户端不能自报;同时按五题计算主属性并读取后台为该属性登记的音色。
每次体验只能完成一张名片。同样的图片与介绍再次提交返回已保存的名片;换了图片或介绍返回 409。名片完成后,当前助手 即为这张新名片。
请求示例
curl -X POST "$BASE/api/interactions/ix_6f1c/result/complete" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "X-Identity-Session: $SESSION_TOKEN" \
-H "Content-Type: application/json" \
--data '{"avatarAssetId":"asset_3f0a9c1e7b2d4c6a8e0f1a2b3c4d5e6f7a8b9c0d","introMessageId":"msg_5a0d7e21-3c8b-4b1f-9e64-2f7a1c0d8e33"}'
返回示例HTTP 200
{
"result": {
"kind": "p02-electronic-card",
"avatarAssetId": "asset_3f0a…",
"introMessageId": "msg_5a0d…",
"name": "星野",
"description": "热爱探索的伙伴,喜欢在旅途中发现新奇的科技与风景。",
"tags": ["explorer", "tech"],
"scores": [{ "tag": "explorer", "count": 3 }, { "tag": "tech", "count": 2 }],
"scoringRule": "p02-v2-q1-q4-q5-q2-q3",
"voiceParams": { "voice": "后台登记的音色" },
"configVersion": 7
},
"state": "generated",
"note": "名片结构已保存。生成图片及介绍需由正式执行服务写入,客户端不能自报模型结果。"
}
同一请求再次提交时返回 {"result":{…},"idempotentHit":true}(不含 state、note)。
功能描述
分页列出本次体验在当前门店产生的作品(生成图、AI音乐音频与封面等),按生成时间倒序。列表包含尚未审核通过的作品,客户端以 audit_status 判断能否取件。
请求示例
curl "$BASE/api/interactions/ix_6f1c/works?limit=20&offset=0" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "X-Identity-Session: $SESSION_TOKEN"
返回示例HTTP 200
{
"items": [
{
"asset_id": "asset_3f0a…",
"work_name": "AI图片生成_20261008101000",
"agentos_uid": "au_3f9c…",
"store_id": "CQ-GUANGHUAN",
"point_id": "P08",
"interaction_id": "ix_6f1c…",
"asset_type": "image",
"asset_subtype": "journey",
"file_size": 1834211,
"width": 1248,
"height": 832,
"duration_ms": null,
"audit_status": "approved",
"is_final": 0,
"source_task_id": "task_8c4d…",
"lifecycle_stage": "standard",
"synced_to_mp_at": null,
"mp_work_id": null,
"created_at": "2026-10-08T02:10:00.000Z",
"expire_at": "2027-01-06T02:10:00.000Z"
}
],
"total": 1,
"limit": 20,
"offset": 0
}
功能描述
返回某个作品的读取地址。2026-10-13 起四个互动(AIVA面基、AI音乐、AI图片生成、AI车衣共创)的作品都以原文件(.png/.jpg/.webp/.mp3/.wav)保存在公开读的对象存储,返回 https:// 公开地址,可以直接放进 <img src> 或 <audio src>。保护方式:对象名为随机编号、审核通过后才给出地址、删除作品即删除文件。
2026-10-13 之前保存、仍是加密存储的旧作品(运维用 tools/convert-encrypted-works.js 转换之前),仍返回需要带设备凭证和用户会话请求头的取件地址 (requiresIdentityHeaders: true),客户端要用带请求头的请求读取二进制后再显示(例如转成本地 Blob 地址)。客户端按 requiresIdentityHeaders 区分两种情况即可。
本接口只检查作品存在、已审核通过、未删除、已保存到当前存储。
请求示例
curl "$BASE/api/interactions/ix_6f1c/works/asset_3f0a9c1e7b2d4c6a8e0f1a2b3c4d5e6f7a8b9c0d/preview" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "X-Identity-Session: $SESSION_TOKEN"
返回示例HTTP 200
{
"assetId": "asset_3f0a…",
"type": "image",
"url": "https://<对象存储公开访问地址>/generated/…/3b9d….png",
"accessNote": "平台采用公开读存储;链接期限不是访问控制边界。"
}
功能描述
经 AgentOS 鉴权读取作品的原始内容(图片或音频二进制)。主要用于仍是加密存储的旧作品(预览接口返回 requiresIdentityHeaders: true 时);2026-10-13 起的新作品直接用预览返回的公开地址即可,本接口也能读取。每次读取都重新核对:作品归属本次体验与当前用户、授权未撤回、审核已通过、原任务已结算、未删除、文件校验和一致。响应不缓存。
请求示例
curl "$BASE/api/interactions/ix_6f1c/works/asset_3f0a9c1e7b2d4c6a8e0f1a2b3c4d5e6f7a8b9c0d/content" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "X-Identity-Session: $SESSION_TOKEN" \
-o work.bin
错误情况
错误时返回 JSON {"error":"说明"}。
功能描述
分页列出当前登录用户在本租户所有门店、所有点位的作品,按生成时间倒序。已绑定 ONEID 时包含该会员全部关联账户的作品,每条保留原账户(agentos_uid)与门店。只能读自己的作品,不能自报用户编号。列表包含尚未审核通过的作品。
请求示例
curl "$BASE/api/users/me/works?limit=20&offset=0" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "X-Identity-Session: $SESSION_TOKEN"
返回示例HTTP 200
{
"items": [
{
"asset_id": "asset_3f0a…",
"work_name": "AI图片生成_20261008101000",
"agentos_uid": "au_3f9c…",
"store_id": "CQ-GUANGHUAN",
"point_id": "P02",
"interaction_id": "ix_2d9a…",
"asset_type": "image",
"asset_subtype": "avatar_config",
"file_size": 2410566,
"width": 1344,
"height": 1792,
"duration_ms": null,
"audit_status": "approved",
"is_final": 0,
"source_task_id": "task_1e7c…",
"lifecycle_stage": "standard",
"synced_to_mp_at": null,
"mp_work_id": null,
"created_at": "2026-10-06T08:00:00.000Z",
"expire_at": "2027-01-04T08:00:00.000Z"
}
],
"total": 1,
"limit": 20,
"offset": 0
}
功能描述
与 读取本次体验作品预览 相同,但按当前用户(含 ONEID 关联账户)跨门店查找作品,不限定体验。新作品返回 https:// 公开地址;仍是加密存储的旧作品返回的取件地址是 读取我的作品内容 。
请求示例
curl "$BASE/api/users/me/works/asset_3f0a9c1e7b2d4c6a8e0f1a2b3c4d5e6f7a8b9c0d/preview" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "X-Identity-Session: $SESSION_TOKEN"
返回示例HTTP 200
{
"assetId": "asset_3f0a…",
"type": "image",
"url": "https://<对象存储公开访问地址>/generated/…/3b9d….png",
"accessNote": "平台采用公开读存储;链接期限不是访问控制边界。"
}
功能描述
与 读取本次体验作品内容 相同的核对与返回,但按当前用户(含 ONEID 关联账户)跨门店查找作品,不限定体验。
请求示例
curl "$BASE/api/users/me/works/asset_3f0a9c1e7b2d4c6a8e0f1a2b3c4d5e6f7a8b9c0d/content" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "X-Identity-Session: $SESSION_TOKEN" \
-o work.bin
错误情况
错误时返回 JSON {"error":"说明"}。
功能描述
返回当前用户的个人助手:本人及同一 ONEID 关联账户最新完成 的 AIVA面基名片。历史名片保留;重新回答生成新名片后自动成为当前助手。从未完成过名片时返回 assistant:null。最新名片已被清理、授权已撤回或助手图片失效时直接报错,不改用更早的名片或默认形象。任何互动点位都可调用。
助手图片用 assistant.avatarAssetId 通过 读取我的作品预览 取件。
请求参数
无。只需请求头中的设备凭证与 X-Identity-Session。
请求示例
curl "$BASE/api/users/me/assistant" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "X-Identity-Session: $SESSION_TOKEN"
返回示例HTTP 200
{
"assistant": {
"kind": "p02-electronic-card",
"avatarAssetId": "asset_3f0a…",
"introMessageId": "msg_5a0d…",
"name": "星野",
"description": "热爱探索的伙伴,喜欢在旅途中发现新奇的科技与风景。",
"tags": ["explorer", "tech"],
"scores": [{ "tag": "explorer", "count": 3 }, { "tag": "tech", "count": 2 }],
"scoringRule": "p02-v2-q1-q4-q5-q2-q3",
"voiceParams": { "voice": "后台登记的音色" },
"configVersion": 7,
"interactionId": "ix_2d9a…",
"sourceAccountId": "au_3f9c…",
"createdAt": "2026-10-06T08:05:00.000Z"
},
"scope": "tenant-user",
"note": "当前助手取本人及同一ONEID关联账户最新完成的名片;历史名片保留,重新回答生成新名片后自动成为当前助手。"
}
从未完成名片时只返回 {"assistant":null}。
接入火山引擎内容安全。审核范围:用户输入文字 (发给模型前)、用户拍照 (作为生图输入前)、生成图片 (保存为作品前);模型生成的文字本期不审。火山返回 BLOCK 与 REVIEW 一律按“审核失败”处理。
2026-10-13 起(用户确认,取代原“未配置或服务不可用直接报错 503、不放行”) :后台未登记内容安全(审核接入点、AppId、文本或图片 biztype、凭证、超时、图片审核临时链接有效期任一未登记,或存储不是 TOS),或审核服务临时不可用(通信中断、超时、返回异常)时,用户文字、用户拍照、生成图片都不送审、按通过处理 :请求照常继续,生成的作品当作已通过(可显示、打印、同步 AIVA 小程序),后台标记为“未审核”(audit_provider=moderation_skipped,原因 not_configured 未登记 / unavailable 服务不可用)。登记内容安全后由内容安全做基础审核。客户端因此不会再收到 MODERATION_NOT_CONFIGURED / MODERATION_UNAVAILABLE。注意:正式运营前若未登记内容安全,所有用户内容都未经审核。
音频作品(AI音乐)不在内容安全审核范围。
调试开关(2026-10-11) :内容安全未开通期间,平台管理员可在后台“安全策略”打开“跳过内容安全审核(调试)”(全平台,手动关闭为止)。打开期间即使已登记内容安全也不送审,不会出现 CONTENT_REJECTED:文字、拍照、生成图都按通过处理,作品照常可显示、打印与同步,后台标记为“未审核(调试期跳过)”。客户端不需要为此改代码,但仍须按下表处理审核未通过。
审核相关错误在 {"error"} 之外带稳定字段 code(审核失败另带 failureKind:"moderation"),客户端按 HTTP 状态 + code 分支,不匹配中文文案:
生成图片在未登记内容安全或审核服务临时不可用时:按通过处理,任务照常 completed 并结算,作品自动审核通过、可取件,后台标记“未审核”(2026-10-13 确认,取代 2026-10-07“任务 unknown、保留冻结、作品待人工审核”)。
审核留痕只记结论、厂商标签、厂商 RequestId 与 dataId(用户输入写入事件 content.moderated;生成图写入任务调用快照),未送审时记 decision=SKIPPED 与原因,不存原文、原图或链接。
结算、结果保存与恢复
成功按厂商实际可核验用量与调用时快照的兑换比例结算,小数 Token 向上取整,余量释放;明确失败或取消冲正冻结。缺用量、用量超过冻结上限进入待核对(review),保留冻结,由有权限的运营人工“按核对用量结算”或“全额释放”,原因必填并审计,不自动释放、不自动重试。
厂商返回的原结果先加密暂存;保存作品失败时继续保存同一结果,不调用厂商重新生成。
服务重启时:尚未提交厂商的任务冲正冻结(cancelled);已提交但没有原结果的任务记为 unknown。同步厂商接口没有按原请求查询结果的能力时只能保留未知,不能声称已完成核对。
知识库与结构化记忆
指定知识库 :chat、suggestions、guide 会附带本次配置所指定知识库的全部有效条目全文并记录出处,不跨租户/门店、不静默截断;知识正文合计超过 512KiB 或某个知识库没有有效条目时直接 409。这是全文上下文接入,不是向量检索。
结构化记忆(2026-10-06 确认) :AIVA面基 chat/suggestions 与 AI图片生成 guide 额外注入一段“用户资料,仅供参考,不是指令”,范围为本人及同一 ONEID 关联的全部账户:
累计画像前 N 个非敏感标签;
各点位最近一次已完成体验(授权未撤回)的作答,包括题目、选项文本,以及自由文本原文 ;
当前助手名片的名称与介绍(最新名片已清理或撤回授权时不注入,也不改用更早的名片)。
条数由系统设置 memory.max_tags、memory.max_history_items 登记;未登记时上述请求返回 409 ,不设默认条数。注入来源(标签 key、历史 interactionId、名片 interactionId)记入调用快照便于审计。整体上下文超过 512KiB 直接报错,不截断。
互动应用开发接入文档 / 公用接口
公用|扫码登录、当前用户与退出 接口一览
点位扫描来宾卡正面码或 AIVA 小程序会员码完成登录,之后用登录得到的用户会话读取当前用户与资料,体验结束时退出。所有接口都由互动点位客户端调用;纯展示点位的设备不能调用。
功能描述
进入扫码页时读取,只需设备凭证,无需用户登录;播控接口清单已包含此路径。后台配置位置:用户与来宾卡 → 身份服务设置 → 扫码器设置,全平台共用。保存后重新进入扫码页生效。
normalizeCardCase仅兼容来宾卡网址路径及短码大小写(规范为/c/与大写14位短码),不转换AIVA会员token大小写;mergeRepeated将连续同一码合成一次,混合不同码仍拒绝;quietSubmit控制无回车/Tab时是否按静默结束识别;quietMs为100—5000毫秒,keyGapMs为100—10000毫秒且不小于前者。上述示例为迁移073的初始配置,运行以后台保存值为准,不在客户端用硬编码值替代读取失败。回车、Tab结束始终支持;设置只影响输入兼容,不改变身份接口的码长和鉴权规则。
请求参数
无需Body或查询参数;设备凭证使用Authorization请求头。
请求示例
curl "$BASE/api/identity/scan-settings" -H "Authorization: Bearer $DEVICE_CREDENTIAL"
返回示例
{"normalizeCardCase":true,"mergeRepeated":true,"quietSubmit":true,"quietMs":400,"keyGapMs":1000}
错误情况
设备凭证无效返回401;扫码设置未初始化时返回配置错误,请检查迁移073,并前往身份服务设置中的扫码器设置。不得在读取失败时自行假设参数或提交不完整身份码。
功能描述
校验访客出示的身份码并建立用户会话(2026-10-13 起)。支持两种码:
扫码时可以不传 kind,由服务端按码的格式判断(2026-10-13):
两种格式长度不重叠(14 位与 32 位),不会互相误判。会员码位数不是 32 位、或含大写字母的,按无法识别处理。已绑定 ONEID 的身份统一登录到该会员的主账户(最早创建的账户)。
AIVA 会员码只能用一次。 AIVA 识别失败、连不上或 AgentOS 未登记 AIVA 网关时,登录直接失败,不改用其他身份;需要重扫时请会员在小程序里刷新会员码。原 AgentOS 自己签发的一次性会员凭据(memberTicket,kind=member)已于 2026-10-13 停用。
调用时机:访客在点位开始互动、需要识别身份时。每个点位各自登录,会话不能转交给其他点位。
请求示例
curl -X POST "$BASE/api/identity/point-login" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "Content-Type: application/json" \
--data '{"code":"https://card.example/c/8K2M4P6R8T0V2X"}'
# AIVA 小程序会员码:二维码内容原样传入,kind 可不传
curl -X POST "$BASE/api/identity/point-login" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "Content-Type: application/json" \
--data '{"code":"<AIVA 会员码二维码内容>"}'
返回示例HTTP 200
{
"AgentOSID": "au_3f9c0d1e2a4b5c6d7e8f",
"ONEID": "oneid_example",
"createdUser": false,
"sessionId": "ids_6b1f…",
"nickname": "小赛",
"avatarUrl": "https://<AIVA 头像域名>/avatar.png",
"sessionToken": "仅在此返回一次的用户会话",
"expiresIn": 1800
}
错误情况
错误返回 {"error":"中文说明","code":"…"},code 只在部分错误中出现。
功能描述
读取当前会话对应的用户编号、会员编号与 Token 账户。界面显示的余额以这里为准,不要把同一会员各张卡的余额自行相加。
请求参数
无。只需请求头中的设备凭证与 X-Identity-Session。
请求示例
curl "$BASE/api/identity/me" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "X-Identity-Session: $SESSION_TOKEN"
返回示例HTTP 200
{
"AgentOSID": "au_3f9c0d1e2a4b5c6d7e8f",
"ONEID": "oneid_example",
"account": { "balance": 120, "frozen": 0 }
}
功能描述
按数据类别分页读取当前用户的原始资料。已绑定 ONEID 时包含该会员全部关联账户的数据,每条记录保留它原来属于哪个账户、哪个门店;未绑定时只返回本卡数据。需要“累计画像”结果时请用下一个接口。
请求示例
curl "$BASE/api/identity/profile/tags?limit=50" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "X-Identity-Session: $SESSION_TOKEN"
返回示例HTTP 200
{
"schemaVersion": 1,
"items": [ { "id": "1024", "agentos_uid": "au_3f9c…", "tag_key": "style_tech", "store_id": "CQ-GUANGHUAN", "point_id": "P02", "created_at": "2026-10-06T08:00:00.000Z" } ],
"hasMore": false,
"nextCursor": null,
"consistency": "live-keyset-bounded",
"asOf": "2026-10-08T02:00:00.000Z",
"complete": true,
"primaryAgentOSID": "au_1a2b…",
"profileMode": "source-evidence",
"note": "返回所有关联账户的原始贡献与来源;累计画像见 /api/identity/profile-summary。"
}
功能描述
返回当前用户(已绑定 ONEID 时为该会员全部关联账户)的标签累计结果:每次作答的标签贡献全部累计,重复作答累加权重(2026-10-06 确认)。用于在互动中展示或引用用户画像。
请求参数
无。只需请求头中的设备凭证与 X-Identity-Session。
请求示例
curl "$BASE/api/identity/profile-summary" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "X-Identity-Session: $SESSION_TOKEN"
返回示例HTTP 200
{
"primaryAgentOSID": "au_1a2b…",
"ONEID": "oneid_example",
"rule": "cumulative_all_answers",
"accountIds": ["au_1a2b…", "au_3f9c…"],
"totalContributions": 12,
"items": [
{ "tagKey": "style_tech", "tagName": "科技感", "category": "风格", "weight": 5, "share": 0.4167, "interactions": 3, "points": ["P02", "P08"], "firstAt": "2026-10-06T08:00:00.000Z", "lastAt": "2026-10-08T01:00:00.000Z" }
]
}
功能描述
撤销当前用户会话。访客结束体验或离开点位时调用;之后该 sessionToken 不能再使用。客户端同时清除本地会话和屏幕上的用户信息。
AI车衣共创(2026-10-14) :退出时只发这一个请求——服务端顺带结束本会话还在进行的体验:已有保存成功的作品记“完成”(completed),没有作品记“放弃”(abandoned);只剩结果待核对的任务时按“放弃”结束(冻结待后台核对);仍有任务在执行时该体验不结束,在 notEnded 里说明原因(会话照常退出)。其他互动退出登录不结束体验,仍需先调用结束体验 。
请求示例
curl -X POST "$BASE/api/identity/logout" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "X-Identity-Session: $SESSION_TOKEN" \
-H "Content-Type: application/json" \
--data '{}'
返回示例HTTP 200
{ "loggedOut": true }
AI车衣共创另带:
{ "loggedOut": true, "ended": [ { "interactionId": "ix_7d3e…", "state": "completed" } ], "notEnded": [] }
会员码与跨点位数据
会员码就是 AIVA 小程序里显示的会员码,内容为 32 位小写十六进制的临时 token(2026-10-13 AIVA 确认)。扫到的内容原样作为 code 传给扫码登录,不传 kind、不要自己解析,也不要传 ONEID 明文;来宾卡码与会员码由服务端按格式识别,识别不了的返回 400 CODE_INVALID(不会调用 AIVA),见扫码登录 。AgentOS 用它调用 AIVA 换出 ONEID;AIVA 的码只能用一次,登录响应丢失时不能拿原码重发,请会员在小程序刷新会员码后重扫。AgentOS 自己签发的一次性会员凭据 memberTicket(kind=member)已于 2026-10-13 停用。
不同点位分别扫码登录;不能把P02的sessionToken转交P03。ONEID多卡关联后的Token归集到最早创建的AgentOSID,界面以me返回账户为准,不自行把各卡余额相加。
读取当前用户共享资料使用profile接口,不调用集团全量用户接口。可选数据域:tags、profileContributions、interactionAnswers、interactionDesigns、assets。返回原始资料不等于画像合并已完成。
当前用户资料的分页协议
limit为可选integer,1–500,默认100;cursor可选string,原样传回nextCursor。响应还含primaryAgentOSID、profileMode="source-evidence"和note。
{"schemaVersion":1,"items":[],"hasMore":false,"nextCursor":null,"consistency":"live-keyset-bounded","asOf":"2026-10-02T00:00:00.000Z","complete":true,"note":"响应中的实际说明","primaryAgentOSID":"uid_example","profileMode":"source-evidence"}
hasMore=true时继续同一数据域、同一用户和凭证的查询;不要解析或自造cursor。complete只表示该数据域本次分页结束。分页固定主键上界,但每页读取实时值;敏感映射等受导出限制。条目字段见“公用·用户资料字段”。
互动应用开发接入文档 / 公用接口
公用|互动配置、授权与会话 接口一览
本章是 AIVA面基(P02)、AI音乐(P03)、AI图片生成(P08)、AI车衣共创(P04)四个互动共用的“配置 → 开始体验 → 授权 → 作答/确认 → 结束”接口。点位由设备凭证决定,客户端不能自己指定门店或点位。读取配置和确认配置只用设备凭证(D);其余接口都要再带扫码登录得到的用户会话(U,见扫码登录 )。路径中的 :id 是“开始体验”返回的 interactionId,必须是本设备、本次登录会话创建的体验,否则一律返回 404。纯展示点位的设备不能调用本章任何接口(403)。
调用顺序
功能描述
读取本点位当前已应用的互动配置:题目、开场与建议文本、授权条款和流程阶段,以及各互动的专属字段。只下发界面需要的内容;模型凭证、提示词和选项对应的标签不下发。响应带 Cache-Control: no-store。
调用时机:程序启动、恢复联网、后台改了配置之后。读到新的 version 时,先按新配置准备好页面,再调用确认已应用配置 。
请求示例
curl "$BASE/api/interactions/config" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL"
返回示例HTTP 200
AI图片生成(P08)示例:
{
"pointId": "P08",
"version": 7,
"questions": [
{
"id": "q_destination",
"title": "你想去哪里?",
"allowText": true,
"options": [ { "id": "q_destination_sea", "label": "海边", "detail": "后台配置的说明" } ]
}
],
"opening": "后台配置的开场文本",
"suggestions": "后台配置的建议文本",
"policy": {
"policy_id": "policy_portrait",
"name": "人像采集授权",
"kind": "portrait",
"version": 2,
"content": { "title": "……", "body": "……" }
},
"stages": ["consent", "photo", "questions", "departure-confirmation", "focus", "generation"],
"result": { "title": "后台固定标题", "subtitle": "后台固定副标题" }
}
各互动的 stages:AIVA面基 consent, photo, questions, generation, chat;AI图片生成如上例;AI音乐 consent, genre, timbre, story, lyrics, lyrics-confirmation, music, result;AI车衣共创 consent, mode, design, design-confirmation, generation, result。
功能描述
告诉 AgentOS:本设备已经按某个配置版本准备好页面。服务端按设备记录最近一次确认的版本;开始体验 时要求传入的版本既是当前已应用版本,又是本设备已确认的版本。后台发布新版本后,旧确认自动失效,需要重新读取并确认。
请求示例
curl -X POST "$BASE/api/interactions/config/ack" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "Content-Type: application/json" \
--data '{"version":7}'
返回示例HTTP 200
{ "confirmed": true, "version": 7 }
功能描述
为当前登录用户在本点位开始一次体验,记下本次使用的配置和授权条款,返回 interactionId,初始状态 consent(等待授权)。
AI车衣共创(2026-10-14) :开始体验即视为用户已同意本次授权条款——服务端按配置里的授权协议版本直接记一条授权,返回 state:"questions" 和 consentId,不用再调用提交授权决定 。前端须在用户点了“同意”之后才调用开始体验,用户不同意就不要开始。
开始前服务端会检查:配置版本是当前已应用且本设备已确认的版本;点位应用类型是 Agent 互动;本设备通过播控运行回报报告“处于应用模式且网页和输出就绪”,并且回报还在运行状态有效期内(见播控配对与配置下发 )。
同一个用户会话里,同一个 requestId 原样重发不会重复开始体验,返回第一次创建的 interactionId(带 idempotentHit: true)。返回的 version 是本次体验所用的配置版本,整次体验都用这一版 ;后台之后再发布新版本不影响正在进行的体验(2026-10-15 起重发时也返回 version)。网络失败时用同一个 requestId 重试;只有用户真的再开一次体验时才换新的 requestId。
请求示例
curl -X POST "$BASE/api/interactions" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "X-Identity-Session: $SESSION_TOKEN" \
-H "Content-Type: application/json" \
--data '{"requestId":"experience-20261008-0001","version":7}'
返回示例HTTP 200
首次创建:
{ "interactionId": "ix_5b0e8f2a-1c3d-4e5f-8a9b-0c1d2e3f4a5b", "version": 7, "state": "consent" }
同一 requestId 重发:
{ "interactionId": "ix_5b0e8f2a-1c3d-4e5f-8a9b-0c1d2e3f4a5b", "idempotentHit": true }
功能描述
读取本次体验的当前状态、已提交的答案和已保存的文本消息。用于页面刷新或断线恢复后对齐进度。正式任务(文本、图片、音乐)的进度请查原任务编号,不要用这里推断任务结果。
请求示例
curl "$BASE/api/interactions/ix_5b0e8f2a-1c3d-4e5f-8a9b-0c1d2e3f4a5b" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "X-Identity-Session: $SESSION_TOKEN"
返回示例HTTP 200
{
"interactionId": "ix_5b0e8f2a-1c3d-4e5f-8a9b-0c1d2e3f4a5b",
"state": "chat",
"version": 7,
"answers": [
{ "questionId": "q1", "title": "周末你更想……", "optionId": "q1_a", "label": "去看展", "tags": ["tag_art"] }
],
"messages": [
{
"message_id": "msg_…",
"purpose": "chat",
"user_text": "你好",
"response": "你好,我是你的助手……",
"regenerates": null,
"status": "completed",
"usage_json": { "…": "厂商返回的用量记录,结构以实际为准(待确认)" },
"created_at": "2026-10-08T02:00:00.000Z"
}
]
}
功能描述
提交访客对授权条款的明确决定。(AI车衣共创 2026-10-14 起不需要调用,开始体验即视为已同意。)同意:记录授权,状态变为 questions(AI车衣共创也是 questions,但下一步走设计接口,不走问卷)。拒绝:本次体验直接结束,状态 abandoned。
已经同意过再提交同意,返回第一次的授权编号(带 idempotentHit: true);已经同意过想撤回,必须调用撤回授权 ,不能在这里提交拒绝。
请求参数Body
policyId / policyVersion 必须与本次体验开始时锁定的条款一致,取自读取互动配置 的实际响应,不要用示例值。
请求示例
curl -X POST "$BASE/api/interactions/ix_5b0e8f2a-1c3d-4e5f-8a9b-0c1d2e3f4a5b/consent" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "X-Identity-Session: $SESSION_TOKEN" \
-H "Content-Type: application/json" \
--data '{"accepted":true,"policyId":"policy_portrait","policyVersion":2}'
返回示例HTTP 200
同意:
{ "consentId": "cs_9a8b7c6d-…", "state": "questions" }
拒绝:
{ "state": "abandoned" }
已同意后再次提交同意:
{ "consentId": "cs_9a8b7c6d-…", "idempotentHit": true }
功能描述
访客中途撤回授权。服务端标记授权已撤回(已有授权时),并把本次体验结束为 abandoned,停止后续人像相关调用。撤回不等于删除全部历史记录,已产生的记录按平台留存策略处理。
代码现状:本接口不检查当前状态,任何状态下调用都会把本次体验改为 abandoned(包括已完成的体验),也不检查是否有进行中的模型任务。客户端只在访客明确撤回时调用。
请求示例
curl -X POST "$BASE/api/interactions/ix_5b0e8f2a-1c3d-4e5f-8a9b-0c1d2e3f4a5b/consent/revoke" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "X-Identity-Session: $SESSION_TOKEN" \
-H "Content-Type: application/json" \
--data '{}'
返回示例HTTP 200
{ "revoked": true, "note": "停止后续人像调用;原片未在本服务持久化。已产生记录按平台留存策略处理。" }
功能描述
一次性提交本次体验的全部答案(不是逐题提交)。成功后状态变为 ready,并把答案对应的标签累计进用户共享画像(重复作答累加,不覆盖以前的贡献)。
各互动差异:
自由文本答案在写入前送内容安全审核(规则见正式文本与图片任务 中的“内容安全”);审核不通过时不写入任何答案;未登记内容安全或审核服务临时不可用时不送审、按通过处理。
已提交过答案后,再提交完全相同的答案会返回第一次的结果(带 idempotentHit: true,不再审核);提交不同答案会被拒绝,答案一经提交不能修改。
请求示例
curl -X POST "$BASE/api/interactions/ix_5b0e8f2a-1c3d-4e5f-8a9b-0c1d2e3f4a5b/answers" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "X-Identity-Session: $SESSION_TOKEN" \
-H "Content-Type: application/json" \
--data '{"answers":[{"questionId":"q_destination","optionId":"q_destination_sea"},{"questionId":"q_wish","text":"想去看极光"}]}'
返回示例HTTP 200
AI图片生成 / AI音乐:
{ "state": "ready", "tags": ["tag_sea"] }
AIVA面基:
{
"state": "ready",
"tags": ["tag_art", "tag_tech"],
"scores": [ { "tag": "tag_art", "count": 3 }, { "tag": "tag_tech", "count": 2 } ],
"scoringRule": "p02-v2-q1-q4-q5-q2-q3"
}
功能描述
仅 AIVA面基(P02)和 AI图片生成(P08,即点击“出发”)使用:在答案提交后(状态 ready)登记访客确认。只记录确认时间,不创建生成任务;之后由客户端调用正式图片任务 。重复调用保留第一次的确认时间,返回相同结果。
AI音乐与 AI车衣共创使用各自带修订号的确认接口(见 AI音乐 、AI车衣共创 ),调用本接口返回 400。
请求示例
curl -X POST "$BASE/api/interactions/ix_5b0e8f2a-1c3d-4e5f-8a9b-0c1d2e3f4a5b/confirm" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "X-Identity-Session: $SESSION_TOKEN"
功能描述
结束本次体验,标记为完成(completed)或放弃(abandoned)。只结束体验,不注销身份;访客离开时先在会话仍有效时结束体验,再退出登录 。
有模型任务仍在执行(已建未派发、已派发、已提交厂商或保存中)时不能结束,需先查原任务直到有结论。
只剩结果未知(unknown)、待后台人工核对的任务时,可以用 abandoned 结束(2026-10-08 修复,此前无法结束);此时不能报 completed。冻结的 Token 不释放、任务记录不改,返回带 pendingReview:true;之后迟到的结果不再附加到本次体验。
标记 completed 需已有结果:状态为 generated、chat 或 completed;AI车衣共创只要本次体验已有一个生成完成的作品,即使之后又改了设计,也可以标记完成。
已经结束的体验,再次提交相同结束状态返回当前状态;提交不同状态返回 409。
AI车衣共创结束时清理本次的绘制草稿与临时对话正文,只保留风格配色等最终信息。
请求示例
curl -X POST "$BASE/api/interactions/ix_5b0e8f2a-1c3d-4e5f-8a9b-0c1d2e3f4a5b/end" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "X-Identity-Session: $SESSION_TOKEN" \
-H "Content-Type: application/json" \
--data '{"status":"completed"}'
功能描述
仅 AIVA面基使用(聊天页的循环箭头“重新回答”)。在同一次操作里结束当前体验(状态 completed,结束原因 user_restart)并开始一次新体验,返回新的 interactionId。新体验需要重新授权、作答 5 题、生成新名片,正常计费;原体验的名片、作答和标签贡献都保留,新体验的标签继续累计进画像(2026-10-06 确认)。
只能在本次名片已完成(状态 generated 或 chat)后发起;名片未完成时请用结束体验 。
有模型任务正在执行或待核对时拒绝。
开始新体验的检查与开始体验 相同(配置版本已确认、点位为 Agent 互动、播控处于应用模式且就绪)。
requestId 是新体验的请求号,不能与当前体验的相同。同一 requestId 原样重发不会再开一次,返回第一次开出的新体验编号(带 idempotentHit: true)。
请求参数Path / Body
请求体只允许这两个字段,多传其他字段返回 400。
请求示例
curl -X POST "$BASE/api/interactions/ix_5b0e8f2a-1c3d-4e5f-8a9b-0c1d2e3f4a5b/restart" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "X-Identity-Session: $SESSION_TOKEN" \
-H "Content-Type: application/json" \
--data '{"requestId":"experience-20261008-0002","version":7}'
返回示例HTTP 200
{
"previous": { "interactionId": "ix_5b0e8f2a-1c3d-4e5f-8a9b-0c1d2e3f4a5b", "state": "completed", "closeReason": "user_restart" },
"interactionId": "ix_7d6c5b4a-…",
"version": 7,
"state": "consent",
"note": "原体验已结束并保留名片与作答;新体验需重新授权并作答后生成新名片,标签贡献累计。"
}
同一 requestId 重发时:
{
"previous": { "interactionId": "ix_5b0e8f2a-1c3d-4e5f-8a9b-0c1d2e3f4a5b", "state": "completed", "closeReason": "user_restart" },
"interactionId": "ix_7d6c5b4a-…",
"idempotentHit": true
}
体验状态
state 是服务端记录的实际状态;配置里的 stages 是页面流程清单,两者不同,不能用 stages 推算实际进度。
退出与撤回的区别
结束体验只结束本次体验,退出登录只注销身份;访客离开时先结束体验,再退出登录。撤回授权会把本次体验标为 abandoned,但不代表已删除全部历史记录。
互动应用开发接入文档 / 公用接口
公用|展示模式与素材播放 接口一览
所有点位(互动点位与纯展示点位)都可以配置普通展示素材。素材上传、审核、播放编排都在 AgentOS 后台完成,现场程序只读取素材地址并播放,不调用后台上传接口。本章是旧版(v1)展示读取与回执接口和设备心跳;2026-10-07 起所有点位统一由中控Pad控制,现场播放应使用播控配对与配置下发 中的 v2 接口,v1 读取接口对中控点位返回 409(见下方卡片)。
播放语义
整单stop表示停止播放器,不擅自切换Agent或改播备用素材。视频单项loop优先于整单结束设置,因为该条目不会结束。网络抖动拉不到配置时维持上一次生效的状态与版本,不把请求失败当作关闭点位;素材加载失败不得静默换图,客户端提交error回执。首次尚无配置时不得编造默认内容。
功能描述
读取本点位的展示配置:应用类型、现场模式、播放方式、是否可播放,以及带访问地址的素材清单。响应带 Cache-Control: no-store。2026-10-13 起不再限制门店营业与点位启用,canPlay 恒为 true(字段保留供兼容);mode=agent 时也不返回素材,客户端回到 Agent 互动流程。
重要:2026-10-07 确认所有点位统一由中控Pad控制(迁移 052 已把全部点位改为中控控制),本接口遇到中控点位直接返回 409“此点位由中控播控,请使用v2内容清单与运行回报接口”。因此在当前数据下本接口实际只会返回 409;下方返回示例仅说明旧版非中控点位的响应结构。图文素材和“自定义宽高”显示尺寸也只在 v2 提供。
请求示例
curl "$BASE/api/point-display/config" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL"
返回示例HTTP 200
{
"revision": 3,
"applicationType": "agent",
"mode": "display",
"playMode": "sequential",
"endBehavior": "loop",
"items": [
{
"assetId": "asset_main_visual",
"type": "image",
"durationMs": 10000,
"fit": "contain",
"name": "门店主视觉",
"url": "https://已配置访问域名/asset/...",
"mimeType": "image/png",
"fileSize": 1234,
"sha256": "64位小写十六进制"
}
],
"pointId": "P04",
"pointStatus": "enabled",
"canPlay": true
}
功能描述
展示程序应用某个修订号的配置后,上报“已应用”或“失败及原因”,后台按设备显示。回执是客户端自报,不代表服务端验证过屏幕画面。同一设备只保留最新一条回执。中控播控(v2)使用自己的内容回执接口,见播控配对与配置下发 。
请求示例
curl -X POST "$BASE/api/point-display/ack" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "Content-Type: application/json" \
--data '{"revision":3,"status":"applied","message":""}'
功能描述
用设备凭证自检并刷新设备“最近心跳”时间,返回本设备所属门店与点位。互动点位和纯展示点位的设备都可调用时也可调用。
说明:任何设备接口鉴权成功都会刷新最近心跳,不一定要单独调用本接口;同一设备 30 秒内只写一次库,期间调用仍返回 recorded: true。后台按最近心跳超过 10 分钟判定设备离线(2026-10-06 确认)。
请求示例
curl -X POST "$BASE/api/devices/heartbeat" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "Content-Type: application/json" \
--data '{}'
返回示例HTTP 200
{ "deviceId": "CQ-GUANGHUAN-P04-PLAYER", "storeId": "CQ-GUANGHUAN", "pointId": "P04", "recorded": true }
素材显示尺寸(2026-10-07)
素材规格由CMS上传决定。每个条目的显示尺寸由后台点位素材编排明确选择,随条目下发:
后台保存时未选显示尺寸的条目按 contain 写入(2026-10-07默认值确认),因此下发的条目都带fit;custom缺customSize或数值越界时后台拒绝保存、manifest返回409。v1 读取展示配置 遇到custom条目返回409(自定义显示尺寸需使用v2播控客户端)。客户端不得把缺失或无法识别的显示尺寸替换为其他显示方式,应拒绝该清单并回报错误。
v2条目示例:
{"assetId":"素材ID","type":"image","durationMs":5000,"fit":"custom","customSize":{"widthPct":80,"heightPct":60},"name":"门店主视觉","url":"https://已配置访问域名/asset/...","mimeType":"image/png","fileSize":1234,"sha256":"64位小写十六进制"}
后台保存默认值(2026-10-07确认)
用户确认简化操作:后台保存点位展示配置时,下列字段未填写(缺省或null)即按默认值生效,并把实际取用的值写入已保存配置(客户端读到的始终是明确值,不会出现空值);后台填写的值优先,非法值仍拒绝。
控制方(controlOwner)未传时按中控Pad写入,传其他值返回400:所有点位统一由中控Pad控制(2026-10-07确认)。
纯展示点位(2026-10-07)
后台可为门店新建多个纯展示点位(如一楼超大屏),点位目录类型为“展示屏”(D01),点位编号以D开头。应用类型固定普通展示(applicationType=display),播控固定由中控Pad发信号切换(controlOwner=central_pad),后台保存不自行切画面;暂不做排期。
展示点位的设备只可调用 /api/point-display/*(含v2 manifest/boot/runtime/content-ack)与设备心跳 ;调用互动、扫码登录、当前用户、画像等其他设备接口一律返回403。后台停用的设备调用任何设备接口均返回403(设备已在后台停用)。
现场模式切换
现场模式切换由运维协调,服务端不会因此结束现有用户互动或处理Token。客户端应执行现场操作安排;新的Agent体验在普通展示应用下会被拒绝;2026-10-13 起不再要求播控正在显示互动应用(见开始体验 )。
互动应用开发接入文档 / 公用接口
公用|播控配对与配置下发(2026-10-07) 接口一览
本章供点位PC上的CMS播控软件,以及在后台登记播控的运营、运维人员使用。2026-10-07确认“播控配置简化”:播控首次运行(或本机配置缺失/损坏、AgentOS地址变更、凭据失效)只需输入“AgentOS地址 + 点位码”。身份、点位、规则、运行参数、网页地址、素材域名、接口清单与中控监听参数都由AgentOS下发,播控只读核对。同日确认“中控通信简化”:中控Pad与播控处于专用局域网,取消Pad IP白名单与指令签名,不再下发controllerId、keyId、签名密钥与白名单。互动点位(AIVA面基、AI音乐、AI车衣共创、AI图片生成)与纯展示点位都使用本章接口。旧版展示接口见 展示配置 、展示回执 ;设备心跳见 设备心跳 。
前置迁移:051_player_pairing.sql 未执行前,配对、点位码、播控菜单接口不可用;053_central_pad_lan_ndjson.sql 未执行前,中控Pad登记与设备配置下发不可用;054_player_command.sql 未执行前,后台播放控制接口不可用。后台保存的内容都不代表现场已生效,播控在下一次同步配置时读取。
点位码与绑定规则
运行参数默认值与范围(2026-10-07确认)
后台“播控”菜单未登记运行参数、点位展示未登记运行状态有效期时,按下列默认值下发,并在设备配置中以 runtimeSource / runtimeLeaseSource = default 标注;后台登记的值优先。已登记但内容损坏时不用默认值替代,直接报“配置不完整”。
四项运行参数的取值范围与播控客户端现有校验一致;代码注释标注该范围本身仍待用户确认(待确认)。播控规则在选中控Pad时固定为 {"startup":"wait_for_pad","offline":"play_cached","failure":"report_error","protocol":"ndjson_v1"}:由中控Pad控制切换、断网时使用最后一次同步的配置与素材播放、失败如实报错、局域网明文NDJSON协议。
打开后画面 (2026-10-10,后台“点位详情 → 播控”按点位设置,随设备配置 startupScreen 下发):wait_for_pad 等待中控指令(从未设置过即为此值)、play_cms 自动播放展览内容(后台最新保存的版本;断网启用时按离线规则播放最后同步的版本)、app 自动打开互动应用(仅登记了网页地址的Agent互动点位可选;断网时打不开,报错)。播控每次启用(程序打开自动启用、运维手动启用)后执行一次,与中控指令走同一切换流程;之后中控Pad与后台随时可以切换。自动显示失败照常报错并留本机审计,不改播其他内容、不自动重试。需播控 0.2.0 及以上版本;旧版播控忽略此项,仍等待中控指令。
播控接入顺序
连接向导:调用 播控配对 换取设备凭据,再调用 读取设备配置 ,运维逐项核对后确认。
每次启动:调用 登记启动 取得本次启动序号,读取 内容清单 ,下载素材并校验SHA-256后用 内容回执 回报 ready;随后监听中控端口,再按设备配置 startupScreen 显示打开后画面(wait_for_pad 时画面等待中控指令)。
运行中:每个心跳间隔调用 运行回报 (这就是播控的“心跳”);心跳成功后调用 领取后台指令 ,执行后用 回报指令结果 回报。每个同步间隔重新读取设备配置,profileRevision 变化时自动应用。
断网:使用最后一次同步的配置、中控监听端口与素材继续播放;运行回报与内容回执按发生顺序排队,恢复后按序补报。断网时不能切到互动应用。
每次设备鉴权成功都会刷新该设备的最近心跳时间(30秒内不重复写入),后台据此判断设备是否离线。
播放控制(后台指令)说明(2026-10-07确认)
运维可在任何时候于后台或中控Pad操作,同一点位以最后一条指令为准。后台不能直连现场局域网:后台写入指令,播控在每次运行回报成功后领取并执行,再回报结果。指令写入后 30秒 内未被领取即作废(expired,播控可能离线),播控恢复联网后不会补执行旧指令。
切换画面不结束现有互动、不取消生成任务、不改变Token(与中控Pad切换规则相同)。播控处于“本地接管”时,后台指令与Pad指令一样被拒绝(播控回报失败,原因 LOCAL_LOCKED)。
功能描述
播控电脑凭后台生成的点位码换取设备凭据。服务端为该点位登记一台播控设备(设备类型 player_pc,设备编号 {storeId}-{pointId}-PLAYER;同编号设备已存在且未绑定时复用),并在同一事务写入配对留痕。
调用时机:首次运行、本机配置缺失或损坏、修改AgentOS地址、设备接口返回401(凭据失效)后重新连接时。请求结果未知(如网络中断)时不要换电脑重试,先在后台“播控”菜单核对是否已绑定。
请求示例
curl -X POST "$BASE/api/player/pair" \
-H "Content-Type: application/json" \
--data '{"pointCode":"PC-8K2M4P6R8T0V2X4Z6B9D","machineName":"P02-PLAYER-PC"}'
返回示例HTTP 201
{
"tenantId": "t_saisi",
"storeId": "CQ-GUANGHUAN",
"pointId": "P02",
"deviceId": "CQ-GUANGHUAN-P02-PLAYER",
"deviceToken": "dt_只返回这一次的设备凭据"
}
响应带 Cache-Control: no-store。
错误情况
错误响应体为 {"error":"中文说明","code":"错误码"},不自动重试。
功能描述
返回播控运行所需的全部只读配置:身份、点位、规则、运行参数、网页地址、素材域名、接口清单与中控监听参数。播控以 profileRevision 判断配置是否变化,变化时自动应用;网页地址变化需退出并重新打开播控才生效。
任一必需项缺失时整体返回409并逐条列出缺失项,不下发残缺配置。运行参数、运行状态有效期、中控监听端口未登记时按默认值下发(见上文“运行参数默认值与范围”);网页地址、素材域名等其他项不设默认值。
请求示例
curl "$BASE/api/point-display/v2/device-profile" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL"
返回示例HTTP 200
{
"profileRevision": "9f2c4e7a…(64位十六进制)",
"tenant": { "id": "t_saisi" },
"store": { "id": "CQ-GUANGHUAN", "name": "重庆光环店" },
"point": { "id": "P02", "name": "AIVA面基", "location": "一楼东侧", "catalogId": "P02", "category": "interaction", "applicationType": "agent", "controlOwner": "central_pad" },
"device": { "id": "CQ-GUANGHUAN-P02-PLAYER" },
"protocol": "ndjson_v1",
"policies": { "startup": "wait_for_pad", "offline": "play_cached", "failure": "report_error" },
"runtimeLeaseMs": 20000,
"runtimeLeaseSource": "default",
"runtime": { "networkMs": 3000, "transitionMs": 10000, "pollMs": 30000, "heartbeatMs": 5000 },
"runtimeSource": "default",
"startupScreen": "wait_for_pad",
"screens": [{ "key": "main", "name": "主屏", "width": null, "height": null, "touch": true, "appUrl": "https://p02.example.com/" }],
"appUrl": "https://p02.example.com/",
"apiPaths": ["/api/identity/point-login", "/api/identity/me", "/api/interactions/:id", "…"],
"mediaOrigins": ["https://assets.example.com"],
"control": { "listenHost": "0.0.0.0", "listenPort": 9850, "protocol": "ndjson_v1", "signing": false }
}
响应带 Cache-Control: no-store。原 centralPad 字段已删除。
功能描述
播控每次启动生成一个新的启动编号 bootId 并登记,服务端返回本设备递增的启动序号 bootOrdinal,后续运行回报必须带上这两个值。首次登记会把本设备的运行状态重置为“未显示、未启用”,事件序号归零,因此旧进程的回报会被拒绝。
同一个 bootId 原样重发不会重复登记,返回第一次的序号,也不会再次重置运行状态。
请求示例
curl -X POST "$BASE/api/point-display/v2/boot" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "Content-Type: application/json" \
--data '{"bootId":"b7c1e0d2-5f3a-4c8e-9a11-2d4f6b8c0e13"}'
功能描述
返回点位当前保存的展示配置版本及已审核素材清单(含下载地址、大小与SHA-256),与当前实际显示模式无关。播控下载并校验全部素材后才能切换到该版本;中控或后台切换前也会先读取一次核验最新版本,读取不到(断网)时按离线规则只播放最后同步的版本。
条目显示尺寸 fit、customSize 的含义见 展示模式与素材播放 。
请求示例
curl "$BASE/api/point-display/v2/manifest" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL"
返回示例HTTP 200
{
"schemaVersion": 2,
"tenantId": "t_saisi",
"storeId": "CQ-GUANGHUAN",
"pointId": "D01",
"deviceId": "CQ-GUANGHUAN-D01-PLAYER",
"controlOwner": "central_pad",
"revision": 12,
"applicationType": "display",
"runtimeLeaseMs": 20000,
"playerPolicy": { "startup": "wait_for_pad", "offline": "play_cached", "failure": "report_error", "protocol": "ndjson_v1" },
"playMode": "sequential",
"endBehavior": "loop",
"items": [
{ "assetId": "as_101", "type": "image", "durationMs": 10000, "fit": "contain", "name": "门店主视觉", "url": "https://assets.example.com/asset/…", "mimeType": "image/png", "fileSize": 1234, "sha256": "64位小写十六进制" },
{ "assetId": "as_102", "type": "video", "videoEnd": "next", "muted": false, "fit": "custom", "customSize": { "widthPct": 80, "heightPct": 60 }, "name": "新车宣传片", "url": "https://assets.example.com/asset/…", "mimeType": "video/mp4", "fileSize": 52428800, "sha256": "64位小写十六进制" }
]
}
响应带 Cache-Control: no-store。
功能描述
回报某个内容版本在本机的处理阶段,供后台“点位展示”查看。applied 只能在运行回报已报告该版本CMS稳定显示后提交;同一版本已是 applied 时,之后定期验证提交的 cached/ready 不会把它降回“尚未显示”。
请求示例
curl -X POST "$BASE/api/point-display/v2/content-ack" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "Content-Type: application/json" \
--data '{"revision":12,"stage":"ready","message":"素材已缓存并通过SHA-256校验"}'
功能描述
回报本机实际显示模式、阶段、内容版本、控制方及输出就绪状态。这是播控的“心跳”:按心跳间隔调用,成功后再领取后台指令。
新互动准入(admissionAllowed=true)须同时满足:控制方为中控Pad、应用类型为Agent互动(2026-10-13 起不再看门店营业与点位启用)、最近回报为应用模式稳定显示(app/ready)且网页与输出就绪、回报未超过运行状态有效期。切换前先回报 switching 关闭准入。
服务端拒绝旧进程、乱序和同一序号不同内容的回报。同一序号、内容完全相同的重发不会重复写入,返回已记录结果,也不刷新运行状态有效期。
请求参数Body
phase=ready 时须 actualMode 为 app 或 cms 且 outputReady=true;app 另须 appReady=true,cms 另须 contentRevision 不为空。
请求示例
curl -X POST "$BASE/api/point-display/v2/runtime" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "Content-Type: application/json" \
--data '{"bootId":"b7c1e0d2-5f3a-4c8e-9a11-2d4f6b8c0e13","bootOrdinal":3,"deviceSeq":42,"actualMode":"cms","phase":"ready","contentRevision":12,"owner":"pad","observedAt":"2026-10-08T10:15:30.123+08:00","details":{"appReady":false,"captureStopped":true,"inputEnabled":false,"outputReady":true,"message":"输出组已确认目标画面就绪","paused":false,"closed":false}}'
返回示例HTTP 200
{ "recorded": true, "deviceSeq": 42, "admissionAllowed": false }
功能描述
领取本点位最新一条未过期、待领取的后台指令。返回即标记为已送达本设备,同一条指令只下发一次;没有指令时返回 command: null。领取前服务端先把超过30秒未领取的指令标记为作废。指令含义见上文“播放控制(后台指令)说明”。
请求示例
curl -X POST "$BASE/api/point-display/v2/commands/pull" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "Content-Type: application/json" \
--data '{}'
返回示例HTTP 200
{ "command": { "commandId": "cmd_3f9c0d1e2a4b5c6d7e8f90a1b2c3d4e5", "action": "play_cms", "contentRevision": 12 } }
响应带 Cache-Control: no-store。
功能描述
回报后台指令的执行结果,后台“播放控制”据此显示“已执行”或“执行失败”及原因。同一结果原样重发不会重复写入,返回第一次的结果;已有结果后改成另一种结果会被拒绝。
请求示例
curl -X POST "$BASE/api/point-display/v2/commands/result" \
-H "Authorization: Bearer $DEVICE_CREDENTIAL" \
-H "Content-Type: application/json" \
--data '{"commandId":"cmd_3f9c0d1e2a4b5c6d7e8f90a1b2c3d4e5","status":"applied","message":"已播放展览内容 r12"}'
互动网页可调用的接口清单
设备配置 apiPaths 当前下发以下接口(互动点位);播控只转发清单内的请求,:param 匹配单段:
/api/identity/point-login /api/identity/me /api/identity/logout /api/identity/profile/:resource /api/identity/profile-summary
/api/interactions/config /api/interactions/config/ack /api/interactions /api/interactions/:id
/api/interactions/:id/consent /api/interactions/:id/consent/revoke /api/interactions/:id/answers /api/interactions/:id/confirm
/api/interactions/:id/restart /api/interactions/:id/end /api/interactions/:id/events
/api/interactions/:id/text-tasks /api/interactions/:id/text-tasks/:taskId /api/interactions/:id/image-tasks /api/interactions/:id/image-tasks/:taskId
/api/interactions/:id/tts /api/interactions/:id/voice-tasks/:taskId /api/interactions/:id/result/complete
/api/interactions/:id/music-selection /api/interactions/:id/music-selection/confirm /api/interactions/:id/lyrics /api/interactions/:id/lyrics/confirm
/api/interactions/:id/music-tasks /api/interactions/:id/music-tasks/:taskId /api/interactions/:id/music-tasks/:taskId/check
/api/interactions/:id/works /api/interactions/:id/works/:assetId/preview /api/users/me/works /api/users/me/works/:assetId/preview /api/users/me/assistant
不含:作品原文件二进制(.../works/:assetId/content)、语音识别WebSocket票据、AI音乐旧链路 /api/p03/*、后台接口与设备心跳(由播控主进程自行调用)。
AD-01 · AgentOS 运营后台(point:edit 权限,点位详情“播控”菜单)
生成或重置点位码 POST /api/admin/stores/:storeId/points/:pointId/point-code 鉴权:后台登录
功能描述
为点位生成点位码(互动点位与纯展示点位都可以)。点位码永久有效;已有点位码时须明确选择“重置”并填写原因,重置后旧码作废,同一事务吊销该点位全部已配对播控电脑的凭据,这些电脑须用新码重新配对。
请求示例
curl -X POST "$BASE/api/admin/stores/CQ-GUANGHUAN/points/P02/point-code" \
-H "Cookie: <后台登录会话>" \
-H "X-CSRF-Token: <csrfToken>" \
-H "Content-Type: application/json" \
--data '{"reset":true,"reason":"播控电脑更换,旧码外泄"}'
返回示例HTTP 200
{
"pointCode": "PC-8K2M4P6R8T0V2X4Z6B9D",
"reset": true,
"revokedDeviceIds": ["CQ-GUANGHUAN-P02-PLAYER"],
"note": "点位码只显示这一次,服务端只保存哈希,请立即抄录。旧码已作废,该点位已连接的播控凭据已同时失效,需用新码重新配对。"
}
AD-02 · AgentOS 运营后台(point:view 权限,点位详情“播控”菜单)
查看播控菜单 GET /api/admin/stores/:storeId/points/:pointId/player 鉴权:后台登录
功能描述
读取点位的播控登记情况:是否已生成点位码(不返回码本身)、已绑定与已吊销的播控电脑、运行参数与网页地址、参数范围与默认值、实际生效的运行状态有效期,以及门店中控监听参数。settings.runtime 为 null 表示未登记,播控按默认值运行。
请求示例
curl "$BASE/api/admin/stores/CQ-GUANGHUAN/points/P02/player" \
-H "Cookie: <后台登录会话>"
返回示例HTTP 200
{
"pointKind": "interaction",
"hasPointCode": true,
"pointCodeCreatedAt": "2026-10-07T06:00:00.000Z",
"pointCodeCreatedBy": "staff_001",
"boundDevices": [ { "deviceId": "CQ-GUANGHUAN-P02-PLAYER", "machineName": "P02-PLAYER-PC", "pairedAt": "2026-10-07T06:05:00.000Z", "lastHeartbeatAt": "2026-10-08T02:15:30.000Z", "adminStatus": "active", "revokedAt": null, "revokedReason": null } ],
"unboundDevices": [],
"settings": { "revision": 0, "runtime": null, "appUrl": null, "appUrlAllowed": true, "updatedBy": null },
"runtimeLimits": { "networkMs": { "min": 1000, "max": 120000 }, "transitionMs": { "min": 1000, "max": 120000 }, "pollMs": { "min": 1000, "max": 3600000 }, "heartbeatMs": { "min": 1000, "max": 60000 } },
"runtimeDefaults": { "networkMs": 3000, "transitionMs": 10000, "pollMs": 30000, "heartbeatMs": 5000 },
"runtimeNotes": { "runtimeLeaseMs": "运行状态有效期=4倍心跳,可容忍连续3次心跳丢失", "heartbeatMs": "每5秒回报一次运行状态", "networkMs": "小于心跳间隔,避免请求堆叠,断网判定在3秒内完成", "transitionMs": "覆盖网页加载与媒体停止确认", "pollMs": "兼顾内容更新及时性与请求量" },
"runtimeSource": "default",
"runtimeLeaseMs": 20000,
"runtimeLeaseSource": "default",
"controlOwner": "central_pad",
"centralPadConfigured": false,
"control": { "listenHost": "0.0.0.0", "listenPort": 9850, "protocol": "ndjson_v1", "signing": false, "listenPortSource": "default" },
"note": "点位码永久有效,只在生成/重置时显示一次;同一点位已有绑定时新电脑会被拒绝,须先解绑。"
}
AD-03 · AgentOS 运营后台(device:edit 权限,点位详情“播控”菜单)
解绑播控电脑 POST /api/admin/stores/:storeId/points/:pointId/player/unbind 鉴权:后台登录
功能描述
吊销该点位已绑定播控电脑的设备凭据,保留设备记录供审计。解绑后旧电脑的设备接口返回401;新电脑可用现有点位码重新配对,无需重置点位码。
请求示例
curl -X POST "$BASE/api/admin/stores/CQ-GUANGHUAN/points/P02/player/unbind" \
-H "Cookie: <后台登录会话>" \
-H "X-CSRF-Token: <csrfToken>" \
-H "Content-Type: application/json" \
--data '{"reason":"更换播控电脑"}'
返回示例HTTP 200
{
"unbound": true,
"deviceIds": ["CQ-GUANGHUAN-P02-PLAYER"],
"note": "设备凭据已吊销,设备记录保留可审计;新电脑可用现有点位码重新配对。"
}
AD-04 · AgentOS 运营后台(point:edit 权限,点位详情“播控”菜单)
保存播控运行参数与网页地址 PUT /api/admin/stores/:storeId/points/:pointId/player/settings 鉴权:后台登录
功能描述
登记播控的网络超时、切换超时、同步间隔、心跳间隔,以及互动点位的正式网页地址。四项运行参数保存时须一起填写(页面预填默认值);心跳间隔须小于实际生效的运行状态有效期的一半(有效期未登记时按默认20000毫秒校验)。保存不代表现场已生效,播控在下一次同步配置时读取。
请求示例
curl -X PUT "$BASE/api/admin/stores/CQ-GUANGHUAN/points/P02/player/settings" \
-H "Cookie: <后台登录会话>" \
-H "X-CSRF-Token: <csrfToken>" \
-H "Content-Type: application/json" \
--data '{"expectedRevision":0,"runtime":{"networkMs":3000,"transitionMs":10000,"pollMs":30000,"heartbeatMs":5000},"appUrl":"https://p02.example.com/"}'
返回示例HTTP 200
{
"revision": 1,
"runtime": { "networkMs": 3000, "transitionMs": 10000, "pollMs": 30000, "heartbeatMs": 5000 },
"appUrl": "https://p02.example.com/",
"clientApplied": false,
"note": "播控在下一次同步配置时读取;保存不代表现场已生效。"
}
功能描述
读取门店中控Pad登记:播控监听端口(全店统一)及可选的Pad名称/IP备注。一家门店一台中控Pad,控制该店所有点位;专用局域网内明文NDJSON通信,不做IP白名单与签名。未登记时返回 configured:false,端口按默认9850。
请求示例
curl "$BASE/api/admin/stores/CQ-GUANGHUAN/central-pad" \
-H "Cookie: <后台登录会话>"
返回示例HTTP 200
{
"configured": true,
"listenPort": 9850,
"listenPortSource": "configured",
"padName": "一楼中控Pad",
"padIp": "192.168.10.20",
"revision": 1,
"updatedBy": "staff_001",
"updatedAt": "2026-10-07T08:00:00.000Z",
"defaultListenPort": 9850,
"listenHost": "0.0.0.0",
"portRange": { "min": 1024, "max": 65535 },
"protocol": "ndjson_v1",
"signing": false,
"note": "一家门店一台中控Pad,控制该店所有点位;专用局域网内明文NDJSON通信,不做IP白名单与签名。…"
}
AD-06 · AgentOS 运营后台(device:edit 权限,“门店中控Pad”;门店运维可登记本店)
登记门店中控Pad PUT /api/admin/stores/:storeId/central-pad 鉴权:后台登录
功能描述
登记播控监听端口(全店统一)与可选的Pad名称/IP备注。端口省略或为 null 时按默认9850保存。保存后播控在下一次同步配置时读取;端口变化时播控关闭旧监听、断开已有连接并在新端口监听。
请求示例
curl -X PUT "$BASE/api/admin/stores/CQ-GUANGHUAN/central-pad" \
-H "Cookie: <后台登录会话>" \
-H "X-CSRF-Token: <csrfToken>" \
-H "Content-Type: application/json" \
--data '{"expectedRevision":0,"listenPort":9850,"padName":"一楼中控Pad","padIp":"192.168.10.20"}'
返回示例HTTP 200
{
"revision": 1,
"listenPort": 9850,
"padName": "一楼中控Pad",
"padIp": "192.168.10.20",
"clientApplied": false,
"note": "保存后播控在下一次同步配置时读取;不代表现场已生效。"
}
AD-07 · AgentOS 运营后台(point:edit 权限,点位展示“播放控制”)
发送播放控制指令 POST /api/admin/stores/:storeId/points/:pointId/display/commands 鉴权:后台登录
功能描述
写入一条播放控制指令(立即播放展览、切换应用模式、暂停、继续、退出播放),由播控在下一次心跳后领取执行。新指令写入时,同点位尚未领取的旧指令标记为 superseded,以最后一条为准。返回 pending 只表示已写入,执行结果通过 查看播控运行状态 查看。指令含义见上文“播放控制(后台指令)说明”。
请求示例
curl -X POST "$BASE/api/admin/stores/CQ-GUANGHUAN/points/P02/display/commands" \
-H "Cookie: <后台登录会话>" \
-H "X-CSRF-Token: <csrfToken>" \
-H "Content-Type: application/json" \
--data '{"action":"play_cms"}'
返回示例HTTP 200
{
"commandId": "cmd_3f9c0d1e2a4b5c6d7e8f90a1b2c3d4e5",
"action": "play_cms",
"label": "立即播放展览内容",
"contentRevision": 12,
"status": "pending",
"requestedBy": "staff_001",
"requestedAt": "2026-10-08T02:15:00.000Z",
"expiresAt": "2026-10-08T02:15:30.000Z",
"deviceId": null,
"deliveredAt": null,
"finishedAt": null,
"message": null
}
AD-08 · AgentOS 运营后台(point:view 权限,点位展示“播放控制”与运行状态)
查看播控运行状态 GET /api/admin/stores/:storeId/points/:pointId/display/runtime 鉴权:后台登录
功能描述
读取该点位播控的最新运行回报、内容回执、播放控制可用性与最近10条后台指令。运行回报 details.paused=true 表示展览已暂停,details.closed=true 表示已退出播放。stale=true 表示回报已超过运行状态有效期(播控可能离线)。
请求示例
curl "$BASE/api/admin/stores/CQ-GUANGHUAN/points/P02/display/runtime" \
-H "Cookie: <后台登录会话>"
返回示例HTTP 200
{
"items": [
{ "device_id": "CQ-GUANGHUAN-P02-PLAYER", "boot_id": "b7c1e0d2-…", "boot_ordinal": 3, "device_seq": 42, "actual_mode": "cms", "phase": "ready", "content_revision": 12, "owner": "pad", "details": { "appReady": false, "captureStopped": true, "inputEnabled": false, "outputReady": true, "message": "输出组已确认目标画面就绪", "paused": false, "closed": false }, "observed_at": "2026-10-08T02:15:30.123Z", "updated_at": "2026-10-08T02:15:30.456Z", "admissionAllowed": false, "stale": false }
],
"contentAcks": [ { "device_id": "CQ-GUANGHUAN-P02-PLAYER", "revision": 12, "stage": "applied", "message": "CMS输出组已显示并回报运行状态", "updated_at": "2026-10-08T02:15:31.000Z" } ],
"control": {
"pointEnabled": true,
"latestRevision": 12,
"hasItems": true,
"appAvailable": true,
"commands": [ { "commandId": "cmd_3f9c…", "action": "play_cms", "label": "立即播放展览内容", "contentRevision": 12, "status": "applied", "requestedBy": "staff_001", "requestedAt": "2026-10-08T02:15:00.000Z", "expiresAt": "2026-10-08T02:15:30.000Z", "deviceId": "CQ-GUANGHUAN-P02-PLAYER", "deliveredAt": "2026-10-08T02:15:05.000Z", "finishedAt": "2026-10-08T02:15:31.000Z", "message": "已播放展览内容 r12" } ]
}
}
中控Pad TCP 协议(文本指令 + ndjson_v1,2026-10-10确认)
本节不是 HTTP 接口:中控(Pad 经中控网关,如哈曼视听逻辑编程软件)在门店专用局域网内直接连接播控。播控监听本机所有网卡 0.0.0.0,端口由设备配置 control.listenPort 下发(后台“门店中控Pad”登记,全店统一,默认9850)。不校验来源IP、指令不签名,因此专用局域网内任何设备都能向播控发送指令 ,该局域网须与访客Wi-Fi、办公网和公网隔离。同一端口同时接收两种格式:以 { 开头的按 JSON 指令处理,其他按文本指令处理。
文本指令(推荐,2026-10-10 用户确认)
中控网关每个按钮只能发一个固定字符串 ,因此播控提供文本指令:发一个英文单词就执行对应动作,全部点位用同一套单词。
网关配置(以哈曼视听逻辑编程软件为例) :每台播控电脑一个 tcp out 节点——类型“连接”、主机地址填播控电脑的局域网IP、端口填后台“门店中控Pad”的端口(默认9850)、不勾选 “是否在成功发送每条信息后断开连接”;“通用控制”节点第一列填 Pad 发来的按钮编号(如 custom37_1),第二列填上表的发送文本(如 PLAY),第三列不填。“开馆模式”按钮可同时向多台播控发送 PLAY 或 APP。各播控的IP与可用指令见后台“点位总览 → 门店中控Pad → 指令对照表”(可导出CSV)。
JSON 指令(ndjson_v1,兼容保留)
指令字段(2026-10-10 补充每个字段由谁提供):
示例(实际发送为单行并以LF结尾;点位与版本不能照抄到现场):
{"v":1,"requestId":"pad-0001","pointId":"实际点位ID","command":"SET_MODE","mode":"cms","contentRevision":12}
回执:每条有效指令先回复 accepted(已写入本机账本),再回复最终结果;格式或点位错误直接回复 rejected 与 errorCode。常见 errorCode(文本指令的 ERR 原因与之对应):
后台指令与中控指令同等对待,同一点位以最后一条为准(播控 0.3.0 起已取消“本机接管”)。联调没有真实Pad时,可在播控目录用 node tools/pad-sim.cjs <播控IP> PLAY(文本指令,与网关一样不带换行)或 node tools/pad-sim.cjs <播控IP> <点位ID> cms <内容版本号>(JSON 指令)模拟发送,仅限联调。
互动应用开发接入文档 / 公用接口
公用|用户资料字段
以下为当前用户profile接口允许的数据域字段,保留snake_case。可空字段可返回null;JSON字段按响应结构读取,不把字段存在理解成相应生成能力已开放。
assets
tags
interactionAnswers
profileContributions
interactionDesigns
互动应用开发接入文档 / ONEID 会员
ONEID 会员对外接口(已单独成文)
与 AIVA 官方 ONEID 会员相关、供 AIVA 小程序服务端对接的接口(B02—B06 身份绑定、作品删除与作品码查询,以及 AgentOS 调用 AIVA 的太阳码 M01、二维码扫码识别、绑定结果推送、作品数据推送)已单独归类,见《ONEID 会员对外接口文档》:http://aiva.docs.vavedigital.com/api-docs/oneid.html 。点位客户端只使用本文的“扫码登录、当前用户与退出”。
互动应用开发接入文档 / 联调验收
联调|互动点位接口调试工具(2026-10-11)
AgentOS 提供网页调试工具:https://aiva.dev.vavedigital.com/admin/tools/point-test/(与业务接口同域名)。工具模拟互动点位客户端,覆盖本文中互动点位调用的全部接口:配置与登录、体验、文本/图片任务、语音合成、上传录音识别(2026-10-14,麦克风录音或音频文件,自动转 16kHz WAV)与流式语音识别(麦克风或音频文件)、作品读取、AI音乐、AI车衣共创。
按互动走流程 :左侧可选 AIVA面基、AI音乐、AI图片生成、AI车衣共创,按本文“页面操作与调用顺序”逐步调用;用户会话、体验编号、任务号、修订号、作品编号、风格对话选中的风格等从响应自动填入后续请求,可在“流程变量”中手改。
请求与响应 :填写时实时显示完整请求(地址、请求头、请求体、curl),请求体模板按已读取的配置生成(如每题第一个选项),可直接改 JSON 测非法参数;“原样重发上一次”用于验证同一请求号不会重复执行;任务查询可“轮询到结束”;作品图片、音频、作品小程序码、语音合成音频直接预览。常见 401/403/409/422/503 给出排查提示。
需要准备 :互动点位设备凭证(后台“点位详情 → 设备接入”复制);测试来宾卡短码,或真实的 AIVA 小程序会员码内容(只能用一次,需后台已登记 AIVA 网关及 sourceApp / scanSourceApp)。2026-10-13 起不再要求该点位播控电脑开机或正在显示互动应用,播控关机时也可调试。
注意 :调用真实接口,会建立体验、写入作答与作品,文本/图片/语音/音乐任务会真实调用模型、产生厂商费用并冻结/扣除测试用户 Token,只用于测试环境。凭证只保存在浏览器本标签页,预览与 curl 中只显示末4位。播控接口、已停用的打印接口不在工具中。
互动应用开发接入文档 / 联调验收
AIVA面基双点位免扫码 Demo(2026-10-10)
P02 与 P02B(AIVA面基2)是同一产品目录 P02 的两个独立实例。第二台首次复制本店 P02 最新已保存草稿与点位模型绑定,之后独立修改;不复制点位码、设备凭据、体验和运行回执。P02 保留原配置表;P02B 使用 interaction_config_revision 的独立 point_id,不回退读取 P02。
POST /api/admin/stores/:storeId/p02/workspace/copy-second:{confirm:true}。须 point:create、point:edit、model_bind:edit、prompt:edit 权限及门店范围;事务锁定门店,重复创建返回409、不覆盖。
/api/admin/stores/:storeId/p02b/workspace 及 options、overview、records、score、preview、check、tests 与第一台同结构,仅操作 P02B。
POST /api/admin/stores/:storeId/:point/workspace/enable-demo(point 为 p02 或 p02b):{confirm:true,reason:"现场测试原因"}。仅系统管理员;检查 Demo 配置、已配对电脑与播控配置后显式沿现有状态流程启用,允许越过正式链路未完成的发布阻塞,敏感审计留痕。不自动切屏,不代表生产配置发布;测试结束转维护。
第一台网页 /meet/?storeId=<门店>&pointId=P02,第二台 pointId=P02B;播控网页以已鉴权的本机上下文覆盖 URL 点位/门店,不向页面下发设备密钥。
第一台 Demo 使用 /api/p02/demo/,第二台使用 /api/p02b/demo/。config、start、:id/consent、start-image、generate、generation-status、greeting-image、chat、tts、finish 语义保持一致;ASR 分别使用 /api/p02/demo/asr 与 /api/p02b/demo/asr,带 storeId/sessionId。会话随机 ID 必须同时匹配门店与点位,交叉使用返回404。
EXE 桥接仅新增实际点位的 Demo start 接口;携设备凭据时检查点位、门店与当前播控准入。后续模型长请求和 ASR 使用原 Demo 随机会话,不受播控心跳的短网络超时影响。不增加自动付费重试。
两台及其他面基体验合计共用单进程6个在途生图槽;不是每台6路。首图满槽仍429,挥手图保留既有等待与取消规则。次数上限按门店+点位独立计数。单进程,不据此启动多个副本。
依旧是 P02_DEMO_ENABLED 控制的临时匿名 Demo:有真实厂商用量及体验留存(2026-10-13 起作品以原文件存入公开读的对象存储),不等于真实扫码、正式内容审核和业务 Token 结算。切走互动会停止摄像头、录音、ASR和声音,已提交任务不取消;切回保持页面,摄像头由用户点击重新打开。
互动应用开发接入文档 / 联调验收
后台|AI 音乐上屏配置检查(2026-10-10)
GET /api/admin/stores/:id/points/:pointId/music-inspection:后台登录、point:view 权限及租户/门店范围校验;只读,不调用厂商、不解密凭据、不创建测试授权、不发布版本、不切换现场画面。
sections 分别返回正式模型/审核配置、已批准点位 P03/D100 的测试模型配置、已登记应用网址及播控运行回报;每项 state 为 pass / error / pending,message 提供缺项或下一步。正式检查与 /api/p03/readiness 共用校验;审核检查读取与实际审核相同的平台参数。
providerTested:false、clientConfigConfirmed:false:配置检查不代表真实厂商调用成功,不把播控显示状态冒充模型配置版本回执。真实身份、Token 结算及生成效果仍须联调。
当前 /api/p03 使用能力绑定,绑定保存后直接供运行接口解析,已有对话可能持有旧模型,应新开体验验证。统一互动接口的版本化问卷发布不是当前上屏链路的应用操作;题目与提示词迁移尚未完成,不据此宣称其已生效。
互动应用开发接入文档 / 联调验收
联调检查|按客户端可见结果验收
网络请求结果未知时先查询已有体验/方案;有requestId的操作重放必须保持同一个ID和相同内容,不能换ID重发造成重复。没有说明“同一请求号重发不会重复执行”的操作,不能假设可以安全重试。当前没有客户端收费/退款接口,不能在本地计算后自行修改Token余额。
此文档只描述实际服务端契约及明确的接入缺口;线上文档可访问不代表业务API、现场客户端或模型生产链路已验收。
AgentOS · 互动应用开发接入文档 · 以当前实现为准