模型BYOK与搜索接口

本文供客户开发人员实现模型与搜索 API。客户提供符合本文协议的服务地址、模型 ID 和可选 API Key，由 QwenWork 发起调用。

调用方向：QwenWork → 客户服务；响应方向相反。 客户只需实现需要接入的能力。示例中的域名、模型 ID、内容和请求标识均可替换，字段名称、层级、状态值及事件名保持不变。

按能力阅读：对话 · 异步任务 · 图片 · 视频 · 音乐 · 实时语音识别 · 搜索。

1. 协议与接口清单

协议名称不进入请求体。model 使用实际模型 ID；搜索不发送 model。

各能力的请求与响应按对应章节实现；不支持的参数应明确报错。

2. 公共连接约定

2.1 Endpoint 与协议选择

客户提供完整调用地址；异步图片和视频另外交付包含 {task_id} 的完整查询地址。例如：

• 图片须明确选择 Sync 或 Async；两者均可使用自定义路径。Sync 无查询接口，Async 必须提供查询接口。
• ASR 路径须保留 /api-ws/v1/inference 或 /api-ws/v1/realtime 后缀，可增加网关前缀。
• K8S 支持 HTTP(S) 和 WS(S)、集群域名、私网 IP、自定义端口；地址必须从 QwenWork 服务所在网络可达。使用 TLS 时证书链须有效。
• HTTP Endpoint 不带 query、fragment 或 URL 用户名密码；ASR 的 model query 例外见第 8 节。接口直接响应，不依赖重定向。完整 Endpoint 不会自动追加 /v1。

2.2 Header 与鉴权

三个关联 Header 共用“透传第三方用户 ID”开关，无需另行开启会话或轮次透传。主模型 Agent 对话按各字段的可用值独立发送，缺失字段省略；专项模型和搜索服务只透传第三方用户 ID。

表中 Header 按约定处理。客户服务应允许未使用的额外请求头；异步接口无需识别或校验异步标记 Header。

API Key 均可选。 关联 Header 不替代鉴权；网页搜索的 userId/requestId 保留其请求体语义。

2.3 成功、失败与文件结果

同步成功须返回最终结果；异步提交须返回任务 ID，成功查询须返回产物。使用规定的字段和层级，不额外包装响应。

产物返回可下载的绝对 URL，文件格式须正确且非空。下载请求不携带接口 Bearer；需要鉴权时提供有效期充足的签名 URL。

输入图片支持约定的 URL 或 Data URI。客户服务须能读取 URL，或解码 Data URI。

3. Chat Completions：主模型、视觉理解与语音润色

3.1 普通请求与响应

QwenWork 对已配置的完整 Endpoint 发送 POST：

{
  "model": "company-chat",
  "messages": [{"role": "user", "content": "你好，请介绍一下自己。"}],
  "stream": false
}

客户服务返回：

{
  "id": "chat-001",
  "object": "chat.completion",
  "created": 1789420800,
  "model": "company-chat",
  "choices": [{"index": 0, "message": {"role": "assistant", "content": "你好，我是企业助手。"}, "finish_reason": "stop"}],
  "usage": {"prompt_tokens": 12, "completion_tokens": 8, "total_tokens": 20}
}

model 使用实际模型 ID。messages 保持 system、user、assistant、tool 的顺序；消息内容可能是字符串，也可能是内容块数组。

3.2 流式输出和工具调用

stream=true 时，返回 Content-Type: text/event-stream，逐条发送 SSE；每条 data: 记录后有一个空行：

data: {"id":"chat-001","object":"chat.completion.chunk","created":1789420800,"model":"company-chat","choices":[{"index":0,"delta":{"role":"assistant","content":"你好"},"finish_reason":null}]}

data: {"id":"chat-001","object":"chat.completion.chunk","created":1789420800,"model":"company-chat","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

用于 Agent 的模型还需支持 tools、tool_choice、assistant 的 tool_calls 和 tool 角色的 tool_call_id。流式工具调用通过 delta.tool_calls 返回，各工具用稳定的 index/id 区分；function.arguments 是可分段拼接的 JSON 字符串。完成工具调用时使用 finish_reason: "tool_calls"。

支持 stream_options.include_usage=true，在结束前返回 usage；未知用量不伪造为 0。推理及其他扩展参数由双方约定。

工具请求示例：

{
  "model": "company-chat",
  "messages": [{"role":"user","content":"查询订单 order-demo 的状态。"}],
  "tools": [{"type":"function","function":{"name":"lookup_order","description":"查询订单状态","parameters":{"type":"object","properties":{"order_id":{"type":"string"}},"required":["order_id"]}}}],
  "tool_choice": "auto",
  "stream": false
}

模型要求调用工具时，响应示例：

{
  "id":"chat-tool-001","object":"chat.completion","created":1789420800,"model":"company-chat",
  "choices":[{"index":0,"message":{"role":"assistant","content":null,"tool_calls":[{"id":"call-001","type":"function","function":{"name":"lookup_order","arguments":"{\"order_id\":\"order-demo\"}"}}]},"finish_reason":"tool_calls"}]
}

后续请求会包含这条 assistant 消息，以及例如 {"role":"tool","tool_call_id":"call-001","content":"已发货"} 的工具结果消息。客户服务必须保留它们的对应关系，不把工具结果重写成无关联的普通 user 文本。

3.3 图片输入

视觉理解使用同一 POST 接口，图片作为消息内容块传入：

{
  "model": "company-vl",
  "messages": [{"role": "user", "content": [
    {"type": "text", "text": "这张图片里有什么？"},
    {"type": "image_url", "image_url": {"url": "https://assets.example/input.png"}}
  ]}],
  "stream": false
}

图片也可能以 Data URI 传入；客户服务应按双方确认的输入方式处理。语音润色使用纯文本消息，返回优化后的文字。

3.4 接入预检请求

QwenWork 的主模型连通性预检会向 Chat Endpoint 发送短请求，接口需支持以下字段组合：

{"model":"company-chat","messages":[{"role":"user","content":"OK"}],"max_tokens":1,"stream":false,"enable_thinking":false}

预检包含 enable_thinking=false。客户服务须接受该字段并关闭推理。

4. 图片与视频共用的异步任务流程

QwenWork → 提交 Endpoint：POST 生成请求
客户服务 → QwenWork：task_id + task_status
QwenWork → 查询 Endpoint：GET，替换 {task_id}
客户服务 → QwenWork：任务状态；成功后附产物 URL
QwenWork → 产物 URL：下载文件并保存到企业对象存储

异步提交由接口协议确定，无需通过额外 Header 开启。客户服务直接接收提交请求并返回任务 ID。

提交和查询使用同一模型配置的可选 API Key。查询使用约定的完整地址，例如 https://media.example/tasks/{task_id}；占位符必须恰好出现一次，并单独占一个路径段。不要通过提交响应另行指定查询服务器。

提交成功返回 2xx JSON，不要求 202 + Location：

{"request_id":"req-submit-001","output":{"task_id":"task-001","task_status":"PENDING"}}

处理中查询返回：

{"request_id":"req-query-001","output":{"task_id":"task-001","task_status":"RUNNING"}}

任务 ID 使用字母、数字、-、_、.、:，最长 200 个字符，不能是单独的 . 或 ..。查询返回的 ID 必须与请求一致，任务完成后不能回到处理中。已知任务需要在约定保留期内持续可查，包括 客户服务 实例重启之后。

任务失败示例：

{"request_id":"req-query-002","output":{"task_id":"task-001","task_status":"FAILED","code":"InvalidParameter","message":"Unsupported size."}}

提交响应丢失不等于任务未创建。对接方应按“结果未知”处理，不依赖 QwenWork 重发生成 POST；查询可以继续查询原任务。

5. QwenWork Image Sync / Async：图片生成与编辑

5.1 两种合同的区别

Sync 和 Async 共用以下请求结构。Sync 须在同一次响应中返回图片；Async 须提供任务提交和查询接口。

5.2 共用请求体

文生图的 POST 请求：

{
  "model": "company-image",
  "input": {
    "messages": [{
      "role": "user",
      "content": [{"text": "一间明亮的花店。"}]
    }]
  },
  "parameters": {"n": 1, "size": "1024*1024", "watermark": false}
}

图像编辑时，参考图在前、文字在后；同一接口接收：

{
  "model": "company-image",
  "input": {
    "messages": [{
      "role": "user",
      "content": [
        {"image": "https://assets.example/source.png"},
        {"text": "把背景改成浅蓝色，保留主体。"}
      ]
    }]
  },
  "parameters": {"n": 1, "watermark": false}
}

输出 PNG，编辑输入 1–3 张。支持尺寸： 1024*1024、1536*1024、1024*1536、2048*2048、2048*1152，以及省略 size 的自动尺寸。接入前确认服务支持这些参数。

5.3 Sync 成功与失败响应

对同一次 POST 返回 HTTP 200、Content-Type: application/json：

{
  "request_id": "req-image-sync-001",
  "output": {
    "choices": [{
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": [{"image": "https://assets.example/result-001.png"}]
      }
    }]
  }
}

QwenWork 按顺序读取 output.choices[].message.content[].image。每张图片一个 image 项，type 不是必填字段。至少返回一张有效图片，不超过请求的 n；返回后这些地址必须可以下载。Sync 不要求 task_id/task_status，也不会因为响应中出现它们而开始轮询。

失败使用非 2xx，例如参数不支持时返回 HTTP 400：

{"request_id":"req-image-sync-002","code":"InvalidParameter","message":"Unsupported image size."}

缺少图片、图片地址无效或文件无法下载均不能视为生成成功。Sync 接口及中间网关要允许完整生成所需的请求时长；生成响应超时应保留“结果未知”的判断，不自动重新提交生成。

5.4 Async 提交与查询响应

向 Async Endpoint 提交相同请求体，先返回任务：

{"request_id":"req-image-async-001","output":{"task_id":"image-001","task_status":"PENDING"}}

随后按第 4 节轮询。任务成功时的 GET 响应：

{
  "request_id": "req-image-query-001",
  "output": {
    "task_id": "image-001",
    "task_status": "SUCCEEDED",
    "choices": [{
      "message": {"role": "assistant", "content": [{"image": "https://assets.example/result-001.png"}]}
    }]
  }
}

任务状态使用第 4 节的固定枚举。查询必须返回相同的 task_id；SUCCEEDED 的查询必须有图片。提交接口即使直接返回 SUCCEEDED，也应确保后续查询可以取得最终产物，不能依赖提交响应替代查询接口。

6. QwenWork Video：视频生成

使用第 4 节的异步提交与查询。基础请求：

{
  "model": "company-video",
  "input": {"prompt": "镜头缓慢掠过山间湖泊。"},
  "parameters": {"duration": 5, "resolution": "720P", "watermark": false, "prompt_extend": false}
}

6.1 基础参数

生成方式由 input.media 决定，不另传 operation：

6.2 可选扩展

以下字段仅在指定时发送；未指定时省略。接入前确认支持范围，有效值不得静默忽略，不支持时返回参数错误。

6.3 成功查询

{"request_id":"req-video-001","output":{"task_id":"video-001","task_status":"SUCCEEDED","video_url":"https://assets.example/result.mp4"}}

video_url 必须指向可下载的 MP4。失败状态和格式见第 4、10 节。

7. QwenWork Music：音乐生成

对完整音乐 Endpoint 发送 POST，在同一次 HTTP 响应中返回音频地址：

{
  "model": "company-music",
  "input": {
    "prompt": "温暖轻快的原声吉他音乐。",
    "lyrics": "清晨的风吹过窗前",
    "format": "mp3",
    "enable_aigc_watermark": false
  }
}

{"request_id":"req-music-001","output":{"audio":{"url":"https://assets.example/song.mp3","id":"audio-001"},"finish_reason":"stop"}}

同一次 HTTP 响应返回 output.audio.url；audio.id 仅为音频标识，无任务查询。接口和网关应支持生成所需的长请求。

8. QwenWork Realtime：实时语音识别

两种接口均为实时双向流式识别：持续发送音频，同时接收转写结果。按 Endpoint 选择音频编码和控制事件。

8.1 实时流式 ASR（二进制音频）

Endpoint 为 /api-ws/v1/inference，模型 ID 放在消息体中，地址不带 query。

1. 完成 WebSocket 握手；如配置密钥，握手包含 Bearer Header。
2. QwenWork 发送 run-task，客户服务回应 task-started。
3. QwenWork 开始发送 PCM16、单声道、16 kHz 的二进制音频帧；客户服务持续返回识别结果。
4. QwenWork 发送 finish-task；客户服务返回剩余结果和 task-finished。

启动消息：

{
  "header": {"action": "run-task", "task_id": "asr-001", "streaming": "duplex"},
  "payload": {
    "task_group": "audio", "task": "asr", "function": "recognition",
    "model": "company-asr-streaming",
    "parameters": {"format": "pcm", "sample_rate": 16000}, "input": {}
  }
}

客户服务 就绪消息：

{"header":{"event":"task-started","task_id":"asr-001"},"payload":{}}

识别结果：

{
  "header": {"event": "result-generated", "task_id": "asr-001"},
  "payload": {
    "output": {"sentence": {"sentence_id": 1, "text": "现在开始会议。", "sentence_end": true, "heartbeat": false}},
    "usage": {"duration": 2.5}
  }
}

sentence_id 从 1 开始标识句子。sentence_end=false 的文本可被同句后续结果修订，true 才是该句最终文本。usage.duration 为任务累计用量，不逐句相加。句子结束不等于整个任务结束。

结束消息及确认：

{"header":{"action":"finish-task","task_id":"asr-001","streaming":"duplex"},"payload":{"input":{}}}

{"header":{"event":"task-finished","task_id":"asr-001"},"payload":{}}

任务失败发送 header.event: "task-failed"，并提供同一 task_id、header.error_code 和 header.error_message。断开连接不能代替正常结束事件。

8.2 实时流式 ASR（Base64 音频）

Endpoint 为 /api-ws/v1/realtime。URL 携带 ?model=<模型ID>。握手还包含 OpenAI-Beta: realtime=v1。

客户服务返回 session.created；QwenWork 发送配置并等待 session.updated：

{
  "event_id": "event-001", "type": "session.update",
  "session": {
    "modalities": ["text"], "input_audio_format": "pcm", "sample_rate": 16000,
    "turn_detection": {"type": "server_vad", "threshold": 0.5, "silence_duration_ms": 800}
  }
}

音频以 JSON 文本帧发送，audio 是 PCM 字节的 Base64：

{"event_id":"event-002","type":"input_audio_buffer.append","audio":"AAAAAA=="}

客户服务 用 conversation.item.input_audio_transcription.text 返回预览，用 conversation.item.input_audio_transcription.completed 的 transcript 返回最终文字；通过 item_id 对应同一条转写。QwenWork 最后发送 session.finish，客户服务 发送 session.finished 后结束会话。错误使用原生 error 事件。

最小服务端事件示例（每个 JSON 独立作为一条 WebSocket 文本消息）：

{"event_id":"server-001","type":"session.created","session":{"id":"session-001"}}

{"event_id":"server-002","type":"session.updated","session":{"id":"session-001"}}

{"event_id":"server-003","type":"conversation.item.input_audio_transcription.text","item_id":"item-001","text":"现在开始","stash":"会"}

{"event_id":"server-004","type":"conversation.item.input_audio_transcription.completed","item_id":"item-001","transcript":"现在开始会议。"}

QwenWork 的结束请求与服务端确认：

{"event_id":"event-003","type":"session.finish"}

{"event_id":"server-005","type":"session.finished","session":{"id":"session-001"}}

两种实时语音接口的错误格式见第 10.3 节。

9. QwenWork Search：网页与图片搜索

两类搜索均使用 POST / JSON、可选密钥，请求和响应结构分别如下。

9.1 网页搜索

基础请求如下。实际请求还可能包含下表中的扩展字段；空字符串、null 或空数组表示未指定条件，可忽略。

{
  "query": "Kubernetes 部署指南",
  "count": 5,
  "contents": {"mainText": false, "markdownText": true, "summary": false}
}

基础字段

可选扩展

扩展字段可能以空值随请求发送。非空筛选条件须执行；不支持或条件冲突时明确报错，不返回未筛选结果伪装成功。

成功响应：

{
  "requestId": "search-001",
  "pageItems": [{
    "title": "部署指南", "link": "https://docs.example/deployment",
    "snippet": "部署入门说明", "markdownText": "# 部署指南\n这是正文。"
  }]
}

pageItems 为有序数组；正文与摘要按 contents 返回。可选结果字段包括 mainText、summary、publishedTime、hostname、hostLogo。未知字段省略，空结果返回 {"pageItems":[]}。默认超时 3 秒。错误格式见第 10.4 节。

9.2 图片搜索

客户服务只收到搜索词：

{"query":"山间湖泊"}

成功响应：

{"imageItems":[{"title":"Mountain lake","imageUrl":"https://assets.example/lake.jpg","width":1024,"height":768}]}

imageUrl 指向可访问的图片文件，宽高可省略或为 null。无结果返回 {"imageItems":[]}。请求不发送 count。

成功时省略 errorCode/errorMsg，不返回 errorCode=0。默认超时 5 秒，响应体上限 4 MiB；错误格式见第 10.4 节。

10. 错误码与失败响应

通用要求

• 错误码用于程序识别，必须稳定、非空；错误消息必须非空且可读，不含密钥或堆栈。
• 请求未被接受时使用对应的非 2xx 状态；已接受的异步任务失败通过任务查询返回。
• 搜索业务错误允许 HTTP 200，但必须返回错误字段。其他接口不能仅在普通成功响应中附一段错误文字。
• 不用空结果、空产物或成功状态掩盖失败。

HTTP 状态与建议错误码

402 为固定业务码，表示配额不足；429 仅表示请求限流。 其余码名为建议值；已有稳定业务码可沿用，并随接口说明交付含义表。HTTP 语义与下述响应结构必须一致。429/503 可携带 Retry-After；返回该 Header 不代表调用方一定重试。生成提交超时或响应丢失可能已创建任务，不能据此重复生成。

配额不足：402

因配额不足而拒绝新请求时，返回 HTTP 402，并按接口结构携带业务码。配额恢复前，不应把此错误作为短暂限流进行重试。

SSE / WebSocket 已建立后，通过错误事件返回，不能改写握手或响应状态。异步任务查询和搜索业务错误可保持 HTTP 200，此时以对应字段中的 402 表达配额不足。

对话请求被拒绝（HTTP 402）：

{"error":{"code":"402","type":"insufficient_quota","message":"配额不足，请补充配额后重试。"}}

网页搜索业务失败（HTTP 200）：

{"requestId":"search-001","pageItems":[],"errorCode":402,"errorMsg":"配额不足，请补充配额后重试。"}

10.1 对话接口

非 2xx 响应的 error.code、error.type、error.message 为非空 string；error.param 可选：

{"error":{"code":"ModelNotFound","type":"invalid_request_error","param":"model","message":"Requested model was not found."}}

SSE 已开始后无法修改 HTTP 状态，应发送相同 error 对象并结束流，不再发送正常完成结果：

data: {"error":{"code":"InternalError","type":"server_error","message":"Generation failed."}}

10.2 图片、视频与音乐

提交或同步请求失败使用非 2xx。code、message 为非空 string，request_id 用于排查：

{"request_id":"req-error-001","code":"UnsupportedParameter","message":"Unsupported parameter value."}

已接受的异步任务执行失败，GET 查询返回 HTTP 200；task_id 保持一致，错误放在 output 内：

{"request_id":"req-query-002","output":{"task_id":"task-001","task_status":"FAILED","code":"GenerationFailed","message":"Unable to generate the requested media."}}

取消使用 CANCELED；任务状态无法确定或已过期可使用 UNKNOWN，不得返回 SUCCEEDED。查询请求本身失败时使用非 2xx 和顶层 code/message；不存在的任务也可明确返回 404 / TaskNotFound。

10.3 实时语音识别

握手前失败使用非 2xx。连接建立后，错误通过对应事件返回。

二进制音频接口：header.error_code、header.error_message 为非空 string，task_id 与请求一致。

{"header":{"event":"task-failed","task_id":"asr-001","error_code":"InvalidAudio","error_message":"Unsupported audio format."},"payload":{}}

Base64 音频接口：error.code、error.type、error.message 为非空 string。

{"event_id":"error-001","type":"error","error":{"code":"InvalidAudio","type":"invalid_request_error","message":"Unsupported audio format."}}

失败事件不能用正常结束事件代替。

10.4 网页与图片搜索

HTTP 200 的业务错误必须包含 integer 类型的 errorCode 和非空 string 类型的 errorMsg。建议使用与上表 HTTP 状态对应的数值，也可使用双方约定的非零整数业务码。

网页搜索失败：

{"requestId":"search-001","pageItems":[],"errorCode":503,"errorMsg":"Search service unavailable."}

图片搜索失败：

{"imageItems":[],"errorCode":400,"errorMsg":"Invalid search query."}

成功时省略 errorCode/errorMsg，不使用 errorCode: 0。真实空结果仍是成功，只返回空结果数组。HTTP 非 2xx 表示请求失败，可附 {"code":"ServiceUnavailable","message":"Search service unavailable."}。

11. 联调与交付要求

11.1 交付接口说明

每项能力提供一份接口登记信息：协议名称、模型 ID（搜索除外）、完整 Endpoint、鉴权方式，以及异步图片/视频的查询 Endpoint。图片必须明确写 Sync 或 Async；ASR 须明确 Endpoint 及音频编码（二进制或 Base64）。

同时说明实际支持的输入类型、图片数量/尺寸、视频模式/时长、素材访问方式、产物 URL 有效期、任务保留期、超时及并发限制。密钥单独交付，不放在协议示例或联调日志中。

11.2 最小协议验收用例

真实生成与协议解析分别验收：正确的 JSON 形状不等于图片、视频、音频可用。调用成功记录请求标识、HTTP 状态、任务状态与产物校验结果，避免保存密钥或用户原始内容。

11.3 常见问题