腾讯混元 API
  1. 数据结构
腾讯混元 API
  • 简介
  • API 概览
  • 签名方法
  • 调用方式
    • 请求结构
    • 公共参数
    • 签名方法 v3
    • 返回结果
    • 参数类型
  • 混元生文相关接口
    • 向量化
    • Token 计数
    • 翻译
    • 对话
      • 对话
      • system prompt
      • 多轮对话
  • 混生元文件对话相关接口
    • 创建会话
    • 执行会话
    • 查询会话
    • 会话消息列表
    • 获取会话消息
  • 混生元文文件相关接口
    • 文件上传
    • 文件列表
    • 文件删除
  • 混元生图相关接口
    • 提交混元生图任务
    • 查询混元生图任务
    • 提交混元生图（多轮对话）任务
    • 查询混元生图（多轮对话）任务
    • 文生图轻量版
  • 控制台相关接口
    • 开通服务
    • 设置付费模式
  • 数据结构
    • 数据结构
  • 错误码
    • 错误码
  1. 数据结构

数据结构

Choice#

返回的回复, 支持多个
被如下接口引用：ChatCompletions。
名称类型描述
FinishReasonString结束标志位，可能为 stop、 sensitive或者tool_calls。 stop 表示输出正常结束。 sensitive 只在开启流式输出审核时会出现，表示安全审核未通过。 tool_calls 标识函数调用。 示例值：stop
DeltaDelta增量返回值，流式调用时使用该字段。 注意：此字段可能返回 null，表示取不到有效值。
MessageMessage返回值，非流式调用时使用该字段。 注意：此字段可能返回 null，表示取不到有效值。
IndexInteger索引值，流式调用时使用该字段。 示例值：0
ModerationLevelString多轮会话风险审核，值为1时，表明存在信息安全风险，建议终止客户多轮会话。 示例值：1

Content#

可以传入多种类型的内容，如图片或文本。
被如下接口引用：ChatCompletions。
名称类型必选描述
TypeString是内容类型 注意： 需包含至少一个 Type 为"text"的参数及至少一个 Type 为"image_url"的参数。 参数值可选范围：[text", "image_url"] 注意：此字段可能返回 null，表示取不到有效值。 示例值：text
TextString否当 Type 为 text 时使用，表示具体的文本内容。当 Type 为 image_url 时，当前字段内容需保持为空，传递内容不生效。 注意：此字段可能返回 null，表示取不到有效值。 示例值：下面图片中是哪个公司的 Logo？
ImageUrlImageUrl否图片的url，当 Type 为 image_url 时使用，表示具体的图片内容 如"https://example.com/1.png" 或 图片的base64（注意 "data:image/jpeg;base64," 为必要部分）："data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAA......"。当 Type 为 text 时，当前字段内容需保持为空，传递内容不生效。 注意：此字段可能返回 null，表示取不到有效值。

Delta#

返回的内容（流式返回）
被如下接口引用：ChatCompletions。
名称类型描述
RoleString角色名称。 示例值：assistant
ContentString内容详情。 示例值：你好！请问有什么我可以帮助你的吗？
ToolCallsArray of ToolCall模型生成的工具调用，仅 hunyuan-functioncall 模型支持 说明： 对于每一次的输出值应该以Id为标识对Type、Name、Arguments字段进行合并。 注意：此字段可能返回 null，表示取不到有效值。

EmbeddingData#

Embedding 信息。
被如下接口引用：GetEmbedding。
名称类型描述
EmbeddingArray of FloatEmbedding 信息，目前为 1024 维浮点数。 注意：此字段可能返回 null，表示取不到有效值。
IndexInteger下标，目前不支持批量，因此固定为 0。 注意：此字段可能返回 null，表示取不到有效值。 示例值：0
ObjectString目前固定为 "embedding"。 注意：此字段可能返回 null，表示取不到有效值。 示例值：embedding

EmbeddingUsage#

Token 使用计数。
被如下接口引用：GetEmbedding。
名称类型描述
PromptTokensInteger输入 Token 数。 示例值：8
TotalTokensInteger总 Token 数。 示例值：8

ErrorMsg#

运行时异常信息。
被如下接口引用：ChatCompletions, ChatTranslations。
名称类型描述
MsgString错误提示信息。
CodeInteger错误码。 4000 服务内部异常。 4001 请求模型超时。

FileObject#

已上传的文件对象。
被如下接口引用：FilesList。
名称类型必选描述
IDString否文件标识符，可在各个API中引用。 示例值：file-YbhlphnNEsjRoKTEXukAqNZZ
ObjectString否对象类型，始终为 file。 示例值：file
BytesInteger否文件大小，单位为字节。 示例值：15877
CreatedAtInteger否文件创建时的 Unix 时间戳（秒）。 示例值：1722325693
FilenameString否文件名。 示例值：test.docx
PurposeString否上传文件的用途。 示例值：file-extract

History#

混元生图多轮对话历史记录。
被如下接口引用：QueryHunyuanImageChatJob。
名称类型必选描述
ChatIdString否对话的 ID，用于唯一标识一轮对话 注意：此字段可能返回 null，表示取不到有效值。
PromptString否原始输入的 Prompt 文本 注意：此字段可能返回 null，表示取不到有效值。
RevisedPromptString否扩写后的 Prompt 文本 注意：此字段可能返回 null，表示取不到有效值。
SeedInteger否生成图的随机种子 注意：此字段可能返回 null，表示取不到有效值。

ImageUrl#

具体的图片内容
被如下接口引用：ChatCompletions。
名称类型必选描述
UrlString是图片的 Url（以 http:// 或 https:// 开头） 注意：此字段可能返回 null，表示取不到有效值。 示例值：https://cloudcache.tencent-cloud.com/qcloud/ui/portal-set/build/About/images/bg-product-series_87d.png

LogoParam#

logo参数
被如下接口引用：SubmitHunyuanImageChatJob, SubmitHunyuanImageJob, TextToImageLite。
名称类型必选描述
LogoUrlString否水印url 示例值：https://xxx.com/logo.jpg
LogoImageString否水印base64，url和base64二选一传入 示例值：9j/4QlQaHR0c...N6a2M5ZCI
LogoRectLogoRect否水印图片位于融合结果图中的坐标，将按照坐标对标识图片进行位置和大小的拉伸匹配 示例值：{"X": 10, "Y": 10, "Width": 20, "Height": 20}

LogoRect#

输入框
被如下接口引用：SubmitHunyuanImageChatJob, SubmitHunyuanImageJob, TextToImageLite。
名称类型必选描述
XInteger否左上角X坐标 示例值：10
YInteger否左上角Y坐标 示例值：10
WidthInteger否方框宽度 示例值：20
HeightInteger否方框高度 示例值：20

Message#

会话内容
被如下接口引用：ChatCompletions。
名称类型必选描述
RoleString是角色，可选值包括 system、user、assistant、 tool。 示例值：user
ContentString否文本内容 示例值：你好！
ContentsArray of Content否多种类型内容（目前支持图片和文本），仅 hunyuan-vision 和 hunyuan-turbo-vision 模型支持 注意：此字段可能返回 null，表示取不到有效值。
ToolCallIdString否当role为tool时传入，标识具体的函数调用 注意：此字段可能返回 null，表示取不到有效值。 示例值：call_cpv320k2c3m8fgcs8ja0
ToolCallsArray of ToolCall否模型生成的工具调用，仅 hunyuan-pro 或者 hunyuan-functioncall 模型支持 注意：此字段可能返回 null，表示取不到有效值。
FileIDsArray of String否文件标识符。单次最大 50 个文件。 注意：此字段可能返回 null，表示取不到有效值。 示例值：["file-YbhlphnNEsjRoKTEXukAqNZZ"]

Mindmap#

脑图
被如下接口引用：ChatCompletions。
名称类型必选描述
ThumbUrlString是脑图缩略图链接 注意：此字段可能返回 null，表示取不到有效值。
UrlString是脑图图片链接 注意：此字段可能返回 null，表示取不到有效值。

Multimedia#

多媒体详情
被如下接口引用：ChatCompletions。
名称类型描述
TypeString多媒体类型，可选值包括 image、music、album、playlist。 说明： 1. image：图片；music：单曲，类型为单曲时，会返回详细歌手和歌曲信息；album：专辑；playlist：歌单。 2. 当 type 为 music、album、playlist 时，需要配合 QQ音乐SDK 使用。 示例值：image
UrlString多媒体地址。 说明： 1. type 为 image 时，地址为图片的预览地址；其他类型时，地址为封面图地址。
JumpUrlString多媒体详情地址。 说明： 1. 仅 type 为 image 时，该字段有值。 注意：此字段可能返回 null，表示取不到有效值。
TitleString名称。 说明： 1. type 为 image 时，该字段为空。 注意：此字段可能返回 null，表示取不到有效值。
DescString描述。 注意：此字段可能返回 null，表示取不到有效值。
SingerString歌手名称。 说明： 1. 仅 type 为 music 时，该字段有值。 注意：此字段可能返回 null，表示取不到有效值。
ExtSongExt歌曲详情。 说明： 1. 仅 type 为 music 时，该字段有值。 注意：此字段可能返回 null，表示取不到有效值。

Reference#

翻译对话参考示例
被如下接口引用：ChatTranslations。
名称类型必选描述
TypeString否翻译文本类型，枚举"sentence"表示句子, "term"表示术语 示例值：sentence
TextString否原文 示例值：Computer games are a perfect recipe for strengthening our cognitive skills
TranslationString否译文 示例值：电脑游戏是增强我们认知能力的完美秘诀

RelevantEntity#

相关组织及人物
被如下接口引用：ChatCompletions。
名称类型必选描述
NameString是相关组织及人物名称 注意：此字段可能返回 null，表示取不到有效值。
ContentString是相关组织及人物内容 注意：此字段可能返回 null，表示取不到有效值。
ReferenceArray of Integer是相关事件引用文章标号 注意：此字段可能返回 null，表示取不到有效值。

RelevantEvent#

相关事件
被如下接口引用：ChatCompletions。
名称类型必选描述
TitleString是相关事件标题 注意：此字段可能返回 null，表示取不到有效值。
ContentString是相关事件内容 注意：此字段可能返回 null，表示取不到有效值。
DatetimeString是相关事件时间 注意：此字段可能返回 null，表示取不到有效值。
ReferenceArray of Integer是相关事件引用文章标号 注意：此字段可能返回 null，表示取不到有效值。

Replace#

多媒体占位符替换信息
被如下接口引用：ChatCompletions。
名称类型描述
IdString占位符序号 示例值：0
MultimediaArray of Multimedia多媒体详情

SearchInfo#

搜索结果信息
被如下接口引用：ChatCompletions。
名称类型必选描述
SearchResultsArray of SearchResult否搜索引文信息 注意：此字段可能返回 null，表示取不到有效值。
MindmapMindmap否脑图（回复中不一定存在，流式协议中，仅在最后一条流式数据中返回） 注意：此字段可能返回 null，表示取不到有效值。
RelevantEventsArray of RelevantEvent否相关事件（回复中不一定存在，流式协议中，仅在最后一条流式数据中返回，深度模式下返回） 注意：此字段可能返回 null，表示取不到有效值。
RelevantEntitiesArray of RelevantEntity否相关组织及人物（回复中不一定存在，流式协议中，仅在最后一条流式数据中返回，深度模式下返回） 注意：此字段可能返回 null，表示取不到有效值。
TimelineArray of Timeline否时间线（回复中不一定存在，流式协议中，仅在最后一条流式数据中返回，深度模式下返回） 注意：此字段可能返回 null，表示取不到有效值。
SupportDeepSearchBoolean否是否命中搜索深度模式 注意：此字段可能返回 null，表示取不到有效值。
OutlineArray of String否搜索回复大纲（深度模式下返回） 注意：此字段可能返回 null，表示取不到有效值。

SearchResult#

搜索引文信息
被如下接口引用：ChatCompletions。
名称类型必选描述
IndexInteger否搜索引文序号 注意：此字段可能返回 null，表示取不到有效值。
TitleString否搜索引文标题 注意：此字段可能返回 null，表示取不到有效值。
UrlString否搜索引文链接 注意：此字段可能返回 null，表示取不到有效值。
TextString否搜索引文站点名
IconString否搜索引文图标

SongExt#

歌曲详情。具体含义参考 QQ音乐SDK
被如下接口引用：ChatCompletions。
名称类型描述
SongIdInteger歌曲id 示例值：97773
SongMidString歌曲mid 示例值：0039MnYb0qxYhV
VipInteger歌曲是否为vip。1：vip歌曲； 0：普通歌曲。 示例值：1

ThreadAdditionalMessage#

会话额外消息
被如下接口引用：RunThread。
名称类型必选描述
RoleString否角色 示例值：user
ContentString否内容 示例值：你好
AttachmentsArray of ThreadMessageAttachmentObject否附件 注意：此字段可能返回 null，表示取不到有效值。 示例值：[{"FileID":"file-tMjt0CQnvU25GwUDkih4tU4H"}]

ThreadMessage#

会话消息
被如下接口引用：GetThreadMessageList。
名称类型描述
IDString消息 ID 示例值：msg_pYmfqfAkOcN5bM1rjdEjbVZV
ObjectString对象类型 示例值：thread.message
CreatedAtInteger创建时间 示例值：1727269943
ThreadIDString会话 ID 示例值：thread_OteLtAcmh7prn7tb8uQ3SJzh
StatusString状态，处理中 in_progress，已完成 completed，未完成 incomplete。 示例值：completed
InCompleteDetailsThreadMessageInCompleteDetailsObject未完成原因 注意：此字段可能返回 null，表示取不到有效值。 示例值：{"Reason": ""}
CompletedAtInteger完成时间 注意：此字段可能返回 null，表示取不到有效值。 示例值：1727264847
InCompleteAtInteger未完成时间 注意：此字段可能返回 null，表示取不到有效值。 示例值：1727264847
RoleString角色 示例值：user
ContentString内容 示例值：你好
AssistantIDString助手 ID 注意：此字段可能返回 null，表示取不到有效值。 示例值：asst_LhSU47qcQcFEItggpGEx5eh1
RunIDString运行 ID 注意：此字段可能返回 null，表示取不到有效值。 示例值：run_SR0cPyidY0vBWy7mcYN5loSR
AttachmentsArray of ThreadMessageAttachmentObject附件 注意：此字段可能返回 null，表示取不到有效值。 示例值：[{"FileID":"file-tMjt0CQnvU25GwUDkih4tU4H"}]

ThreadMessageAttachmentObject#

会话消息附件
被如下接口引用：GetThreadMessage, GetThreadMessageList, RunThread。
名称类型必选描述
FileIDString否文件 ID 注意：此字段可能返回 null，表示取不到有效值。 示例值：file-tMjt0CQnvU25GwUDkih4tU4H

ThreadMessageInCompleteDetailsObject#

会话消息未完成原因
被如下接口引用：GetThreadMessage, GetThreadMessageList。
名称类型描述
ReasonString会话消息未完成原因

ThreadToolResources#

在会话中提供给助手工具的一系列资源。不同类型的工具会有各自对应的资源。比如代码解释器需要一个文件 ID 的列表，而文件搜索工具则需要一个向量存储 ID 的列表。
被如下接口引用：CreateThread, GetThread。
名称类型必选描述
CodeInterpreterArray of String否文件 ID 列表 示例值：["file-tZ0lWeNW4oNbEiMYGtOXEmEk"]
VectorStoreIDsArray of String否向量存储 ID 列表 示例值：["vs_ uf4c5hAL9GosVbmJ4jSUVivy"]

Timeline#

时间线
被如下接口引用：ChatCompletions。
名称类型必选描述
TitleString否标题 注意：此字段可能返回 null，表示取不到有效值。
DatetimeString否时间 注意：此字段可能返回 null，表示取不到有效值。
UrlString否相关网页链接 注意：此字段可能返回 null，表示取不到有效值。

Tool#

用户指定模型使用的工具
被如下接口引用：ChatCompletions, RunThread。
名称类型必选描述
TypeString是工具类型，当前只支持function 示例值：function
FunctionToolFunction是具体要调用的function

ToolCall#

模型生成的工具调用
被如下接口引用：ChatCompletions。
名称类型必选描述
IdString是工具调用id 示例值：call_cpv320k2c3m8fgcs8ja0
TypeString是工具调用类型，当前只支持function 示例值：function
FunctionToolCallFunction是具体的function调用
IndexInteger否索引值 示例值：0

ToolCallFunction#

具体的function调用
被如下接口引用：ChatCompletions。
名称类型必选描述
NameString是function名称 示例值：get_current_weather
ArgumentsString是function参数，一般为json字符串 示例值：{"location":["北京","深圳"],"unit":"celsius"}

ToolFunction#

function定义
被如下接口引用：ChatCompletions, RunThread。
名称类型必选描述
NameString是function名称，只能包含a-z，A-Z，0-9，_或- 示例值：get_current_weather
ParametersString是function参数，一般为json字符串
DescriptionString否function的简单描述 示例值：获取当前地点的天气

TranslationChoice#

翻译接口返回的回复，支持多个
被如下接口引用：ChatTranslations。
名称类型描述
FinishReasonString结束标志位，可能为 stop、 sensitive。 stop 表示输出正常结束。 sensitive 只在开启流式输出审核时会出现，表示安全审核未通过。 示例值：stop
IndexInteger索引值，流式调用时使用该字段。 示例值：0
DeltaTranslationDelta增量返回值，流式调用时使用该字段。
MessageTranslationMessage返回值，非流式调用时使用该字段。

TranslationDelta#

翻译接口返回的内容（流式返回）
被如下接口引用：ChatTranslations。
名称类型描述
RoleString角色名称。 示例值：assistant
ContentString内容详情。 示例值：你好！请问有什么我可以帮助你的吗？

TranslationMessage#

翻译接口会话内容
被如下接口引用：ChatTranslations。
名称类型描述
RoleString角色，可选值包括 system、user、assistant、 tool。 示例值：user
ContentString文本内容 示例值：你好！

Usage#

Token 数量
被如下接口引用：ChatCompletions, ChatTranslations。
名称类型描述
PromptTokensInteger输入 Token 数量。 示例值：8
CompletionTokensInteger输出 Token 数量。 示例值：20
TotalTokensInteger总 Token 数量。 示例值：28
修改于 2025-03-05 10:28:50
上一页
设置付费模式
下一页
错误码
Built with