tencent cloud

混元调用指南

Download
聚焦模式
字号
最后更新时间: 2026-07-28 17:54:29

概述

腾讯混元大模型(Tencent Hy)是由腾讯研发的大语言模型,具备强大的中文创作能力,复杂语境下的逻辑推理能力,以及可靠的任务执行能力。

前提条件

已注册腾讯云账号并开通 TokenHub 服务。
已在 TokenHub 控制台 获取 API Key。

Hy3 调用示例

hy3 兼容 OpenAI Chat Completions API 、OpenAI Responses 、Anthropic Messages API 协议。通用接口规范与所有语言模型一致,请参见 语言模型调用概览API 使用说明
以下为 OpenAI Chat Completions API 调用示例。
model(调用参数)
能力说明
上下文窗口
最大输入
最大输出
hy3
Hy3 基于真实业务场景打磨,兼具效果和性价比,强化 Coding、长文、推理和 Agent 等能力。
256k
192k
128k
说明:
所有示例统一使用 Authorization: Bearer YOUR_API_KEY 鉴权,请将 YOUR_API_KEY 替换为您在 TokenHub 控制台 创建的 API Key。
Python / Node.js 直接使用 OpenAI 官方 SDK;Java / Go 使用标准 HTTP 客户端调用 OpenAI 兼容接口。

基础对话

最简单的单轮对话请求,演示基本的请求和响应结构。
cURL
Python
Java
Node.js
Go

curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/chat/completions' \\
-H 'Content-Type: application/json' \\
-H 'Authorization: Bearer YOUR_API_KEY' \\
-d '{
"model": "hy3",
"messages": [
{"role": "user", "content": "你好,请简单介绍一下你自己。"}
],
"stream": false,
"temperature": 0.9
}'
from openai import OpenAI

client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://tokenhub-intl.tencentcloudmaas.com/v1",
)

response = client.chat.completions.create(
model="hy3",
messages=[
{"role": "user", "content": "你好,请简单介绍一下你自己。"},
],
temperature=0.9,
)
print(response.choices[0].message.content)
import okhttp3.*;
import com.google.gson.Gson;
import java.util.*;

public class BasicChat {
public static void main(String[] args) throws Exception {
Map<String, Object> body = new HashMap<>();
body.put("model", "hy3");
body.put("messages", List.of(
Map.of("role", "user", "content", "你好,请简单介绍一下你自己。")
));
body.put("temperature", 0.9);

Request request = new Request.Builder()
.url("https://tokenhub-intl.tencentcloudmaas.com/v1/chat/completions")
.header("Authorization", "Bearer YOUR_API_KEY")
.post(RequestBody.create(new Gson().toJson(body),
MediaType.parse("application/json")))
.build();

try (Response response = new OkHttpClient().newCall(request).execute()) {
System.out.println(response.body().string());
}
}
}
import OpenAI from 'openai';

const client = new OpenAI({
apiKey: 'YOUR_API_KEY',
baseURL: 'https://tokenhub-intl.tencentcloudmaas.com/v1',
});

const response = await client.chat.completions.create({
model: 'hy3',
messages: [
{ role: 'user', content: '你好,请简单介绍一下你自己。' },
],
temperature: 0.9,
});
console.log(response.choices[0].message.content);
package main

import (
"bytes"
"encoding/json"
"fmt"
"io"
"net/http"
)

func main() {
body, _ := json.Marshal(map[string]interface{}{
"model": "hy3",
"messages": []map[string]string{
{"role": "user", "content": "你好,请简单介绍一下你自己。"},
},
"temperature": 0.9,
})

req, _ := http.NewRequest("POST",
"https://tokenhub-intl.tencentcloudmaas.com/v1/chat/completions",
bytes.NewBuffer(body))
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
data, _ := io.ReadAll(resp.Body)
fmt.Println(string(data))
}
响应示例:
{
"id": "REPLACED_ID",
"object": "chat.completion",
"model": "hy3",
"created": 1775146513,
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "你好!我是混元,是由腾讯开发的大模型。我的主要功能是基础信息处理与逻辑响应,比如回答各种问题、解决问题、学习新知识、创造内容,还能陪你闲聊呢。如果你有任何问题都可以随时问我哦。"
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 22,
"completion_tokens": 50,
"total_tokens": 72,
"prompt_tokens_details": {"cached_tokens": 0},
"completion_tokens_details": {"reasoning_tokens": 0}
}
}

流式请求

设置 stream: true 即可启用流式输出,响应以 SSE(Server-Sent Events)格式按 token 增量返回。如需在最后一个 chunk 拿到完整 usage 统计,请加 stream_options: { "include_usage": true }
cURL
Python
Java
Node.js
Go
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/chat/completions' \\
-H 'Content-Type: application/json' \\
-H 'Authorization: Bearer YOUR_API_KEY' \\
-d '{
"model": "hy3",
"messages": [
{"role": "user", "content": "你好"}
],
"stream": true,
"stream_options": {"include_usage": true}
}'
from openai import OpenAI

client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://tokenhub-intl.tencentcloudmaas.com/v1",
)

stream = client.chat.completions.create(
model="hy3",
messages=[{"role": "user", "content": "你好"}],
stream=True,
stream_options={"include_usage": True},
)
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)
if chunk.usage:
print("\\nusage:", chunk.usage)
import okhttp3.*;
import okhttp3.sse.*;
import com.google.gson.Gson;
import java.util.*;

public class StreamingChat {
public static void main(String[] args) {
Map<String, Object> body = new HashMap<>();
body.put("model", "hy3");
body.put("messages", List.of(Map.of("role", "user", "content", "你好")));
body.put("stream", true);
body.put("stream_options", Map.of("include_usage", true));

Request request = new Request.Builder()
.url("https://tokenhub-intl.tencentcloudmaas.com/v1/chat/completions")
.header("Authorization", "Bearer YOUR_API_KEY")
.post(RequestBody.create(new Gson().toJson(body),
MediaType.parse("application/json")))
.build();

EventSources.createFactory(new OkHttpClient()).newEventSource(request,
new EventSourceListener() {
@Override public void onEvent(EventSource es, String id, String type, String data) {
if (!"[DONE]".equals(data)) System.out.println(data);
}
});
}
}
import OpenAI from 'openai';

const client = new OpenAI({
apiKey: 'YOUR_API_KEY',
baseURL: 'https://tokenhub-intl.tencentcloudmaas.com/v1',
});

const stream = await client.chat.completions.create({
model: 'hy3',
messages: [{ role: 'user', content: '你好' }],
stream: true,
stream_options: { include_usage: true },
});

for await (const chunk of stream) {
process.stdout.write(chunk.choices[0]?.delta?.content || '');
if (chunk.usage) console.log('\\nusage:', chunk.usage);
}
package main

import (
"bufio"
"bytes"
"encoding/json"
"fmt"
"net/http"
"strings"
)

func main() {
body, _ := json.Marshal(map[string]interface{}{
"model": "hy3",
"messages": []map[string]string{
{"role": "user", "content": "你好"},
},
"stream": true,
"stream_options": map[string]bool{"include_usage": true},
})

req, _ := http.NewRequest("POST",
"https://tokenhub-intl.tencentcloudmaas.com/v1/chat/completions",
bytes.NewBuffer(body))
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

scanner := bufio.NewScanner(resp.Body)
for scanner.Scan() {
line := scanner.Text()
if strings.HasPrefix(line, "data: ") && line != "data: [DONE]" {
fmt.Println(strings.TrimPrefix(line, "data: "))
}
}
}
响应示例(SSE 片段):
data: {"id": "REPLACED_ID", "object": "chat.completion.chunk", "created": 1779958293, "model": "hy3", "choices": [{"index": 0, "delta": {"role": "assistant"}}]}

data: {"id": "REPLACED_ID", "object": "chat.completion.chunk", "created": 1779958293, "model": "hy3", "choices": [{"index": 0, "delta": {"content": "你好"}}]}

data: {"id": "REPLACED_ID", "object": "chat.completion.chunk", "created": 1779958293, "model": "hy3", "choices": [{"index": 0, "delta": {"content": "帮你的吗"}}]}

data: {"id": "REPLACED_ID", "object": "chat.completion.chunk", "created": 1779958293, "model": "hy3", "choices": [{"index": 0, "delta": {"content": " 😊"}, "finish_reason": "stop"}]}

data: {"id": "REPLACED_ID", "object": "chat.completion.chunk", "created": 1779958293, "model": "hy3", "choices": [], "usage": {"prompt_tokens": 16, "completion_tokens": 11, "total_tokens": 27, "prompt_tokens_details": {"cached_tokens": 0}, "completion_tokens_details": {"reasoning_tokens": 0}}}

data: [DONE]

深度思考

开启深度思考,详细说明请参见 深度思考
cURL
Python
Node.js
Java
Go
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/chat/completions' \\
-H 'Content-Type: application/json' \\
-H 'Authorization: Bearer YOUR_API_KEY' \\
-d '{
"model": "hy3",
"messages": [
{"role": "user", "content": "小明有5个苹果,给了小红2个,又买了3个,最后还剩几个?"}
],
"thinking": {"type": "enabled"},
"stream": false
}'
from openai import OpenAI

client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://tokenhub-intl.tencentcloudmaas.com/v1",
)

response = client.chat.completions.create(
model="hy3",
messages=[
{"role": "user", "content": "小明有5个苹果,给了小红2个,又买了3个,最后还剩几个?"},
],
extra_body={"thinking": {"type": "enabled"}},
)

# OpenAI SDK 不直接声明 reasoning_content 字段,需用 getattr 访问
msg = response.choices[0].message
if hasattr(msg, "reasoning_content"):
print("思考过程:", getattr(msg, "reasoning_content"))
print("最终回答:", msg.content)
import OpenAI from 'openai';

const client = new OpenAI({
apiKey: 'YOUR_API_KEY',
baseURL: 'https://tokenhub-intl.tencentcloudmaas.com/v1',
});

// Node.js SDK:thinking 字段直接展开到顶层
const response = await client.chat.completions.create({
model: 'hy3',
messages: [
{ role: 'user', content: '小明有5个苹果,给了小红2个,又买了3个,最后还剩几个?' },
],
thinking: { type: 'enabled' },
});

const msg = response.choices[0].message;
if (msg.reasoning_content) console.log('思考过程:', msg.reasoning_content);
console.log('最终回答:', msg.content);
import okhttp3.*;
import com.google.gson.Gson;
import java.util.*;

public class ThinkingChat {
public static void main(String[] args) throws Exception {
Map<String, Object> body = new HashMap<>();
body.put("model", "hy3");
body.put("messages", List.of(
Map.of("role", "user", "content", "小明有5个苹果,给了小红2个,又买了3个,最后还剩几个?")
));
body.put("thinking", Map.of("type", "enabled"));

Request request = new Request.Builder()
.url("https://tokenhub-intl.tencentcloudmaas.com/v1/chat/completions")
.header("Authorization", "Bearer YOUR_API_KEY")
.post(RequestBody.create(new Gson().toJson(body), MediaType.parse("application/json")))
.build();

try (Response response = new OkHttpClient().newCall(request).execute()) {
// 响应体中 message.reasoning_content 为思考过程,message.content 为最终回答
System.out.println(response.body().string());
}
}
}
package main

import (
"bytes"
"encoding/json"
"fmt"
"io"
"net/http"
)

func main() {
body, _ := json.Marshal(map[string]interface{}{
"model": "hy3",
"messages": []map[string]string{
{"role": "user", "content": "小明有5个苹果,给了小红2个,又买了3个,最后还剩几个?"},
},
"thinking": map[string]string{"type": "enabled"},
})

req, _ := http.NewRequest("POST",
"https://tokenhub-intl.tencentcloudmaas.com/v1/chat/completions",
bytes.NewBuffer(body))
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

data, _ := io.ReadAll(resp.Body)
// 响应体中 message.reasoning_content 为思考过程,message.content 为最终回答
fmt.Println(string(data))
}
响应示例:
启用思考后,响应中会附带 reasoning_content 思考过程字段。
{
"id": "REPLACED_ID",
"object": "chat.completion",
"created": 1775146546,
"model": "hy3",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "小明最初有5个苹果,给了小红2个后剩下3个,又买了3个,所以最后剩下 **6个** 苹果。",
"reasoning_content": "我们被问到:\\"小明有5个苹果,给了小红2个,又买了3个,最后还剩几个?\\" 这是一个简单的算术问题。让我们一步步来:\\n\\n1. 小明一开始有5个苹果。\\n2. 他给了小红2个,所以剩下:5 - 2 = 3个苹果。\\n3. 然后他又买了3个苹果,所以现在有:3 + 3 = 6个苹果。\\n\\n所以最后还剩6个苹果。\\n\\n答案:6。"
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 31,
"completion_tokens": 132,
"total_tokens": 163
}
}
推理深度配置
hy3hy3-preview 默认为 low。详细说明请参见 深度思考
注意:
Hy3正式版在 toolcall 场景下,模型已具备 adaptive thinking 能力,即可以根据任务复杂度,自主决定推理深度。当请求携带 tools 时,出于兼容考虑,此场景下若设置 reasoning_effort low,API 会自动将 low 映射为 high
cURL
Python
Node.js
Java
Go
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/chat/completions' \\
-H 'Content-Type: application/json' \\
-H 'Authorization: Bearer YOUR_API_KEY' \\
-d '{
"model": "hy3",
"messages": [
{"role": "user", "content": "小明有5个苹果,给了小红2个,又买了3个,最后还剩几个?"}
],
"stream": false,
"temperature": 0.9,
"reasoning_effort": "high"
}'
from openai import OpenAI

client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://tokenhub-intl.tencentcloudmaas.com/v1",
)

response = client.chat.completions.create(
model="hy3",
messages=[
{"role": "user", "content": "小明有5个苹果,给了小红2个,又买了3个,最后还剩几个?"},
],
temperature=0.9,
extra_body={"reasoning_effort": "high"},
)

msg = response.choices[0].message
if hasattr(msg, "reasoning_content"):
print("思考过程:", getattr(msg, "reasoning_content"))
print("最终回答:", msg.content)
import OpenAI from 'openai';

const client = new OpenAI({
apiKey: 'YOUR_API_KEY',
baseURL: 'https://tokenhub-intl.tencentcloudmaas.com/v1',
});

const response = await client.chat.completions.create({
model: 'hy3',
messages: [
{ role: 'user', content: '小明有5个苹果,给了小红2个,又买了3个,最后还剩几个?' },
],
temperature: 0.9,
reasoning_effort: 'high',
});

const msg = response.choices[0].message;
if (msg.reasoning_content) console.log('思考过程:', msg.reasoning_content);
console.log('最终回答:', msg.content);
import okhttp3.*;
import com.google.gson.Gson;
import java.util.*;

public class ReasoningEffortChat {
public static void main(String[] args) throws Exception {
Map<String, Object> body = new HashMap<>();
body.put("model", "hy3");
body.put("messages", List.of(
Map.of("role", "user", "content", "小明有5个苹果,给了小红2个,又买了3个,最后还剩几个?")
));
body.put("temperature", 0.9);
body.put("reasoning_effort", "high");

Request request = new Request.Builder()
.url("https://tokenhub-intl.tencentcloudmaas.com/v1/chat/completions")
.header("Authorization", "Bearer YOUR_API_KEY")
.post(RequestBody.create(new Gson().toJson(body), MediaType.parse("application/json")))
.build();

try (Response response = new OkHttpClient().newCall(request).execute()) {
System.out.println(response.body().string());
}
}
}
package main

import (
"bytes"
"encoding/json"
"fmt"
"io"
"net/http"
)

func main() {
body, _ := json.Marshal(map[string]interface{}{
"model": "hy3",
"messages": []map[string]string{
{"role": "user", "content": "小明有5个苹果,给了小红2个,又买了3个,最后还剩几个?"},
},
"temperature": 0.9,
"reasoning_effort": "high",
})

req, _ := http.NewRequest("POST",
"https://tokenhub-intl.tencentcloudmaas.com/v1/chat/completions",
bytes.NewBuffer(body))
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

data, _ := io.ReadAll(resp.Body)
fmt.Println(string(data))
}
响应示例:
启用思考后,响应中会附带 reasoning_content 思考过程字段。
{
"id": "c95dc87ecce440678c3bb08f5868fee6",
"object": "chat.completion",
"created": 1775146546,
"model": "hy3",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "小明原本有5个苹果,给了小红2个后剩下: \\n5 - 2 = 3(个) \\n然后又买了3个,现在共有: \\n3 + 3 = 6(个) \\n\\n所以最后还剩 **6个** 苹果。",
"reasoning_content": "我们被问到:\\"小明有5个苹果,给了小红2个,又买了3个,最后还剩几个?\\" 我们需要逐步计算。\\n\\n初始:5个苹果。\\n给了小红2个:5 - 2 = 3个苹果。\\n又买了3个:3 + 3 = 6个苹果。\\n所以最后还剩6个苹果。\\n\\n答案:6。"
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 3,
"completion_tokens": 136,
"total_tokens": 167
}
}

交错式思考(深度思考 + 工具调用)

本示例仅用于说明完整流程与字段回传逻辑;实际使用时,请根据业务部署环境和业务字段调整具体值(此案例仅用于理解流程,不代表模型能力边界)。详细说明请参见 交错式思考模式(Interleaved Thinking)
第 1 轮 - 用户提问:
请求:
cURL
Python
Node.js
Java
Go
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/chat/completions' \\
-H 'Content-Type: application/json' \\
-H 'Authorization: Bearer YOUR_API_KEY' \\
-d '{
"model": "hy3",
"messages": [
{ "role": "system", "content": "你是一个 Agent,必须按步骤推理并调用工具完成任务。" },
{ "role": "user", "content": "深圳今天天气怎么样?" }
],
"stream": false,
"tool_choice": "auto",
"reasoning_effort": "high",
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "获取某地天气信息,输入 location。",
"parameters": {
"type": "object",
"properties": { "location": { "type": "string" } },
"required": ["location"]
}
}
}
]
}'
from openai import OpenAI

client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://tokenhub-intl.tencentcloudmaas.com/v1",
)

tools = [{
"type": "function",
"function": {
"name": "get_weather",
"description": "获取某地天气信息,输入 location。",
"parameters": {
"type": "object",
"properties": {"location": {"type": "string"}},
"required": ["location"],
},
},
}]

messages = [
{"role": "system", "content": "你是一个 Agent,必须按步骤推理并调用工具完成任务。"},
{"role": "user", "content": "深圳今天天气怎么样?"},
]

# OpenAI Python SDK 类型签名严格,非标字段(如 reasoning_effort)需通过 extra_body 透传
resp1 = client.chat.completions.create(
model="hy3",
messages=messages,
tools=tools,
tool_choice="auto",
extra_body={"reasoning_effort": "high"},
)
msg1 = resp1.choices[0].message
print("第 1 轮 assistant.reasoning_content:", getattr(msg1, "reasoning_content", ""))
print("第 1 轮 tool_calls:", msg1.tool_calls)
import OpenAI from 'openai';

const client = new OpenAI({
apiKey: 'YOUR_API_KEY',
baseURL: 'https://tokenhub-intl.tencentcloudmaas.com/v1',
});

const tools = [{
type: 'function',
function: {
name: 'get_weather',
description: '获取某地天气信息,输入 location。',
parameters: {
type: 'object',
properties: { location: { type: 'string' } },
required: ['location'],
},
},
}];

const messages = [
{ role: 'system', content: '你是一个 Agent,必须按步骤推理并调用工具完成任务。' },
{ role: 'user', content: '深圳今天天气怎么样?' },
];

const resp1 = await client.chat.completions.create({
model: 'hy3',
messages,
tools,
tool_choice: 'auto',
reasoning_effort: 'high',
});

const msg1 = resp1.choices[0].message;
console.log('第 1 轮 reasoning_content:', msg1.reasoning_content);
console.log('第 1 轮 tool_calls:', msg1.tool_calls);
import okhttp3.*;
import com.google.gson.*;
import java.util.*;

public class InterleavedThinking {
static final String URL = "https://tokenhub-intl.tencentcloudmaas.com/v1/chat/completions";
static final String API_KEY = "YOUR_API_KEY";
static final OkHttpClient HTTP = new OkHttpClient();
static final Gson GSON = new Gson();

/** 通用 chat 调用,返回原始 JSON 响应字符串。 */
static String chat(List<Map<String, Object>> messages, List<Map<String, Object>> tools) throws Exception {
Map<String, Object> body = new HashMap<>();
body.put("model", "hy3");
body.put("messages", messages);
body.put("tools", tools);
body.put("tool_choice", "auto");
body.put("reasoning_effort", "high");
body.put("stream", false);

Request req = new Request.Builder()
.url(URL)
.header("Authorization", "Bearer " + API_KEY)
.post(RequestBody.create(GSON.toJson(body), MediaType.parse("application/json")))
.build();
try (Response resp = HTTP.newCall(req).execute()) {
return resp.body().string();
}
}

public static void main(String[] args) throws Exception {
List<Map<String, Object>> tools = List.of(Map.of(
"type", "function",
"function", Map.of(
"name", "get_weather",
"description", "获取某地天气信息,输入 location。",
"parameters", Map.of(
"type", "object",
"properties", Map.of("location", Map.of("type", "string")),
"required", List.of("location")
)
)
));

List<Map<String, Object>> messages = new ArrayList<>();
messages.add(Map.of("role", "system", "content", "你是一个 Agent,必须按步骤推理并调用工具完成任务。"));
messages.add(Map.of("role", "user", "content", "深圳今天天气怎么样?"));

// 第 1 轮:模型决定是否调用工具
String r1 = chat(messages, tools);
System.out.println("第 1 轮响应:" + r1);
// 接下来按响应里的 reasoning_content / tool_calls 回填到 messages,参见第 2 步
}
}
package main

import (
"bytes"
"encoding/json"
"fmt"
"io"
"net/http"
)

const (
URL = "https://tokenhub-intl.tencentcloudmaas.com/v1/chat/completions"
APIKEY = "YOUR_API_KEY"
)

// 通用 chat 调用
func chat(messages []map[string]interface{}, tools []map[string]interface{}) (map[string]interface{}, error) {
body, _ := json.Marshal(map[string]interface{}{
"model": "hy3",
"messages": messages,
"tools": tools,
"tool_choice": "auto",
"reasoning_effort": "high",
"stream": false,
})
req, _ := http.NewRequest("POST", URL, bytes.NewBuffer(body))
req.Header.Set("Authorization", "Bearer "+APIKEY)
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
return nil, err
}
defer resp.Body.Close()
data, _ := io.ReadAll(resp.Body)
var out map[string]interface{}
json.Unmarshal(data, &out)
return out, nil
}

func main() {
tools := []map[string]interface{}{{
"type": "function",
"function": map[string]interface{}{
"name": "get_weather",
"description": "获取某地天气信息,输入 location。",
"parameters": map[string]interface{}{
"type": "object",
"properties": map[string]interface{}{
"location": map[string]string{"type": "string"},
},
"required": []string{"location"},
},
},
}}

messages := []map[string]interface{}{
{"role": "system", "content": "你是一个 Agent,必须按步骤推理并调用工具完成任务。"},
{"role": "user", "content": "深圳今天天气怎么样?"},
}

// 第 1 轮:模型决定是否调用工具
r1, _ := chat(messages, tools)
fmt.Printf("第 1 轮响应: %+v\\n", r1)
// 接下来按响应里的 reasoning_content / tool_calls 回填到 messages,参见第 2 步
}
响应:
{
"id": "31be91fe574e41e49616352366b4fa1b",
"object": "chat.completion",
"created": 1776057110,
"model": "hy3",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "我来帮你查询深圳今天的天气情况。",
"reasoning_content": "用户问的是\\"深圳今天天气怎么样?\\",这是一个简单的天气查询请求。我需要使用get_weather函数来获取深圳的天气信息。根据函数描述,这个函数需要一个location参数,用户已经明确提供了\\"深圳\\"作为地点。所以,我应该直接调用get_weather函数,参数location设为\\"深圳\\"。不需要额外的推理步骤,因为用户的问题很直接。现在,我准备调用函数。",
"tool_calls": [
{
"id": "chatcmpl-tool-b39c6375f812783a",
"type": "function",
"function": {
"name": "get_weather",
"arguments": "{\\"location\\": \\"深圳\\"}"
}
}
]
},
"finish_reason": "tool_calls"
}
],
"usage": {
"prompt_tokens": 209,
"completion_tokens": 111,
"total_tokens": 320
}
}
第 2 轮 - 回填工具结果(在同一轮中延续思维链):
假设工具执行返回的结果为:Cloudy,气温 7~13°C。您需要在请求中,回填工具执行结果,同时保留首次请求中响应体里获取的 reasoning_content
请求:
cURL
Python
Node.js
Java
Go
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/chat/completions' \\
-H 'Content-Type: application/json' \\
-H 'Authorization: Bearer YOUR_API_KEY' \\
-d '{
"model": "hy3",
"messages": [
{ "role": "system", "content": "你是一个 Agent,必须按步骤推理并调用工具完成任务。" },
{ "role": "user", "content": "深圳今天天气怎么样?" },
{
"role": "assistant",
"content": "我来帮你查询深圳今天的天气情况。",
"reasoning_content": "用户问的是\\"深圳今天天气怎么样?\\"...",
"tool_calls": [
{
"id": "chatcmpl-tool-b39c6375f812783a",
"type": "function",
"function": {
"name": "get_weather",
"arguments": "{\\"location\\": \\"深圳\\"}"
}
}
]
},
{
"role": "tool",
"tool_call_id": "chatcmpl-tool-b39c6375f812783a",
"content": "Cloudy,气温 7~13°C"
}
],
"stream": false,
"tool_choice": "auto",
"reasoning_effort": "high",
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "获取某地天气信息,输入 location。",
"parameters": {
"type": "object",
"properties": { "location": { "type": "string" } },
"required": ["location"]
}
}
}
]
}'
# 接续上一步:把第 1 轮的 assistant 消息(含 reasoning_content + tool_calls)
# 与工具结果一起回填到 messages
import json

# 第 1 轮 assistant 消息的回写:reasoning_content 必须保留
assistant_msg = {
"role": "assistant",
"content": msg1.content,
"reasoning_content": getattr(msg1, "reasoning_content", ""),
"tool_calls": [
{
"id": tc.id,
"type": tc.type,
"function": {
"name": tc.function.name,
"arguments": tc.function.arguments,
},
} for tc in (msg1.tool_calls or [])
],
}
messages.append(assistant_msg)

# 业务侧执行工具,把结果以 role=tool 回填
for tc in (msg1.tool_calls or []):
args = json.loads(tc.function.arguments)
# 这里替换为真实业务逻辑
tool_result = "Cloudy,气温 7~13°C"
messages.append({
"role": "tool",
"tool_call_id": tc.id,
"content": tool_result,
})

# 第 2 轮:把工具结果送回模型,模型继续思考并输出最终回答
resp2 = client.chat.completions.create(
model="hy3",
messages=messages,
tools=tools,
tool_choice="auto",
extra_body={"reasoning_effort": "high"},
)
print("最终回答:", resp2.choices[0].message.content)
// 接续上一步:把第 1 轮的 assistant 消息(含 reasoning_content + tool_calls)
// 与工具结果一起回填到 messages

const assistantMsg = {
role: 'assistant',
content: msg1.content,
reasoning_content: msg1.reasoning_content,
tool_calls: msg1.tool_calls,
};
messages.push(assistantMsg);

for (const tc of msg1.tool_calls || []) {
const args = JSON.parse(tc.function.arguments);
// 这里替换为真实业务逻辑
const toolResult = 'Cloudy,气温 7~13°C';
messages.push({
role: 'tool',
tool_call_id: tc.id,
content: toolResult,
});
}

const resp2 = await client.chat.completions.create({
model: 'hy3',
messages,
tools,
tool_choice: 'auto',
reasoning_effort: 'high',
});
console.log('最终回答:', resp2.choices[0].message.content);
// 接续 main():把第 1 轮 assistant 消息和工具结果回填,再发起第 2 轮请求
// 完整流程示意(仅展示消息构造,HTTP 调用复用上一步的 chat() 函数)

// 1. 解析第 1 轮响应
JsonObject r1Obj = JsonParser.parseString(r1).getAsJsonObject();
JsonObject msg1 = r1Obj.getAsJsonArray("choices").get(0).getAsJsonObject()
.getAsJsonObject("message");

// 2. 把 assistant 消息(含 reasoning_content)整体回写到 messages
Map<String, Object> assistantEntry = new LinkedHashMap<>();
assistantEntry.put("role", "assistant");
assistantEntry.put("content", msg1.has("content") ? msg1.get("content").getAsString() : "");
if (msg1.has("reasoning_content")) {
assistantEntry.put("reasoning_content", msg1.get("reasoning_content").getAsString());
}
if (msg1.has("tool_calls")) {
assistantEntry.put("tool_calls", GSON.fromJson(msg1.get("tool_calls"), List.class));
}
messages.add(assistantEntry);

// 3. 业务侧执行工具,把工具结果以 role=tool 回填
for (JsonElement el : msg1.getAsJsonArray("tool_calls")) {
JsonObject call = el.getAsJsonObject();
String toolResult = "Cloudy,气温 7~13°C"; // 这里替换为真实业务逻辑
messages.add(Map.of(
"role", "tool",
"tool_call_id", call.get("id").getAsString(),
"content", toolResult
));
}

// 4. 第 2 轮:把工具结果送回模型
String r2 = chat(messages, tools);
System.out.println("第 2 轮响应:" + r2);
// 接续 main():把第 1 轮 assistant 消息和工具结果回填,再发起第 2 轮请求
// 完整流程示意(仅展示消息构造,HTTP 调用复用上一步的 chat() 函数)

// 1. 从第 1 轮响应中取出 assistant 消息
msg1Wrap := r1["choices"].([]interface{})[0].(map[string]interface{})
msg1 := msg1Wrap["message"].(map[string]interface{})

// 2. 把 assistant 消息(含 reasoning_content)整体回写到 messages
messages = append(messages, msg1)

// 3. 业务侧执行工具,把工具结果以 role=tool 回填
toolCalls, _ := msg1["tool_calls"].([]interface{})
for _, c := range toolCalls {
call := c.(map[string]interface{})
toolResult := "Cloudy,气温 7~13°C" // 这里替换为真实业务逻辑
messages = append(messages, map[string]interface{}{
"role": "tool",
"tool_call_id": call["id"],
"content": toolResult,
})
}

// 4. 第 2 轮:把工具结果送回模型
r2, _ := chat(messages, tools)
fmt.Printf("第 2 轮响应: %+v\\n", r2)
响应:
之后,模型会根据实际推理结果继续输出(可能继续 tool_calls,也可能输出最终答案),在获得最终答案前,每次调用都需遵循上述流程,通过“保留 reasoning_content + 回填 tool 输出”以维持大模型的思维链。
{
"id": "ae8941415e154a3c9749f0cf897469a4",
"object": "chat.completion",
"created": 1776057913,
"model": "hy3",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "根据查询结果,深圳今天的天气是**多云**,气温在 **7°C 到 13°C** 之间。今天天气比较凉爽,建议适当增添衣物,注意保暖哦!🧥",
"reasoning_content": "用户询问深圳今天的天气,我已经调用了get_weather工具获取了深圳的天气信息。结果显示是\\"Cloudy,气温 7~13°C\\"。\\n\\n现在我需要用中文回复用户,告诉他深圳今天的天气情况。天气是多云(Cloudy),气温在7到13摄氏度之间。\\n\\n我应该简洁明了地回复用户。"
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 340,
"completion_tokens": 114,
"total_tokens": 454
}
}

多轮对话

通过 messages 数组传递系统提示与历史对话,模型按顺序理解上下文并续接回复。消息顺序需为 system(可选)→ user → assistant → user → ...,且必须以 user 结尾。
cURL
Python
Java
Node.js
Go
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/chat/completions' \\
-H 'Content-Type: application/json' \\
-H 'Authorization: Bearer YOUR_API_KEY' \\
-d '{
"model": "hy3",
"messages": [
{"role": "system", "content": "你是一个专业的 AI 编程助手。"},
{"role": "user", "content": "Python 中如何读取 JSON 文件?"},
{"role": "assistant", "content": "可以使用内置的 json 模块:import json; with open(\\"data.json\\") as f: data = json.load(f)"},
{"role": "user", "content": "如果 JSON 文件很大怎么办?"}
]
}'
from openai import OpenAI

client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://tokenhub-intl.tencentcloudmaas.com/v1",
)

response = client.chat.completions.create(
model="hy3",
messages=[
{"role": "system", "content": "你是一个专业的 AI 编程助手。"},
{"role": "user", "content": "Python 中如何读取 JSON 文件?"},
{"role": "assistant", "content": "可以使用内置的 json 模块:import json; with open('data.json') as f: data = json.load(f)"},
{"role": "user", "content": "如果 JSON 文件很大怎么办?"},
],
)
print(response.choices[0].message.content)
import okhttp3.*;
import com.google.gson.Gson;
import java.util.*;

public class MultiTurn {
public static void main(String[] args) throws Exception {
Map<String, Object> body = new HashMap<>();
body.put("model", "hy3");
body.put("messages", List.of(
Map.of("role", "system", "content", "你是一个专业的 AI 编程助手。"),
Map.of("role", "user", "content", "Python 中如何读取 JSON 文件?"),
Map.of("role", "assistant", "content", "可以使用内置的 json 模块:import json; with open(\\"data.json\\") as f: data = json.load(f)"),
Map.of("role", "user", "content", "如果 JSON 文件很大怎么办?")
));

Request request = new Request.Builder()
.url("https://tokenhub-intl.tencentcloudmaas.com/v1/chat/completions")
.header("Authorization", "Bearer YOUR_API_KEY")
.post(RequestBody.create(new Gson().toJson(body),
MediaType.parse("application/json")))
.build();

try (Response response = new OkHttpClient().newCall(request).execute()) {
System.out.println(response.body().string());
}
}
}
import OpenAI from 'openai';

const client = new OpenAI({
apiKey: 'YOUR_API_KEY',
baseURL: 'https://tokenhub-intl.tencentcloudmaas.com/v1',
});

const response = await client.chat.completions.create({
model: 'hy3',
messages: [
{ role: 'system', content: '你是一个专业的 AI 编程助手。' },
{ role: 'user', content: 'Python 中如何读取 JSON 文件?' },
{ role: 'assistant', content: '可以使用内置的 json 模块:import json; with open("data.json") as f: data = json.load(f)' },
{ role: 'user', content: '如果 JSON 文件很大怎么办?' },
],
});
console.log(response.choices[0].message.content);
package main

import (
"bytes"
"encoding/json"
"fmt"
"io"
"net/http"
)

func main() {
body, _ := json.Marshal(map[string]interface{}{
"model": "hy3",
"messages": []map[string]string{
{"role": "system", "content": "你是一个专业的 AI 编程助手。"},
{"role": "user", "content": "Python 中如何读取 JSON 文件?"},
{"role": "assistant", "content": "可以使用内置的 json 模块:import json; with open(\\"data.json\\") as f: data = json.load(f)"},
{"role": "user", "content": "如果 JSON 文件很大怎么办?"},
},
})

req, _ := http.NewRequest("POST",
"https://tokenhub-intl.tencentcloudmaas.com/v1/chat/completions",
bytes.NewBuffer(body))
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
data, _ := io.ReadAll(resp.Body)
fmt.Println(string(data))
}
说明:
当历史对话中包含思考类响应时,回写 assistant 消息建议同时携带 contentreasoning_content 两个字段,避免推理上下文丢失。

工具调用(Function Calling)

通过 tools 定义模型可调用的函数列表,模型在判断需要调用工具时返回 tool_calls;业务执行后将结果以 role: "tool" 消息回填,模型据此生成最终回答。
cURL
Python
Java
Node.js
Go
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/chat/completions' \\
-H 'Content-Type: application/json' \\
-H 'Authorization: Bearer YOUR_API_KEY' \\
-d '{
"model": "hy3",
"messages": [
{"role": "user", "content": "深圳今天天气怎么样?"}
],
"tools": [{
"type": "function",
"function": {
"name": "get_weather",
"description": "获取指定城市的当前天气信息",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "城市名称,例如:北京"}
},
"required": ["city"]
}
}
}],
"tool_choice": "auto"
}'
from openai import OpenAI

client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://tokenhub-intl.tencentcloudmaas.com/v1",
)

tools = [{
"type": "function",
"function": {
"name": "get_weather",
"description": "获取指定城市的当前天气信息",
"parameters": {
"type": "object",
"properties": {"city": {"type": "string", "description": "城市名称,例如:北京"}},
"required": ["city"],
},
},
}]

response = client.chat.completions.create(
model="hy3",
messages=[{"role": "user", "content": "深圳今天天气怎么样?"}],
tools=tools,
tool_choice="auto",
)
print(response.choices[0].message)
import okhttp3.*;
import com.google.gson.Gson;
import java.util.*;

public class FunctionCalling {
public static void main(String[] args) throws Exception {
Map<String, Object> tool = Map.of(
"type", "function",
"function", Map.of(
"name", "get_weather",
"description", "获取指定城市的当前天气信息",
"parameters", Map.of(
"type", "object",
"properties", Map.of("city", Map.of("type", "string", "description", "城市名称,例如:北京")),
"required", List.of("city")
)
)
);

Map<String, Object> body = new HashMap<>();
body.put("model", "hy3");
body.put("messages", List.of(Map.of("role", "user", "content", "深圳今天天气怎么样?")));
body.put("tools", List.of(tool));
body.put("tool_choice", "auto");

Request request = new Request.Builder()
.url("https://tokenhub-intl.tencentcloudmaas.com/v1/chat/completions")
.header("Authorization", "Bearer YOUR_API_KEY")
.post(RequestBody.create(new Gson().toJson(body),
MediaType.parse("application/json")))
.build();

try (Response response = new OkHttpClient().newCall(request).execute()) {
System.out.println(response.body().string());
}
}
}
import OpenAI from 'openai';

const client = new OpenAI({
apiKey: 'YOUR_API_KEY',
baseURL: 'https://tokenhub-intl.tencentcloudmaas.com/v1',
});

const tools = [{
type: 'function',
function: {
name: 'get_weather',
description: '获取指定城市的当前天气信息',
parameters: {
type: 'object',
properties: { city: { type: 'string', description: '城市名称,例如:北京' } },
required: ['city'],
},
},
}];

const response = await client.chat.completions.create({
model: 'hy3',
messages: [{ role: 'user', content: '深圳今天天气怎么样?' }],
tools,
tool_choice: 'auto',
});
console.log(response.choices[0].message);
package main

import (
"bytes"
"encoding/json"
"fmt"
"io"
"net/http"
)

func main() {
tool := map[string]interface{}{
"type": "function",
"function": map[string]interface{}{
"name": "get_weather",
"description": "获取指定城市的当前天气信息",
"parameters": map[string]interface{}{
"type": "object",
"properties": map[string]interface{}{
"city": map[string]interface{}{"type": "string", "description": "城市名称,例如:北京"},
},
"required": []string{"city"},
},
},
}

body, _ := json.Marshal(map[string]interface{}{
"model": "hy3",
"messages": []map[string]string{{"role": "user", "content": "深圳今天天气怎么样?"}},
"tools": []map[string]interface{}{tool},
"tool_choice": "auto",
})

req, _ := http.NewRequest("POST",
"https://tokenhub-intl.tencentcloudmaas.com/v1/chat/completions",
bytes.NewBuffer(body))
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
data, _ := io.ReadAll(resp.Body)
fmt.Println(string(data))
}
模型决定调用工具时的响应:
{
"id": "REPLACED_ID",
"object": "chat.completion",
"model": "hy3",
"created": 1775146513,
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "我来帮你查询深圳今天的天气情况。",
"tool_calls": [
{
"id": "REPLACED_ID",
"type": "function",
"function": {
"name": "get_weather",
"arguments": "{\\"city\\": \\"深圳\\"}"
}
}
]
},
"finish_reason": "tool_calls"
}
],
"usage": {
"prompt_tokens": 208,
"completion_tokens": 28,
"total_tokens": 236,
"prompt_tokens_details": {"cached_tokens": 0},
"completion_tokens_details": {"reasoning_tokens": 0}
}
}
回填工具执行结果继续对话:
{
"model": "hy3",
"messages": [
{"role": "user", "content": "深圳今天天气怎么样?"},
{
"role": "assistant",
"content": "我来帮您查询深圳今天的天气情况。",
"tool_calls": [{
"id": "REPLACED_ID",
"type": "function",
"function": {"name": "get_weather", "arguments": "{\\"city\\": \\"深圳\\"}"}
}]
},
{
"role": "tool",
"tool_call_id": "REPLACED_ID",
"content": "{\\"temperature\\":28,\\"weather\\":\\"晴\\",\\"humidity\\":\\"65%\\"}"
}
]
}
注意:
reasoning_effort=low/high 的慢思考模式下进行工具调用,每一轮请求都需要回填历史 reasoning_content,以获取最佳效果。

结构化输出

通过 response_format 约束模型按指定的 JSON Schema 输出,常用于信息抽取、结构化数据生成等场景。
cURL
Python
Java
Node.js
Go
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/chat/completions' \\
-H 'Content-Type: application/json' \\
-H 'Authorization: Bearer YOUR_API_KEY' \\
-d '{
"model": "hy3",
"messages": [
{"role": "user", "content": "请从以下文本中提取人物信息:张三,35岁,是一名高级软件工程师,擅长Python、Java和机器学习。"}
],
"response_format": {
"type": "json_schema",
"json_schema": {
"name": "person_info",
"schema": {
"type": "object",
"properties": {
"name": {"type": "string", "description": "人物姓名"},
"age": {"type": "integer", "description": "年龄"},
"occupation": {"type": "string", "description": "职业"},
"skills": {"type": "array", "items": {"type": "string"}, "description": "技能列表"}
},
"required": ["name", "age", "occupation", "skills"]
}
}
}
}'
from openai import OpenAI

client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://tokenhub-intl.tencentcloudmaas.com/v1",
)

schema = {
"type": "object",
"properties": {
"name": {"type": "string", "description": "人物姓名"},
"age": {"type": "integer", "description": "年龄"},
"occupation": {"type": "string", "description": "职业"},
"skills": {"type": "array", "items": {"type": "string"}, "description": "技能列表"},
},
"required": ["name", "age", "occupation", "skills"],
}

response = client.chat.completions.create(
model="hy3",
messages=[
{"role": "user", "content": "请从以下文本中提取人物信息:张三,35岁,是一名高级软件工程师,擅长Python、Java和机器学习。"},
],
response_format={
"type": "json_schema",
"json_schema": {"name": "person_info", "schema": schema},
},
)
print(response.choices[0].message.content)
import okhttp3.*;
import com.google.gson.Gson;
import java.util.*;

public class StructuredOutput {
public static void main(String[] args) throws Exception {
Map<String, Object> schema = Map.of(
"type", "object",
"properties", Map.of(
"name", Map.of("type", "string", "description", "人物姓名"),
"age", Map.of("type", "integer", "description", "年龄"),
"occupation", Map.of("type", "string", "description", "职业"),
"skills", Map.of("type", "array", "items", Map.of("type", "string"), "description", "技能列表")
),
"required", List.of("name", "age", "occupation", "skills")
);

Map<String, Object> body = new HashMap<>();
body.put("model", "hy3");
body.put("messages", List.of(Map.of("role", "user", "content",
"请从以下文本中提取人物信息:张三,35岁,是一名高级软件工程师,擅长Python、Java和机器学习。")));
body.put("response_format", Map.of(
"type", "json_schema",
"json_schema", Map.of("name", "person_info", "schema", schema)
));

Request request = new Request.Builder()
.url("https://tokenhub-intl.tencentcloudmaas.com/v1/chat/completions")
.header("Authorization", "Bearer YOUR_API_KEY")
.post(RequestBody.create(new Gson().toJson(body),
MediaType.parse("application/json")))
.build();

try (Response response = new OkHttpClient().newCall(request).execute()) {
System.out.println(response.body().string());
}
}
}
import OpenAI from 'openai';

const client = new OpenAI({
apiKey: 'YOUR_API_KEY',
baseURL: 'https://tokenhub-intl.tencentcloudmaas.com/v1',
});

const schema = {
type: 'object',
properties: {
name: { type: 'string', description: '人物姓名' },
age: { type: 'integer', description: '年龄' },
occupation: { type: 'string', description: '职业' },
skills: { type: 'array', items: { type: 'string' }, description: '技能列表' },
},
required: ['name', 'age', 'occupation', 'skills'],
};

const response = await client.chat.completions.create({
model: 'hy3',
messages: [
{ role: 'user', content: '请从以下文本中提取人物信息:张三,35岁,是一名高级软件工程师,擅长Python、Java和机器学习。' },
],
response_format: {
type: 'json_schema',
json_schema: { name: 'person_info', schema },
},
});
console.log(response.choices[0].message.content);
package main

import (
"bytes"
"encoding/json"
"fmt"
"io"
"net/http"
)

func main() {
schema := map[string]interface{}{
"type": "object",
"properties": map[string]interface{}{
"name": map[string]interface{}{"type": "string", "description": "人物姓名"},
"age": map[string]interface{}{"type": "integer", "description": "年龄"},
"occupation": map[string]interface{}{"type": "string", "description": "职业"},
"skills": map[string]interface{}{
"type": "array", "items": map[string]string{"type": "string"}, "description": "技能列表",
},
},
"required": []string{"name", "age", "occupation", "skills"},
}

body, _ := json.Marshal(map[string]interface{}{
"model": "hy3",
"messages": []map[string]string{
{"role": "user", "content": "请从以下文本中提取人物信息:张三,35岁,是一名高级软件工程师,擅长Python、Java和机器学习。"},
},
"response_format": map[string]interface{}{
"type": "json_schema",
"json_schema": map[string]interface{}{
"name": "person_info",
"schema": schema,
},
},
})

req, _ := http.NewRequest("POST",
"https://tokenhub-intl.tencentcloudmaas.com/v1/chat/completions",
bytes.NewBuffer(body))
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
data, _ := io.ReadAll(resp.Body)
fmt.Println(string(data))
}
响应示例:
{
"id": "REPLACED_ID",
"object": "chat.completion",
"model": "hy3",
"created": 1775146513,
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "{\\n \\"age\\": 35,\\n \\"name\\": \\"张三\\",\\n \\"occupation\\": \\"高级软件工程师\\",\\n \\"skills\\": [\\"Python\\", \\"Java\\", \\"机器学习\\"]\\n}"
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 38,
"completion_tokens": 42,
"total_tokens": 80,
"prompt_tokens_details": {"cached_tokens": 0},
"completion_tokens_details": {"reasoning_tokens": 0}
}
}

翻译模型

Hy-MT2 是一款面向真实复杂场景的“快思考”多语言翻译模型家族,包含 1.8B、7B、30B-A3B(MoE)三种体量,支持 33 个语种之间的互译,并能高效遵循多语言翻译指令。多维度评测显示,Hy-MT2 在通用翻译、真实业务场景翻译、垂直领域翻译以及指令遵循翻译等任务上均表现出色。

支持的模型

model(调用参数)
能力说明
上下文窗口
最大输入
最大输出
hy-mt2-plus
翻译模型,参数量7B。业界效果领先,开源测试集 Flores200、WMT25 效果领先,专业领域和真实业务场景表现优秀。支持语种齐全,重点支持33个语种互译,支持5种民汉/方言。
8k
4k
4k

基础翻译

最常见的翻译场景,在 user 消息中明确指定目标语种target_lang 使用完整中文名,如“英语”、“法语”、“中文”)。
"messages": [{"role": "user", "content": "将以下文本翻译为 {target_lang},注意只需要输出翻译后的结果,不要额外解释:{source_text}"}]
cURL
Python
Java
Node.js
Go
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/chat/completions' \\
-H 'Content-Type: application/json' \\
-H 'Authorization: Bearer YOUR_API_KEY' \\
-d '{
"model": "hy-mt2-plus",
"messages": [
{"role": "user", "content": "将以下文本翻译为 法语 ,注意只需要输出翻译后的结果,不要额外解释: Please ensure that all attendees have received the agenda before the meeting starts."}
]
}'
from openai import OpenAI

client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://tokenhub-intl.tencentcloudmaas.com/v1",
)

target_lang = "法语"
source_text = "Please ensure that all attendees have received the agenda before the meeting starts."

prompt = f"""将以下文本翻译为 {target_lang},注意只需要输出翻译后的结果,不要额外解释:
{source_text}"""

response = client.chat.completions.create(
model="hy-mt2-plus",
messages=[{"role": "user", "content": prompt}],
)
print(response.choices[0].message.content)
import okhttp3.*;
import com.google.gson.Gson;
import java.util.*;

public class TranslationDemo {
public static void main(String[] args) throws Exception {
String targetLang = "法语";
String sourceText = "Please ensure that all attendees have received the agenda before the meeting starts.";
String prompt = "将以下文本翻译为 " + targetLang + ",注意只需要输出翻译后的结果,不要额外解释:\\n" + sourceText;

Map<String, Object> body = new HashMap<>();
body.put("model", "hy-mt2-plus");
body.put("messages", List.of(
Map.of("role", "user", "content", prompt)
));

Request request = new Request.Builder()
.url("https://tokenhub-intl.tencentcloudmaas.com/v1/chat/completions")
.header("Authorization", "Bearer YOUR_API_KEY")
.post(RequestBody.create(new Gson().toJson(body),
MediaType.parse("application/json")))
.build();

try (Response response = new OkHttpClient().newCall(request).execute()) {
System.out.println(response.body().string());
}
}
}
import OpenAI from 'openai';

const client = new OpenAI({
apiKey: 'YOUR_API_KEY',
baseURL: 'https://tokenhub-intl.tencentcloudmaas.com/v1',
});

const targetLang = '法语';
const sourceText = 'Please ensure that all attendees have received the agenda before the meeting starts.';
const prompt = `将以下文本翻译为 ${targetLang},注意只需要输出翻译后的结果,不要额外解释:\\n${sourceText}`;

const response = await client.chat.completions.create({
model: 'hy-mt2-plus',
messages: [{ role: 'user', content: prompt }],
});
console.log(response.choices[0].message.content);
package main

import (
"bytes"
"encoding/json"
"fmt"
"io"
"net/http"
)

func main() {
targetLang := "法语"
sourceText := "Please ensure that all attendees have received the agenda before the meeting starts."
prompt := "将以下文本翻译为 " + targetLang + ",注意只需要输出翻译后的结果,不要额外解释:\\n" + sourceText

body, _ := json.Marshal(map[string]interface{}{
"model": "hy-mt2-plus",
"messages": []map[string]string{
{"role": "user", "content": prompt},
},
})

req, _ := http.NewRequest("POST",
"https://tokenhub-intl.tencentcloudmaas.com/v1/chat/completions",
bytes.NewBuffer(body))
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
data, _ := io.ReadAll(resp.Body)
fmt.Println(string(data))
}
响应示例:
{
"id": "REPLACED_ID",
"object": "chat.completion",
"model": "hy-mt2-plus",
"created": 1775146513,
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Veuillez vous assurer que tous les participants ont reçu l’ordre du jour avant le début de la réunion."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 26,
"completion_tokens": 28,
"total_tokens": 54,
"prompt_tokens_details": {"cached_tokens": 0},
"completion_tokens_details": {"reasoning_tokens": 0}
}
}

结构化数据翻译

当原文是 JSON / Markdown / HTML / XML 等结构化数据时,模型会“锁定结构、仅翻译可见 value、保留所有 key 与占位符”。
"messages": [{"role": "user", "content": "
# 任务目标
将下方 {source_text} 中的 {format_type} 格式数据翻译为 {target_lang}

# 严格约束
1. 结构锁定:绝对保持原有的 {format_type} 数据结构、缩进和层级完全不变。
2. 选择性翻译:仅翻译面向用户展示的可见文本内容。
3. 禁止修改:严禁翻译或更改任何代码标签、键名 (Key)、变量占位符(如 {{var}}、${var}、%s、%d 等)或代码属性。

# 数据输入
{source_text}"}]
cURL
Python
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/chat/completions' \\
-H 'Content-Type: application/json' \\
-H 'Authorization: Bearer YOUR_API_KEY' \\
-d '{
"model": "hy-mt2-plus",
"messages": [
{"role": "user", "content": "# 任务目标\\n将下方 source_text 中的 JSON 格式数据翻译为 法语。\\n\\n# 严格约束\\n1. 结构锁定:绝对保持原有的 JSON 数据结构、缩进和层级完全不变。\\n2. 选择性翻译:仅翻译面向用户展示的可见文本内容。\\n3. 禁止修改:严禁翻译或更改任何代码标签、键名 (Key)、变量占位符(如 {{var}}、${var}、%s、%d 等)或代码属性。\\n\\n# 数据输入\\n{\\"title\\": \\"West Lake Scenic Area\\", \\"description\\": \\"Located in the heart of Hangzhou, it is a national 5A-level tourist attraction known for its pleasant scenery throughout the four seasons.\\", \\"tags\\": [\\"Natural Scenery\\", \\"World Heritage\\", \\"Free Admission\\"]}"}
]
}'
from openai import OpenAI

client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://tokenhub-intl.tencentcloudmaas.com/v1",
)

target_lang = "法语"
format_type = "JSON"
source_text = '{"title": "West Lake Scenic Area", "description": "Located in the heart of Hangzhou, it is a national 5A-level tourist attraction known for its pleasant scenery throughout the four seasons.", "tags": ["Natural Scenery", "World Heritage", "Free Admission"]}'

prompt = f"""# 任务目标
将下方 source_text 中的 {format_type} 格式数据翻译为 {target_lang}。

# 严格约束
1. 结构锁定:绝对保持原有的 {format_type} 数据结构、缩进和层级完全不变。
2. 选择性翻译:仅翻译面向用户展示的可见文本内容。
3. 禁止修改:严禁翻译或更改任何代码标签、键名 (Key)、变量占位符(如 {{var}}、${{var}}、%s、%d 等)或代码属性。

# 数据输入
{source_text}"""

response = client.chat.completions.create(
model="hy-mt2-plus",
messages=[{"role": "user", "content": prompt}],
)
print(response.choices[0].message.content)
响应示例:
{
"id": "REPLACED_ID",
"object": "chat.completion",
"model": "hy-mt2-plus",
"created": 1779966611,
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "{\\"title\\": \\"Zone panoramique du lac de l’Ouest\\", \\"description\\": \\"Située au cœur de Hangzhou, il s’agit d’une attraction touristique nationale de niveau 5A réputée pour ses paysages magnifiques tout au long des quatre saisons.\\", \\"tags\\": [\\"Paysages naturels\\", \\"Patrimoine mondial\\", \\"Entrée gratuite\\"]}"
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 145,
"completion_tokens": 87,
"total_tokens": 232,
"prompt_tokens_details": {"cached_tokens": 0},
"completion_tokens_details": {"reasoning_tokens": 0}
}
}

分隔符翻译

需要逐句对照批量翻译多段文本时,让模型保留等量的分隔符且不遗漏、不转义、不翻译,便于业务侧按下标对齐。
推荐使用 <SEP>### 等不会与目标语言标点冲突的标签作为分隔符。|||--- 等容易被部分语言识别为感叹号、破折号等标点,导致译文不可切分。
"messages": [{"role": "user", "content": "请将以下文本准确翻译为 {target_lang}。
你必须在译文中保留等量的分隔符,绝对不可遗漏、转义或翻译该符号,并注意分隔符的位置。{source_text}"}]
cURL
Python
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/chat/completions' \\
-H 'Content-Type: application/json' \\
-H 'Authorization: Bearer YOUR_API_KEY' \\
-d '{
"model": "hy-mt2-plus",
"messages": [
{"role": "user", "content": "请将以下文本准确翻译为 法语。你必须在译文中保留等量的分隔符,绝对不可遗漏、转义或翻译该符号,并注意分隔符的位置。\\nGetting eight hours of sleep every day is beneficial for good health<SEP>Properly planning work and rest can improve efficiency<SEP>Moderate exercise can effectively relieve stress"}
]
}'
from openai import OpenAI

client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://tokenhub-intl.tencentcloudmaas.com/v1",
)

target_lang = "法语"
SEP = "<SEP>"
source_segments = ["Getting eight hours of sleep every day is beneficial for good health", "Properly planning work and rest can improve efficiency", "Moderate exercise can effectively relieve stress"]
source_text = SEP.join(source_segments)

prompt = f"""请将以下文本准确翻译为 {target_lang}。你必须在译文中保留等量的分隔符,绝对不可遗漏、转义或翻译该符号,并注意分隔符的位置。
{source_text}"""

response = client.chat.completions.create(
model="hy-mt2-plus",
messages=[{"role": "user", "content": prompt}],
)

translated = response.choices[0].message.content.split(SEP)
for src, tgt in zip(source_segments, translated):
print(f"{src.strip()} → {tgt.strip()}")
响应示例:
{
"id": "REPLACED_ID",
"object": "chat.completion",
"model": "hy-mt2-plus",
"created": 1779966612,
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Dormir huit heures par jour est bénéfique pour une bonne santé<SEP>Planifier correctement le travail et les moments de repos peut améliorer l’efficacité<SEP>Une activité physique modérée peut soulager efficacement le stress"
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 74,
"completion_tokens": 59,
"total_tokens": 133,
"prompt_tokens_details": {"cached_tokens": 0},
"completion_tokens_details": {"reasoning_tokens": 0}
}
}

上下文翻译

当原文存在多义词、专有名词、代词指代等需要语境消歧的情况时,提供“背景信息”可以让模型选用与上下文一致的术语。
"messages": [{"role": "user", "content": "
【背景信息】{background_text}
请结合背景信息将以下文本翻译为 {target_lang}。
【待翻译文本】{source_text}"}]
cURL
Python
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/chat/completions' \\
-H 'Content-Type: application/json' \\
-H 'Authorization: Bearer YOUR_API_KEY' \\
-d '{
"model": "hy-mt2-plus",
"messages": [
{"role": "user", "content": "【背景信息】\\nThis is a technical document introducing database systems. The transaction mentioned above refers to database transactions, and index refers to database indexes.\\n请结合背景信息将以下文本翻译为 法语。\\n【待翻译文本】\\nAfter a transaction is committed, the index is asynchronously flushed to disk."}
]
}'
from openai import OpenAI

client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://tokenhub-intl.tencentcloudmaas.com/v1",
)

target_lang = "法语"
background_text = "This is a technical document introducing database systems. The transaction mentioned above refers to database transactions, and index refers to database indexes."
source_text = "After a transaction is committed, the index is asynchronously flushed to disk."

prompt = f"""【背景信息】
{background_text}
请结合背景信息将以下文本翻译为 {target_lang}。
【待翻译文本】
{source_text}"""

response = client.chat.completions.create(
model="hy-mt2-plus",
messages=[{"role": "user", "content": prompt}],
)
print(response.choices[0].message.content)
响应示例:
{
"id": "REPLACED_ID",
"object": "chat.completion",
"model": "hy-mt2-plus",
"created": 1779966614,
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Une fois une transaction validée, l’index est écrit de manière asynchrone sur le disque."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 65,
"completion_tokens": 24,
"total_tokens": 89,
"prompt_tokens_details": {"cached_tokens": 0},
"completion_tokens_details": {"reasoning_tokens": 0}
}
}

术语表翻译

业务侧拥有领域术语表(产品名、品牌词、专有名词等需固定译法)时,将术语对照清单作为参考前置,模型会优先按指定译法翻译。
"messages": [{"role": "user", "content": "
参考下面的翻译:
{text} 翻译成 {text}
{text} 翻译成 {text}
{text} 翻译成 {text}
将以下文本翻译为 {target_lang},注意只需要输出翻译后的结果,不要额外解释:{source_text}"}]
cURL
Python
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/chat/completions' \\
-H 'Content-Type: application/json' \\
-H 'Authorization: Bearer YOUR_API_KEY' \\
-d '{
"model": "hy-mt2-plus",
"messages": [
{"role": "user", "content": "参考下面的翻译:\\npremiere 翻译成 première\\nratings 翻译成 audiences\\n将以下文本翻译为 法语,注意只需要输出翻译后的结果,不要额外解释:\\nThe ratings for this drama kept rising after its premiere on media platforms."}
]
}'
from openai import OpenAI

client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://tokenhub-intl.tencentcloudmaas.com/v1",
)

target_lang = "法语"
glossary = [
("premiere", "première"),
("ratings", "audiences"),
]
source_text = "The ratings for this drama kept rising after its premiere on media platforms."

glossary_text = "\\n".join(f"{src} 翻译成 {tgt}" for src, tgt in glossary)
prompt = f"""参考下面的翻译:
{glossary_text}
将以下文本翻译为 {target_lang},注意只需要输出翻译后的结果,不要额外解释:
{source_text}"""

response = client.chat.completions.create(
model="hy-mt2-plus",
messages=[{"role": "user", "content": prompt}],
)
print(response.choices[0].message.content)
响应示例:
{
"id": "REPLACED_ID",
"object": "chat.completion",
"model": "hy-mt2-plus",
"created": 1779967706,
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Les audiences de cette série ont continué d’augmenter après sa première diffusion sur les plateformes médiatiques."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 58,
"completion_tokens": 28,
"total_tokens": 86,
"prompt_tokens_details": {"cached_tokens": 0},
"completion_tokens_details": {"reasoning_tokens": 0}
}
}

风格翻译

不同业务场景对译文风格要求不同(口语化 / 书面化 / 营销文案 / 法律合同 / 学术 / 古文等),描述出目标风格,模型会按要求调整用词与句式。
"messages": [{"role": "user", "content": "
请将以下文本翻译为 {target_lang}。
注意翻译的风格要严格符合【{target_style}】
{source_text}"}]
cURL
Python
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/chat/completions' \\
-H 'Content-Type: application/json' \\
-H 'Authorization: Bearer YOUR_API_KEY' \\
-d '{
"model": "hy-mt2-plus",
"messages": [
{"role": "user", "content": "请将以下文本翻译为 法语。注意翻译的风格要严格符合【科普文案:语言简洁有力、富有感染力】\\nModerate outdoor activities help regulate emotions and alleviate mental stress."}
]
}'
from openai import OpenAI

client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://tokenhub-intl.tencentcloudmaas.com/v1",
)

target_lang = "法语"
target_style = "科普文案:语言简洁有力、富有感染力"
source_text = "Moderate outdoor activities help regulate emotions and alleviate mental stress."

prompt = f"""请将以下文本翻译为 {target_lang}。注意翻译的风格要严格符合【{target_style}】
{source_text}"""

response = client.chat.completions.create(
model="hy-mt2-plus",
messages=[{"role": "user", "content": prompt}],
)
print(response.choices[0].message.content)
响应示例:
{
"id": "REPLACED_ID",
"object": "chat.completion",
"model": "hy-mt2-plus",
"created": 1779966617,
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Les activités physiques modérées en plein air aident à réguler les émotions et à réduire le stress mental."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 43,
"completion_tokens": 30,
"total_tokens": 73,
"prompt_tokens_details": {"cached_tokens": 0},
"completion_tokens_details": {"reasoning_tokens": 0}
}
}

术语库

与上述 术语表翻译(prompt 内嵌术语)不同,本节使用独立的翻译接口与持久化术语库,更适合术语量大、复用频率高的工程化场景。
注意:
目前仅 OpenAPI 协议支持使用混元翻译术语库。接口地址:https://tokenhub-intl.tencentcloudmaas.com/v1/api/translations
可参考 术语库管理相关接口 创建、修改、查询术语库。
请求参数说明
参数
类型
必填
说明
model
string
model 参数,如 hy-mt2-plus
text
string
待翻译的文本
target
string
目标语言代码
source
string
源语言代码,如不传参则模型自动识别
stream
bool
是否流式返回,默认 false
context
string
上下文信息,用于让译文更连贯
references
list of object
参考示例(句子或术语),最多 10 个
glossary_ids
list of string
术语库 ID 列表,最多 10 个
响应字段说明
字段
类型
说明
id
string
此次请求的 id
Created
integer
Unix 时间戳
choices
list
返回的回复, 支持多个
choices[n].finish_reason
string
stop 表示正常结束,sensitive 表示审核不通过
choices[n].message
json
返回的内容
choices[n].message.role
string
角色名称
choices[n].message.content
string
翻译后的文本
choices[n].delta
json
返回的内容(流式)
choices[n].delta.role
string
角色名称(流式)
choices[n].delta.content
string
翻译后的文本(流式)
source
string
请求源语言
target
string
目标语言
usage
object
token 使用量
请求示例
cURL
Python
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/api/translations' \\
-H 'Content-Type: application/json' \\
-H 'Authorization: Bearer YOUR_API_KEY' \\
-d '{
"model": "hy-mt2-plus",
"text": "This model is equipped with an advanced Battery Management System (BMS), offering a driving range of over 600 kilometers along with fast charging support.",
"source": "en",
"target": "fr",
"glossary_ids": ["YOUR_GLOSSARY_ID"]
}'
import requests

url = "https://tokenhub-intl.tencentcloudmaas.com/v1/api/translations"
headers = {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
}
payload = {
"model": "hy-mt2-plus",
"text": "This model is equipped with an advanced Battery Management System (BMS), offering a driving range of over 600 kilometers along with fast charging support.",
"source": "en",
"target": "fr",
"glossary_ids": ["YOUR_GLOSSARY_ID"],
}

response = requests.post(url, headers=headers, json=payload)
data = response.json()
print(data["choices"][0]["message"]["content"])
响应示例
{
"id": "REPLACED_ID",
"created": 1781604284,
"choices": [
{
"index": 0,
"finish_reason": "stop",
"message": {
"role": "assistant",
"content": "Ce modèle est équipé d’un système avancé de gestion de batterie (BMS), qui lui permet d’atteindre une autonomie de plus de 600 kilomètres, tout en offrant une fonction de charge rapide."
}
}
],
"source": "en",
"target": "fr",
"usage": {
"prompt_tokens": 85,
"completion_tokens": 46,
"total_tokens": 131
}
}

支持的语言

语言
英文名
代码
简体中文
Chinese
zh
繁体中文
Traditional Chinese
zh-TR
英语
English
en
法语
French
fr
葡萄牙语
Portuguese
pt
西班牙语
Spanish
es
日语
Japanese
ja
土耳其语
Turkish
tr
俄语
Russian
ru
阿拉伯语
Arabic
ar
韩语
Korean
ko
泰语
Thai
th
意大利语
Italian
it
德语
German
de
越南语
Vietnamese
vi
马来语
Malay
ms
印尼语
Indonesian
id
菲律宾语
Filipino
fil
印地语
Hindi
hi
波兰语
Polish
pl
捷克语
Czech
cs
荷兰语
Dutch
nl
高棉语
Khmer
km
缅甸语
Burmese
my
波斯语
Persian
fa
古吉拉特语
Gujarati
gu
乌尔都语
Urdu
ur
泰卢固语
Telugu
te
马拉地语
Marathi
mr
希伯来语
Hebrew
he
孟加拉语
Bengali
bn
泰米尔语
Tamil
ta
乌克兰语
Ukrainian
uk
藏语
Tibetan
bo
哈萨克语
Kazakh
kk
蒙古语
Mongolian
mn
维吾尔语
Uyghur
ug
粤语
Cantonese
yue


帮助和支持

本页内容是否解决了您的问题?

填写满意度调查问卷,共创更好文档体验。

文档反馈