VIBE Pod 后端 API 总览

已实现接口

GET`/health`

健康检查，返回服务状态和当前 adapter。

响应：status、service、adapter
用于 Android/Web 启动前检查后端是否在线。

GET`/api-overview`

后端自带中文 API 总览页；Cloudflare 这里是静态镜像版。

本地地址：http://127.0.0.1:8080/api-overview
公网静态页只展示文档，不转发 API。

POST`/v1/ai/persona-reply`

根据角色状态、场景、证据和按钮输入生成小人中文短台词。

输入包含 characterId、characterState、stageEffects。
输出 text 最多 40 字，并回传角色屏幕契约。

POST`/v1/ai/tts`

把角色台词生成语音，当前是一次性 TTS。

fake 返回 base64 占位音频。
真实 adapter 走 shareapi.audio.tts。
当前不是流式语音。

POST`/v1/ai/image`

提交角色舞台图片任务，服务端调用 GRSAI。

aspectRatio 固定 3:4。
model 支持 nano-banana 系列。
移动端不传 GRSAI API Key。

GET`/v1/ai/image/{task_id}?model=nano-banana`

查询图片任务状态。提交时用了哪个模型，查询时也传同一个模型。

响应包含 status、url、results。

POST`/v1/ai/video`

提交角色舞台短视频生成任务，服务端调用 shareapi video / Bowong。

输入包含 prompt、imageUrl、seconds、resolution。
输出包含 taskId、videoUrl、provider、model。

shareapi 已有但 VIBE 移动端未直接暴露

能力	shareapi 入口	当前 VIBE 后端状态
LLM 普通对话	`llm.chat` / `llm.complete`	只通过 `/v1/ai/persona-reply` 封装成角色短台词。
LLM 流式文本	`llm.stream`	未暴露移动端 HTTP/SSE 接口。
Vision 图像理解	`vision.ask`	未暴露；后续可用于小卡/相机识别。
文件上传	`storage.upload_file` / `upload_bytes`	未暴露；移动端暂不直接上传供应商素材。
Realtime 连接测试	`AzureRealtimeClient`	未暴露正式实时语音 API。
Gateway 管理	`create_gateway_router`: routes/prompts/tasks	未挂到 VIBE 后端，避免移动端修改模型路由。
生成任务监控	`shareapi-monitor`: image/video tasks	是本地/运维工具，不是移动端 API。

还没有实现

流式语音和实时语音还没有正式 API。 当前只有 POST /v1/ai/tts 一次性生成语音。shareapi 已有 Azure Realtime client 和 LLM 文本流，但 VIBE 后端还没有 POST /v1/ai/tts/stream、SSE 或 WS /v1/ai/realtime/voice。

公共请求上下文

字段	说明
`requestId`	客户端请求 ID，便于追踪。
`sceneId` / `scenePhase`	场景 ID 和生命周期阶段。
`characterId`	角色 ID，所有台词、语音和图片都围绕这个角色。
`characterState`	角色当前心情、姿态、表情、服装、道具和记忆标签。
`stageEffects`	角色舞台效果，驱动 3:4 屏幕里的小人、背景、字幕、音效和震动。
`virtualButton`	下半屏虚拟按钮事件，例如大红钮、贴贴、捏握、靠桌、好热、好冷。
`manualEvidence`	由虚拟按钮或用户主动输入产生的手动证据。
`outputContract`	输出约束，包含 `maxChars <= 40` 和 `characterScreen.aspectRatio = 3:4`。

StageEffect

{
  "effectId": "study_room_quiet",
  "sceneId": "late_night_comfort",
  "stageId": "main_character_stage",
  "aspectRatio": "3:4",
  "characterId": "mika",
  "characterPose": "desk_rest",
  "facialExpression": "soft_smile",
  "backgroundState": "bedroom_night",
  "propState": ["blanket"],
  "screenEffect": ["soft_glow"],
  "subtitle": "我把声音放轻一点。",
  "audioCue": "soft_tts",
  "hapticPattern": "soft_pulse",
  "responseMods": {
    "animationEnergy": 0.42,
    "hapticIntensity": 0.3,
    "voiceExcitement": 0.2
  }
}

GRSAI 图片模型

模型名	用途
`nano-banana`	默认模型，适合角色舞台图片。
`nano-banana-fast`	更快的图片生成或编辑。
`nano-banana-2`	新一代模型，适合质量优先的角色图。
`gpt-image-2`	保留兼容。
`gpt-image-2-vip`	保留兼容。

视频接口

字段	说明
`prompt`	角色舞台视频描述。后端会补充 3:4 角色屏幕、固定镜头、一致性等约束。
`model`	默认 `Doubao/Seedance-2-0-fast`，也可传 Bowong 支持的模型字符串。
`imageUrl`	可选参考图 URL，用于保持角色形象。
`seconds`	1 到 15 秒。
`resolution`	默认 `720p`。

最小 curl

curl -s http://127.0.0.1:8080/health

curl -s -X POST http://127.0.0.1:8080/v1/ai/image \
  -H 'Content-Type: application/json' \
  -d '{"requestId":"req-1","sceneId":"late_night_comfort","scenePhase":"enter","intensity":0.7,"characterId":"mika","prompt":"3:4角色屏幕里的小人待机图","model":"nano-banana","aspectRatio":"3:4","consentScope":["image_generation"],"outputContract":{"locale":"zh-CN","maxChars":40,"characterScreen":{"aspectRatio":"3:4"}}}'

已实现接口

GET/health

GET/api-overview

POST/v1/ai/persona-reply

POST/v1/ai/tts

POST/v1/ai/image

GET/v1/ai/image/{task_id}?model=nano-banana

POST/v1/ai/video