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

多模态理解模型 VITA 接口兼容 OpenAI Completions API 协议，您可以直接使用 OpenAI SDK 或任何兼容客户端接入。
接口信息
请求地址：https://api.vita.cloud.tencent.com/v1/video2text/chat/completions
请求方式：POST
Content-Type：application/json
默认并发：5并发
支持的内容形态：图片、图片+文本、视频、音频
请求参数
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": "这段视频展示了一个动画场景，背景设定在一个宁静的户外环境中。视频中有一个穿着冬季服装的蓝发女孩，她戴着毛线帽和围巾，看起来非常保暖。她的表情从惊讶到得意再到震惊，显示出情绪的波动。\n\n场景开始时，女孩站在一片开阔的空地上，周围是秋天的树木，树叶呈现出丰富的橙色和黄色。远处可以看到连绵的山脉，天空晴朗，云朵稀疏。\n\n接着，画面切换到两只可爱的柴犬，它们似乎在进行某种互动或游戏。随后，镜头回到女孩身上，她正牵着其中一只狗，而另一只狗在旁边跳跃。\n\n随着情节的发展，女孩被狗拉着向前跑，显得有些吃力。最后，画面模糊，暗示着快速移动或转场。\n\n整个视频充满了轻松愉快的氛围，背景音乐可能是轻快的，与画面的动态相得益彰。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 11716,
    "completion_tokens": 171,
    "total_tokens": 11887,
    "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": "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": "这段视频展示了一个动画场景，背景设定在一个宁静的户外环境中。视频中有一个穿着冬季服装的蓝发女孩，她戴着毛线帽和围巾，看起来非常保暖。她的表情从惊讶到得意再到震惊，显示出情绪的波动。\n\n场景开始时，女孩站在一片开阔的空地上，周围是秋天的树木，树叶呈现出丰富的橙色和黄色。远处可以看到连绵的山脉，天空晴朗，云朵稀疏。\n\n接着，画面切换到两只可爱的柴犬，它们似乎在进行某种互动或游戏。随后，镜头回到女孩身上，她正牵着其中一只狗，而另一只狗在旁边跳跃。\n\n随着情节的发展，女孩被狗拉着向前跑，显得有些吃力。最后，画面模糊，暗示着快速移动或转场。\n\n整个视频充满了轻松愉快的氛围，背景音乐可能是轻快的，与画面的动态相得益彰。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 11716,
    "completion_tokens": 171,
    "total_tokens": 11887,
    "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 对象

调用示例

示例1：图片内容识别

请求示例

返回示例

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

请求示例

返回示例

示例3：视频内容识别

请求示例

返回示例

示例4：音频内容识别

请求示例

返回示例

﻿
