必须绕过OpenAI兼容层，直接使用腾讯云原生SDK或合规HTTP客户端调用混元API；需配置SecretId/SecretKey环境变量、引入v3.1.1110 SDK、指定ap-guangzhou区域、显式设置model字段，并为非chat接口（如Embedding）正确添加X-TC-Action头。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
要在Spring Boot项目中稳定调用腾讯混元大模型的API，必须绕过OpenAI兼容层的隐性限制，直接对接腾讯云原生SDK或封装合规的HTTP客户端。
准备混元API密钥与环境
登录腾讯云控制台 → 进入【访问管理】→【API密钥管理】→ 创建新的密钥对（SecretId + SecretKey）。【务必勾选“Hunyuan服务”权限】，否则后续调用会返回403错误。
将生成的SecretId和SecretKey保存为环境变量：TENCENTCLOUD_SECRET_ID、TENCENTCLOUD_SECRET_KEY。不要硬编码进代码或配置文件。
引入官方Java SDK依赖
在pom.xml中添加腾讯云混元v3.1.1110版本SDK：
<dependency>
<groupId>com.tencentcloudapi</groupId>
<artifactId>tencentcloud-sdk-java-hunyuan</artifactId>
<version>3.1.1110</version>
</dependency>
注意：该SDK已内置签名逻辑与重试机制，比手动拼接HTTP请求更可靠。若使用低版本SDK，可能因缺少X-TC-Action头导致embedding等非聊天接口调用失败。
配置HunyuanClient为Spring Bean
新建HunyuanConfig类，注入Credential与ClientProfile：
@Configuration
public class HunyuanConfig {
@Bean
@ConditionalOnMissingBean
public HunyuanClient hunyuanClient() {
Credential cred = new Credential(
System.getenv("TENCENTCLOUD_SECRET_ID"),
System.getenv("TENCENTCLOUD_SECRET_KEY")
);
HttpProfile httpProfile = new HttpProfile();
httpProfile.setEndpoint("hunyuan.tencentcloudapi.com");
ClientProfile clientProfile = new ClientProfile();
clientProfile.setHttpProfile(httpProfile);
return new HunyuanClient(cred, "ap-guangzhou", clientProfile);
}
}
其中区域参数"ap-guangzhou"不可省略——混元API强制要求指定Region，填错会导致InvalidRegion错误。
编写调用逻辑（以ChatCompletions为例）
第一步：构造ChatCompletionsRequest对象，设置messages、model、temperature等字段；
第二步：调用client.ChatCompletions(req)发起同步请求；
第三步：从ChatCompletionsResponse中提取resp.getChoices().get(0).getMessage().getContent()获取回复文本。
这一步操作起来很简单，但要注意：若未在request中显式设置model字段（如"hyun-pro"或"hyun-standard"），API将默认使用已下线的老版本模型，返回空响应或400错误。
扩展支持Embedding接口
方法一：复用同一HunyuanClient实例，手动构造POST请求到"/"路径，并在Header中添加X-TC-Action: "TextEmbedding"；
方法二：创建专用EmbeddingService，封装EmbeddingRequest与EmbeddingResponse实体类，通过RestTemplate调用，Header中必须携带X-TC-Action与Authorization签名；
方法三：升级至spring-ai-hunyuan-starter 0.2.0+版本，直接注入EmbeddingClient并调用embed()方法。
关键点在于：所有非chat接口都共用同一个域名和根路径，仅靠X-TC-Action头区分功能类型，漏设该Header将始终返回聊天接口的错误响应。
