EdgeSpeak
中文
语言
English中文

语言与视觉

先选择兼容模型

调用前先通过模型发现与加载确认模型可用。所选模型的 supported_endpoints 必须包含目标接口路径。这些 API 会直接转发所选模型的协议，可选参数与响应细节可能随本机运行时或远端提供方变化。以下展示典型的非流式响应节选，实际返回的生成文本、Token 数或 ID 可能不同。

使用 Responses 生成

POST /v1/responses

传入 model 与 input，input 可以是字符串或支持的结构化输入项。生成文字位于 output[] 内 message 的 content 中，不是统一的顶层 text 字段。

请求示例：

Shell
curl --fail-with-body "$EDGESPEAK_BASE_URL/responses" \
  -H "Content-Type: application/json" \
  -d '{"model":"Qwen/Qwen3.5-4B","input":"Say hello in one short sentence.","max_output_tokens":128}'

输出示例：

JSON
{
  "id": "resp_example",
  "object": "response",
  "status": "completed",
  "model": "Qwen/Qwen3.5-4B",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "Hello!"
        }
      ]
    }
  ]
}

支持推理的模型可能在 message 前返回 reasoning 项，解析时应按类型读取，不要假定 output[0] 就是文字。

使用 Chat Completions 生成

POST /v1/chat/completions

传入 model 与包含角色、内容的 messages[]，适合自行管理聊天历史的客户端。

请求示例：

Shell
curl --fail-with-body "$EDGESPEAK_BASE_URL/chat/completions" \
  -H "Content-Type: application/json" \
  -d '{"model":"Qwen/Qwen3.5-4B","messages":[{"role":"user","content":"Say hello in one short sentence."}],"max_tokens":128}'

输出示例：

JSON
{
  "id": "chatcmpl_example",
  "object": "chat.completion",
  "model": "Qwen/Qwen3.5-4B",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello!"
      },
      "finish_reason": "stop"
    }
  ]
}

生成文字位于 choices[].message.content。如果模型调用了工具，响应中还会返回 tool_calls。

指定翻译语向

POST /v1/responses 与 POST /v1/chat/completions 接受可选的顶层 translation 对象，用于指定翻译方向与风格：

字段说明
target_language本轮译成的语言，BCP-47 写法，如 en、ja、zh-TW。
language_pair两个不同语言组成的数组，如 ["zh", "ja"]。原文属于其中一项时译成另一项，适合来回对译。
source_language原文语言提示。有 language_pair 时用来判断原文是哪一项；省略时按原文文字判断。
style翻译风格：natural、conversational 或 faithful。

目标语言的判定顺序：target_language 优先；其次按 language_pair 取原文之外的那一项，判断不出原文属于哪一项时译成第二项；两者都没有时，原文是中文（或 source_language 为中文）译成英语，否则译成中文。

  • 本机翻译模型：按上述规则组织翻译请求。
  • 通用对话模型与云端服务同样生效：语言对、目标语言与风格写进发给模型的口译提示词，Chat 追加在首条 system 消息末尾（没有就补一条），Responses 追加在 instructions 末尾。translation 字段本身不转发给云端服务。
  • 省略 translation 或传 null 时请求不做任何改动。
  • 写法不对（字段未知、类型不对、语言对两项相同、风格不在上述取值中）返回 400 translation_options_invalid；语言不受支持返回 400 translation_language_unsupported。
JSON
{
  "model": "Qwen/Qwen3.5-4B",
  "input": "我们下周一开会。",
  "translation": {
    "language_pair": ["zh", "ja"],
    "style": "conversational"
  }
}

上例把中文原文译成日语；原文是日语时则译成中文。MCP 的 edgespeak_create_response 与 Realtime 的 session.translation 使用同一种写法。

使用 Messages 生成

POST /v1/messages

适合兼容 Anthropic 协议的客户端。传入 model、messages 与 max_tokens。网关支持使用 x-api-key 鉴权，并会转发请求中显式传入的 anthropic-version 与 anthropic-beta。调用前请先在模型目录中确认模型支持该接口。

请求示例：

Shell
curl --fail-with-body "$EDGESPEAK_BASE_URL/messages" \
  -H "Content-Type: application/json" \
  -d '{"model":"Qwen/Qwen3.5-4B","max_tokens":128,"messages":[{"role":"user","content":"Say hello in one short sentence."}]}' \
  -H "anthropic-version: 2023-06-01"

输出示例：

JSON
{
  "id": "msg_example",
  "type": "message",
  "role": "assistant",
  "model": "Qwen/Qwen3.5-4B",
  "content": [
    {
      "type": "text",
      "text": "Hello!"
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 16,
    "output_tokens": 3
  }
}

从 content[] 中读取 text 块。此响应结构与 Responses 和 Chat Completions 均不相同。

文本分词

POST /v1/tokenize

此示例使用本机运行时的 content 输入。Token ID 取决于所选模型的 Tokenizer。远端提供方的分词格式可能不同，网关会转发其支持的格式。

请求示例：

Shell
curl --fail-with-body "$EDGESPEAK_BASE_URL/tokenize" \
  -H "Content-Type: application/json" \
  -d '{"model":"Qwen/Qwen3.5-4B","content":"Hello world."}'

输出示例：

JSON
{
  "tokens": [
    9707,
    1879,
    13
  ]
}

返回的数组内容仅为示意，请勿硬编码这些 ID。若仅返回数组，可以直接计算其长度获取 Token 数。纯文本分词不包含聊天模板可能额外插入的 Token。

读取语言模型流

为生成请求添加 stream: true 并使用 curl -N。按 SSE 事件边界解析，不要把单个网络 chunk 当成完整事件。下面用 Chat Completions 演示，其他接口使用各自对应的事件名。

请求示例：

Shell
curl --fail-with-body "$EDGESPEAK_BASE_URL/chat/completions" \
  -H "Content-Type: application/json" \
  -d '{"model":"Qwen/Qwen3.5-4B","messages":[{"role":"user","content":"Say hello."}],"stream":true,"max_tokens":128}' \
  -N

输出示例：

data: {"id":"chatcmpl_example","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Hello!"},"finish_reason":null}]}

data: {"id":"chatcmpl_example","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

以上为事件流节选。不同协议的事件命名不同：Responses 通常使用 response.output_text.delta 与 response.completed，Messages 使用 content_block_delta 与 message_stop。不要把 Chat Completions 的 [DONE] 解析逻辑套用到所有协议。流开始后的错误也可能表现为连接断开，需要根据各协议自身的标志确认是否结束。

发送图片或视频

调用前请先选择声明支持视觉的模型。下面的 Python 3 脚本将本地 JPEG 转成完整 JSON 请求，避免不同操作系统的 base64 命令行差异。请在 photo.jpg 所在目录下运行，脚本会生成 vision-request.json。

请求示例：

Shell
python3 - <<'PYIMAGE'
import base64, json
from pathlib import Path
data = base64.b64encode(Path("photo.jpg").read_bytes()).decode("ascii")
body = {"model": "Qwen/Qwen3.5-4B", "messages": [{"role": "user", "content": [
    {"type": "text", "text": "Describe this image."},
    {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64," + data}}
]}], "max_tokens": 256}
Path("vision-request.json").write_text(json.dumps(body), encoding="utf-8")
PYIMAGE
curl --fail-with-body "$EDGESPEAK_BASE_URL/chat/completions" \
  -H "Content-Type: application/json" -d @vision-request.json

输出示例：

JSON
{
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "A mountain lake under a clear sky."
      },
      "finish_reason": "stop"
    }
  ]
}

输出内容为响应节选，具体描述取决于输入图片。Chat Completions 支持直接传入原生视频，格式为 {"type":"input_video","input_video":{"data":"视频字节的 base64"}}。具体要求参阅视频前置条件、采样与大小限制与上下文窗口配置。Realtime 接口不接受原生视频。

继续阅读：Realtime 实时会话 · API 索引

本页目录