让AI长出耳朵和眼睛！扣子多模态 API 对话与流式 WebSocket 音视频实操

在智能穿戴设备（如智能眼镜、车载助手）的开发中，用户常常需要通过纯语音来唤醒智能体，并利用身上的摄像头拍张照片直接传给 AI 进行识别：“看看我面前这是什么地标？”、“识别一下这张报错截图是怎么回事？”

这种“语音触发+图片上传”的多模态联合理解，能够让你的 AI 应用体验直接拉满。

在扣子平台，你可以非常轻松地通过 API 或者更底层的双向流式协议（WebSocket/RTC）来实现这种高阶音视频交互。

今天，我就手把手带大家用 Python 代码把这套多模态双通道交互打通。

---

方案一：基于发起对话 API (适合轻量轮询场景)

如果你的应用不需要毫秒级的实时语音对讲，只是普通的“语音提问 + 传图”交互，那么使用扣子官方的 API 对话接口是最省心的方法。

交互时序流程

sequenceDiagram
    participant 客户端 as Client
    participant 扣子API as Coze API
    participant 智能体 as Agent (Vision Model)

    Client->>Coze API: 1. 上传语音/图片文件 (files.upload)
    Coze API-->>Client: 返回语音 file_id & 图片 file_id
    Client->>Coze API: 2. 发起对话 (chat.stream / chat.create) 传入双 file_id
    Coze API->>智能体: 智能体解析语音与图片内容联合计算
    智能体-->>Client: 3. 流式返回文本/语音答复

Python 实战代码

我们首先将音频文件和图片文件上传至扣子的统一文件管理空间，获得它们各自的唯一 ID，接着直接调用 /v3/chat 接口发起请求：

import secrets
from coze import Coze, Message, MessageObjectString

# 1. 初始化 Coze 客户端
coze = Coze(api_key="your_coze_api_key")

# 2. 将本地的语音和图片文件分别上传，获取 file_id
audio_file = coze.files.upload(file="./raw_question.wav")
image_file = coze.files.upload(file="./screen_error.png")

# 3. 发起对话，并在 additional_messages 中以对象形式合并塞入
stream = coze.chat.stream(
    bot_id="your_bot_id",
    user_id=secrets.token_urlsafe(16),
    additional_messages=[
        Message.build_user_question_objects(
            [
                # 塞入图片文件 ID
                MessageObjectString.build_image(file_id=image_file.id),
                # 塞入语音文件 ID
                MessageObjectString.build_audio(file_id=audio_file.id),
            ]
        )
    ],
)

# 4. 流式获取理解后的文本输出
print(f"--- 对话开始 (LogID: {stream.response.logid}) ---")
for event in stream:
    if event.event == "conversation.message.delta":
        print(event.message.content, end="", flush=True)

---

方案二：基于 WebSocket 双向流式通话 (适合毫秒级实时对讲)

如果你在开发类似 AI 眼镜、智能机器人这种需要极高实时性、甚至能打断对话的硬件，你就必须采用双向流式 WebSocket 通道。

交互时序流程

sequenceDiagram
    participant 客户端 as Client (WebSocket)
    participant 扣子网关 as Coze WS Gateway
    participant 对话流 as Chat Flow (sys_images)

    Client->>Coze WS Gateway: 1. 握手建立连接 (携带 bot_id)
    Client->>Coze WS Gateway: 2. 发送 chat.update 上行事件 (带入图片 file_id)
    Coze WS Gateway->>对话流: 将图片挂载为对话流的 image 入参
    loop 流式语音传送
        Client->>Coze WS Gateway: 3. input_audio_buffer.append (发送音频块数据)
    end
    Client->>Coze WS Gateway: 4. input_audio_buffer.complete (发送语音结束)
    Coze WS Gateway-->>Client: 5. 实时返回语音/文本响应流

Python 实战代码

在双向流式通话中，我们在建连后首先下发一个 chat.update 事件，把图片参数作为变量传给底层的对话流（Chat Flow），然后再像打电话一样持续切片追加发送音频流：

import json
import asyncio
from coze.websockets import ChatUpdateEvent, InputAudioBufferAppendEvent

# 1. 建立双向流式对话客户端
chat = coze.websockets.chat.create(
    bot_id="your_bot_id",
    on_event=MyWebsocketsChatEventHandler(), # 绑定你的事件处理器
)

# 2. 连接并发送交互
async with chat() as client:
    print("WebSocket 通道连接建立成功！")

    # 【避坑重点】必须先发 chat_update，将图片 ID 挂到对话流的输入参数中
    await client.chat_update(
        ChatUpdateEvent.Data.model_validate({
            "chat_config": {
                "parameters": {
                    "image": json.dumps({
                        "file_id": "your_uploaded_image_file_id"
                    })
                }
            }
        })
    )

    # 3. 持续读取并模拟流式发送语音数据 (分块传送，大小控制在 1024 字节)
    with open("./voice_command.pcm", "rb") as f:
        audio_data = f.read()

    for chunk in split_bytes(audio_data, 1024):
        await client.input_audio_buffer_append(
            InputAudioBufferAppendEvent.Data.model_validate({
                "delta": chunk
            })
        )
        # 模拟真实的说话流速间隔
        await asyncio.sleep(len(chunk) / 24000.0) 

    # 4. 告知 AI 说话完毕，等待返回
    await client.input_audio_buffer_complete()
    await client.wait()

---

💡 总结与开发避坑指南

1. 模型能力选取：不论哪种方案，扣子后端的单 Agent 或工作流的主体模型，都必须选择支持视觉理解的模型（如 Doubao-vision-pro 系列），否则在解析 file_id 时会发生报错。
2. WebSocket 握手频率：硬件终端在断线重连时需要做好指数退避（Exponential Backoff）重试，避免因为高频重连被扣子网关触发限流防御机制。

大家可以根据自己硬件和网络带宽条件，选择最匹配的多模态方案，让你的 AI 智能体长出灵敏的耳朵和锐利的眼睛！