VITA API接入指南：兼容OpenAI协议，5分钟快速上手

摘要：

本文详细介绍VITA API的接入方法，包括接口信息、请求参数、返回参数、调用示例，帮助开发者快速上手VITA多模态理解服务。

一、前言

VITA API兼容OpenAI API协议，开发者可直接使用OpenAI SDK进行接入，降低接入成本。无论你是AI应用开发者、内容平台运营者，还是企业技术团队，都可以通过本文快速了解VITA API的接入方法。

二、接入前准备

2.1 步骤1：登录腾讯云控制台

访问腾讯云控制台：https://console.cloud.tencent.com/

2.2 步骤2：进入腾讯云TokenHub平台

在控制台中进入"腾讯云TokenHub平台"，或直接访问：https://console.cloud.tencent.com/tokenhub

2.3 步骤3：创建API密钥

在TokenHub平台创建API密钥（每个账号赠送100万免费Token额度）。

说明： 每个账号赠送100万免费Token额度，可用于测试VITA的各项能力。

2.4 步骤4：选择合适的模型

VITA提供以下两个可用模型，用户可根据是否需要处理音频选择合适的模型。

模型选择建议：

• 如果不需要处理音频，优先选择vita-video-3.0
• 如果需要处理音频，选择vita-video-long

腾讯云TokenHub平台模型名称：

在腾讯云TokenHub平台上，VITA模型的调用名称为youtu-vita，与vita-video-3.0/vita-video-long等价。

三、API接口信息

3.1 基础信息

完整URL：

https://tokenhub.tencentmaas.com/v1/chat/completions

3.2 服务ID说明

1. 平台默认创建的服务：服务ID与模型名称相同，例如youtu-vita
2. 用户自定义服务：服务ID格式为ep-xxxxxxxx，可在在线推理服务页面查看

四、请求参数说明

4.1 顶层参数

4.2 messages参数说明

4.3 content参数说明

4.4 image_url对象

4.5 video_url对象

五、返回参数说明

5.1 顶层参数

5.2 choices数组元素

5.3 usage对象

六、调用示例

6.1 示例1：输入为视频

使用场景： 需要对视频内容进行理解分析。

curl命令：

curl -X POST 'https://tokenhub.tencentmaas.com/v1/chat/completions' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "vita-video-long",
    "messages": [{"role": "user", "content": [
      {"type": "video_url", "video_url": {"url": "<video url>"}},
      {"type": "text", "text": "请描述视频的内容"}
    ]}],
    "stream": false
  }'

说明： 如果视频不含音频，建议使用vita-video-3.0模型。

6.2 示例2：输入为图片

使用场景： 需要对图片内容进行理解分析。

curl命令：

curl -X POST 'https://tokenhub.tencentmaas.com/v1/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 1>"}},
      {"type": "image_url", "image_url": {"url": "<image url 2>"}}, 
      {"type": "text", "text": "请描述图片的内容"}
    ]}],
    "stream": false
  }'

说明： 对于图片理解任务，推荐使用vita-video-3.0模型（不含音频处理，成本更低）。

6.3 示例3：使用OpenAI SDK接入

使用场景： 已熟悉OpenAI SDK的开发者，可直接使用OpenAI SDK接入VITA API。

Python代码：

from openai import OpenAI

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

response = client.chat.completions.create(
    model="vita-video-long",  # 如需处理音频，使用vita-video-long；如不需处理音频，使用vita-video-3.0
    messages=[{"role": "user", "content": [
        {"type": "video_url", "video_url": {"url": "<video url>"}},
        {"type": "text", "text": "请描述视频的内容"}
    ]}],
    stream=False
)

print(response.choices[0].message.content)

优势： 兼容OpenAI API协议，可直接使用OpenAI SDK进行接入，降低接入成本。

七、定价与免费试用

7.1 定价规则

定价特点：

• 显著的成本优势
• 基于纯自研轻量级Youtu-LLM底座，在保障卓越效果的同时大幅降低算力成本
• 实现效果与成本的精准平衡
• 在能力水平与市面同类产品相近的情况下，整体定价约为主流竞品的50%

7.2 Token消耗规则

计算公式

总Token消耗 = 指令token消耗 + 图片数向上取偶 × 单图token消耗

说明：

• 指令token即对应的prompt部分，不同长度prompt消耗不一样
• 图片数向上取偶：例如3张图片按4张计算，5张图片按6张计算

不同分辨率对应的单图token消耗

7.3 免费试用

• 每个账号赠送100万免费Token额度（新开通服务限时赠送）
• 可通过腾讯云TokenHub平台快速体验

八、最佳实践

8.1 Prompt编写建议

1. 明确具体：尽量使用明确、具体的指令，避免模糊表述
2. 格式要求：需要输出特定格式时在指令中明确说明
3. 任务分解：对于复杂任务，可分解为多个简单任务逐步完成
4. 示例引导：在Prompt中提供示例，帮助模型理解任务要求

8.2 输入素材准备

1. 视频时长：控制在30min以内，避免幻觉
2. 视频大小：默认不超过100MB，特殊情况下（白名单）可支持最大600MB
3. 图片质量：确保图片清晰，关键信息可见
4. 音频质量：确保音频清晰，无严重噪音

8.3 结果校验

1. 关键信息核验：对于关键信息，建议进行人工核验
2. 边界测试：对于边界场景，建议进行充分测试
3. 批量测试：对于批量处理场景，建议先进行小批量测试

8.4 成本优化建议

1. 选择合适的图片分辨率：根据任务需求选择合适的图片分辨率，降低Token消耗
2. 优化Prompt长度：精简Prompt，降低指令Token消耗
3. 批量处理规划：合理规划批量处理任务，避免重复调用
4. 使用流式输出：对于长时间任务，使用流式输出提升用户体验

九、常见问题解答

9.1 技术类问题

Q1：VITA支持哪些文件格式？

A1：

• 图片：JPG、JPEG、PNG、WebP，单图最大10MB，一次请求最多10张
• 视频：MP4、MOV、AVI、WebM，编码H.264/H.265，时长建议控制在30分钟以内，文件大小默认最大100MB，特殊情况下（白名单）可支持最大600MB，一次请求仅支持1个视频

Q2：VITA的响应时间是多少？

A2：

• 图片首Token时延：P95 0.539s
• 视频首Token时延：P95 2.471s

Q3：VITA是否支持实时处理？

A3：当前版本不支持实时视频流的直接处理，需要通过预先录制后批量上传的方式提交任务。

Q4：VITA的模型名称是什么？

A4：VITA提供以下两个可用模型：

• vita-video-3.0：支持视频画面（不含音频）和图片，若不需要处理音频，首推该模型
• vita-video-long：支持视频（含画面和音频）和图片，需要处理音频则选择该模型

说明： 在腾讯云TokenHub平台上，模型名称也可使用youtu-vita，与vita-video-3.0/vita-video-long等价。

9.2 接入类问题

Q1：如何获取API密钥？

A1：需登录腾讯云TokenHub平台控制台，创建API密钥。每个账号赠送100万免费Token额度。

Q2：VITA是否兼容OpenAI API协议？

A2：是的，VITA API兼容OpenAI API协议，可直接使用OpenAI SDK进行接入。

9.3 计费类问题

Q1：VITA如何计费？

A1：VITA按Token消耗量进行计费：

• 输入：1.2元/百万Token
• 输出：3.5元/百万Token

Q2：VITA有免费试用吗？

A2：每个账号赠送100万免费Token额度。也可访问腾讯云官网VITA产品页或活动页查询最新优惠活动信息。

Q3：如何降低VITA的使用成本？

A3：

1. 选择合适的图片分辨率：根据任务需求选择合适的图片分辨率，降低Token消耗
2. 优化Prompt长度：精简Prompt，降低指令Token消耗
3. 合理规划调用频率，避免超出限额
4. 对于批量处理场景，先进行小批量测试

VITA API兼容OpenAI API协议，开发者可直接使用OpenAI SDK进行接入，降低接入成本。通过本文的介绍，相信你已经了解了VITA API的接入方法、请求参数、返回参数、调用示例等关键信息。

了解更多产品详情并免费体验：https://console.cloud.tencent.com/tokenhub/multimodal?modelId=youtu-vita