图像识别多模态理解调用方式

多模态理解模型 VITA 接口兼容 OpenAI Completions API 协议，您可以直接使用 OpenAI SDK 或任何兼容客户端接入。
本服务提供两个接口模式：
应用场景模式（主推）：搭配 控制台 使用，基于控制台里配置好的规则，传入“规则 ID”即可实现对应的理解任务。
自定义 Prompt 模式：在接口中直接输入 Prompt，和常见的大模型调用方式一致，需要自己在代码中维护 Prompt。
应用场景模式
接口信息
请求地址：https://api.vita.cloud.tencent.com/v1/video2text/rule/chat/completions
请求方式：POST
Content-Type：application/json
TPM 限制：100万
支持的内容形态：图片、视频、音频
请求参数
Header 参数
参数名
类型
必填
描述
Authorization
string
是
格式：Bearer {token}。
在 产品控制台 的 VITA 图像理解 - 服务管理 页面创建和获取 API KEY 的值并填入。
Content-Type
string
是
请求体类型，固定值：application/json
Accept
string
否
接受的响应类型，默认：*/*
Connection
string
否
连接方式，建议：keep-alive
Body 参数
参数名
类型
必填
描述
model
String
是
调用的模型参数，取值范围：vita-video-3.0。
推荐值：vita-video-3.0
rule_id
String
是
规则 ID，该值在 控制台 中各场景里的“规则管理”页面里获取。
说明：
使用 OpenAI SDK 接入时，rule_id 字段在 extra_body 中传入。
messages
Array
是
需要理解的内容，详细信息请参见 messages 参数说明。
stream
Boolean
否
是否启用流式输出，取值范围：true / false。
默认值：false。
temperature
Float
否
温度参数，控制模型的输出答案的变化性：
数值越高，输出越多样化，同一个问题可能会有不同的答案；
数值越低，输出越确定，同一个问题每次几乎都一样
取值范围：[0.0, 2.0]
top_k
Int
否
前置知识：大模型每一步生成文字时，会算出所有候选字 / 词（token） 的概率，概率越高越容易被选中。top_k、top_p 都是用来缩小候选词范围。
top_k 是不管剩下的词概率多低，只保留排名前 k 高概率的候选词，其余全部直接删掉，不给模型选。举个例子：
假设所有词概率排序：苹果 (40%)、香蕉 (30%)、橙子 (15%)、葡萄 (10%)、西瓜 (5%)
top_k=2：只保留苹果、香蕉，橙子 / 葡萄 / 西瓜直接淘汰
top_k=4：保留苹果、香蕉、橙子、葡萄
取值范围：0表示不限制，其它取值请输入正整数，建议40以上
top_p
Float
否
top_p 是不固定数量，从概率最高的词开始累加，直到总概率达到 p，剩下的全部丢弃。
延续 top_k 的例子：
假设苹果 40%+ 香蕉 30%=70%，橙子 15% 累加后 85%，葡萄 10% 累加 95%
top_p=0.7：总和到 70% 停下，只保留苹果、香蕉
top_p=0.9：总和到 95% 停下，保留苹果、香蕉、橙子、葡萄
取值范围：[0.0, 1.0]
frequency_penalty
Float
否
存在惩罚：只要词出现过一次，后续全程持续扣分，侧重少提冷门词、别反复纠缠同一个概念
取值范围：[-2.0, 2.0]
presence_penalty
Float
否
频率惩罚：词出现次数越多，扣的分越多，侧重不要高频复读同一个词
取值范围：[-2.0, 2.0]，若出现结果复读可尝试设置该值为1.0
repetition_penalty
Float
否
重复惩罚：专门打压连续重复、短句循环、整段套话和叠词，是范围最广、力度最强的重复抑制参数。
取值范围：[0.0, 2.0]，若出现结果复读可尝试设置该值为1.5
max_tokens
Int
否
限制一次请求中，输入和输出加起来的最大 token 数
max_completion_tokens
Int
否
限制模型在一次生成中，最多输出多少个 token（只控制模型生成的内容的长度，不包括输入 prompt 部分）
messages 参数说明
参数名
类型
必填
描述
role
String
是
输入值：user
content
Array
是
需要理解的内容，支持图片、视频、音频，详情参见 content 参数。
content 参数说明
参数名
类型
必填
描述
type
String
是
输入类型：image_url, video_url, audio_url，一次调用仅支持一种类型
image_url
Object
否
需要做理解的图片信息，type 传入 image_url 时需指定，详情请参见 image_url 对象。
video_url
Object
否
需要做理解的视频信息，type 传入 video_url 时需指定，详情请参见 video_url 对象。
audio_url
Object
否
需要做理解的音频信息，type 传入 audio_url 时需指定，详情请参见 audio_url 对象。
参数限制说明：
type 互斥规则：单次调用 content 仅允许包含一种 type 类型，即 image_url、video_url 或 audio_url。不同 type 类型禁止混合传入，如指定 image_url 后，不可再传入 video_url。
数量限制规则：image_url 和 audio_url 类型支持一次传如多个 url；video_url 类型一次仅支持传一个 url。
image_url 对象
参数名
类型
必填
描述
url
String
是
图片 URL 链接。格式要求如下：
封装格式：JPG、JPEG、PNG、WebP
文件大小：单图最大10MB，一次请求最多10张图片。
video_url 对象
参数名
类型
必填
描述
url
String
是
视频 URL 链接。格式要求如下：
封装格式：MP4、MOV、AVI、WebM
编码格式：H.264、H.265
文件大小：时长最长 10 分钟，文件大小最大 100MB，一次请求仅1个视频。
audio_url 对象
参数名
类型
必填
描述
url
String
是
音频 URL 链接。格式要求如下：
封装格式：MP3、RAW
文件大小：建议时长 5 分钟以内
返回参数
参数名
类型
描述
id
String
请求唯一标识，32位十六进制字符串。
object
String
对象类型固定 chat.completion。
created
Integer
创建时间（Unix 时间戳）。
model
String
实际使用的模型名称，如 vita-video-3.0
choices
Array
模型针对同一次请求返回的候选结果列表，详情请参见 choices 数组元素。
usage
Object
详情请参见 usage 对象。
choices 数组元素
参数名
类型
描述
index
Integer
选项索引。
message
Object
回复消息，包含 role 和 content。
finish_reason
String
结束原因：stop（正常结束）、length（达到最大长度）、tool_calls（需要调用工具）
usage 对象
参数名
类型
描述
prompt_tokens
Integer
输入 Token 数
completion_tokens
Integer
输出 Token 数
total_tokens
Integer
总 Token 数
调用示例
请求示例
# 本示例展示了一次请求，输入多个url
# 注意：image_url和audio_url类型支持一次输入多个url；video_url类型一次仅支持传一个url。
curl -X POST 'https://api.vita.cloud.tencent.com/v1/video2text/rule/chat/completions' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "vita-video-3.0",
    "rule_id": "bcast_s_preset_00000001",
    "scene_id": "bcast",
    "messages": [{"role": "user", "content": [
      {"type": "image_url", "image_url": {"url": "<image url 1>"}},
      {"type": "image_url", "image_url": {"url": "<image url 2>"}}
    ]}],
    "stream": false
  }'
返回示例
{
  "id": "0618112664aa56bbfed859db699a1972",
  "object": "chat.completion",
  "created": 1779184723,
  "model": "vita-video-3.0",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "这组图片是一个商品的各方面展示……"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 1171,
    "completion_tokens": 101,
    "total_tokens": 1272,
    "prompt_tokens_details": {
      "cached_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0
    }
  }
}
自定义 Prompt 模式
接口信息
请求地址：https://api.vita.cloud.tencent.com/v1/video2text/chat/completions
请求方式：POST
Content-Type：application/json
TPM 限制：100万
支持的内容形态：图片、图片+文本、视频、视频+文本、音频、音频+文本
请求参数
Header 参数
参数名
类型
必填
描述
Authorization
string
是
格式：Bearer {token}。
在 产品控制台 的 VITA 图像理解 - 服务管理 页面创建和获取 API KEY 的值并填入。
Content-Type
string
是
请求体类型，固定值：application/json
Accept
string
否
接受的响应类型，默认：*/*
Connection
string
否
连接方式，建议：keep-alive
Body 参数
参数名
类型
必填
描述
model
String
是
调用的模型参数，取值范围：vita-video-3.0 / vita-video-long。
推荐值：vita-video-3.0
messages
Array
是
需要理解的内容，详细信息请参见 messages 参数说明。
stream
Boolean
否
是否启用流式输出，取值范围：true / false。
默认值：false。
temperature
Float
否
温度参数，控制模型的输出答案的变化性：
数值越高，输出越多样化，同一个问题可能会有不同的答案；
数值越低，输出越确定，同一个问题每次几乎都一样
取值范围：[0.0, 2.0]
top_k
Int
否
前置知识：大模型每一步生成文字时，会算出所有候选字 / 词（token） 的概率，概率越高越容易被选中。top_k、top_p 都是用来缩小候选词范围。
top_k 是不管剩下的词概率多低，只保留排名前 k 高概率的候选词，其余全部直接删掉，不给模型选。举个例子：
假设所有词概率排序：苹果 (40%)、香蕉 (30%)、橙子 (15%)、葡萄 (10%)、西瓜 (5%)
top_k=2：只保留苹果、香蕉，橙子 / 葡萄 / 西瓜直接淘汰
top_k=4：保留苹果、香蕉、橙子、葡萄
取值范围：0表示不限制，其它取值请输入正整数，建议40以上
top_p
Float
否
top_p 是不固定数量，从概率最高的词开始累加，直到总概率达到 p，剩下的全部丢弃。
延续 top_k 的例子：
假设苹果 40%+ 香蕉 30%=70%，橙子 15% 累加后 85%，葡萄 10% 累加 95%
top_p=0.7：总和到 70% 停下，只保留苹果、香蕉
top_p=0.9：总和到 95% 停下，保留苹果、香蕉、橙子、葡萄
取值范围：[0.0, 1.0]
frequency_penalty
Float
否
存在惩罚：只要词出现过一次，后续全程持续扣分，侧重少提冷门词、别反复纠缠同一个概念
取值范围：[-2.0, 2.0]
presence_penalty
Float
否
频率惩罚：词出现次数越多，扣的分越多，侧重不要高频复读同一个词
取值范围：[-2.0, 2.0]，若出现结果复读可尝试设置该值为1.0
repetition_penalty
Float
否
重复惩罚：专门打压连续重复、短句循环、整段套话和叠词，是范围最广、力度最强的重复抑制参数。
取值范围：[0.0, 2.0]，若出现结果复读可尝试设置该值为1.5
max_tokens
Int
否
限制一次请求中，输入和输出加起来的最大 token 数
max_completion_tokens
Int
否
限制模型在一次生成中，最多输出多少个 token（只控制模型生成的内容的长度，不包括输入 prompt 部分）
messages 参数说明
参数名
类型
必填
描述
role
String
是
输入值：user
content
Array
是
需要理解的内容，支持图片和视频，详情参见 content 参数说明。
content 参数说明
参数名
类型
必填
描述
type
String
是
输入类型：text, image_url, video_url, audio_url
text
String
是
自定义的理解指令，例如：请描述图片的内容。
image_url
Object
否
需要做理解的图片信息，type 传入 image_url 时需指定，详情请参见 image_url 对象。
video_url
Object
否
需要做理解的视频信息，type 传入 video_url 时需指定，详情请参见 video_url 对象。
audio_url
Object
否
需要做理解的音频信息，type 传入 audio_url 时需指定，详情请参见 audio_url 对象。
image_url 对象
参数名
类型
必填
描述
url
String
是
图片 URL 链接。格式要求如下：
封装格式：JPG、JPEG、PNG、WebP
文件大小：单图最大10MB，一次请求最多10张图片。
video_url 对象
参数名
类型
必填
描述
url
String
是
视频 URL 链接。格式要求如下：
封装格式：MP4、MOV、AVI、WebM
编码格式：H.264、H.265
文件大小：时长最长 10 分钟，文件大小最大 100MB，一次请求仅1个视频。
audio_url 对象
参数名
类型
必填
描述
url
String
是
音频 URL 链接。格式要求如下：
封装格式：MP3、RAW
文件大小：建议时长 5 分钟以内
返回参数
参数名
类型
描述
id
String
请求唯一标识，32位十六进制字符串。
object
String
对象类型固定 chat.completion。
created
Integer
创建时间（Unix 时间戳）。
model
String
实际使用的模型名称，如 vita-video-3.0
choices
Array
模型针对同一次请求返回的候选结果列表，详情请参见 choices 数组元素。
usage
Object
详情请参见 usage 对象。
choices 数组元素
参数名
类型
描述
index
Integer
选项索引。
message
Object
回复消息，包含 role 和 content。
finish_reason
String
结束原因：stop（正常结束）、length（达到最大长度）、tool_calls（需要调用工具）
usage 对象
参数名
类型
描述
prompt_tokens
Integer
输入 Token 数
completion_tokens
Integer
输出 Token 数
total_tokens
Integer
总 Token 数
调用示例
示例1：图片内容识别
请求示例
curl -X POST 'https://api.vita.cloud.tencent.com/v1/video2text/chat/completions' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "vita-video-3.0",
    "messages": [{"role": "user", "content": [
      {"type": "image_url", "image_url": {"url": "<image url>"}},
      {"type": "text", "text": "请描述图片的内容"}
    ]}],
    "stream": false
  }'
返回示例
{
  "id": "0618112664aa56bbfed859db699a1972",
  "object": "chat.completion",
  "created": 1779184723,
  "model": "vita-video-3.0",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "这张图片中有一个穿着冬季服装的蓝发女孩，……"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 1171,
    "completion_tokens": 101,
    "total_tokens": 1272,
    "prompt_tokens_details": {
      "cached_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0
    }
  }
}
示例2：图片+文本联合识别
请求示例
curl -X POST 'https://api.vita.cloud.tencent.com/v1/video2text/chat/completions' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "vita-video-3.0",
    "messages": [{"role": "user", "content": [
      {"type": "image_url", "image_url": {"url": "<image url>"}},
      {"type": "text", "text": "这个口红真好用"},
      {"type": "text", "text": "你会收到一张图片和一段文本的内容，现在的任务是判断两者的内容是否有关联关系"}
    ]}],
    "stream": false
  }'
返回示例
{
  "id": "0618112664aa56bbfed859db699a1972",
  "object": "chat.completion",
  "created": 1779184723,
  "model": "vita-video-3.0",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "图片和文本的内容是有关联关系的：图片展示了口红的外挂以及用户的使用效果，文本是用户对该口红的评价"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 1171,
    "completion_tokens": 101,
    "total_tokens": 1272,
    "prompt_tokens_details": {
      "cached_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0
    }
  }
}
示例3：视频内容识别
请求示例
curl -X POST 'https://api.vita.cloud.tencent.com/v1/video2text/chat/completions' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "vita-video-3.0",
    "messages": [{"role": "user", "content": [
      {"type": "video_url", "video_url": {"url": "<video url>"}},
      {"type": "text", "text": "请描述视频的内容"}
    ]}],
    "stream": false
  }'
返回示例
{
  "id": "0618112664aa56bbfed859db699a1871",
  "object": "chat.completion",
  "created": 1779184730,
  "model": "vita-video-3.0",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "这段视频展示了一个动画场景，背景设定在一个宁静的户外环境中……"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 2171,
    "completion_tokens": 171,
    "total_tokens": 887,
    "prompt_tokens_details": {
      "cached_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0
    }
  }
}
示例4：音频内容识别
请求示例
curl -X POST 'https://api.vita.cloud.tencent.com/v1/video2text/chat/completions' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "vita-video-3.0",
    "messages": [{"role": "user", "content": [
      {"type": "audio_url", "audio_url": {"url": "<audio url>"}},
      {"type": "text", "text": "请描述音频的内容"}
    ]}],
    "stream": false
  }'
返回示例
{
  "id": "0618112664aa56bbfed859db699a1871",
  "object": "chat.completion",
  "created": 1779184730,
  "model": "vita-video-3.0",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "这段音频讲述了一个民生新闻事件……"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 1171,
    "completion_tokens": 171,
    "total_tokens": 2188,
    "prompt_tokens_details": {
      "cached_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0
    }
  }
}
﻿
参数名	类型	必填	描述
Authorization	string	是	格式：Bearer {token}。在产品控制台的 VITA 图像理解 - 服务管理页面创建和获取 API KEY 的值并填入。
Content-Type	string	是	请求体类型，固定值：application/json
Accept	string	否	接受的响应类型，默认：/
Connection	string	否	连接方式，建议：keep-alive
多模态理解调用方式

本页目录：

应用场景模式

接口信息

请求参数

Header 参数

Body 参数

messages 参数说明

content 参数说明

image_url 对象

video_url 对象

audio_url 对象

返回参数

choices 数组元素

usage 对象

调用示例

自定义 Prompt 模式

接口信息

请求参数

Header 参数

Body 参数

messages 参数说明

content 参数说明

image_url 对象

video_url 对象

audio_url 对象

返回参数

choices 数组元素

usage 对象

调用示例

示例1：图片内容识别

示例2：图片+文本联合识别

示例3：视频内容识别

示例4：音频内容识别

﻿
