视频转文字

通过 Gemini 原生 generateContent 接口上传视频，让模型完成语音转录、画面描述、带时间戳的内容提取和视频问答，一次请求返回完整结果。gemini-3.8-flash 能同时理解视频里的画面和音频，可以按 MM:SS 时间戳输出转录内容，也支持截取片段、调整抽帧率来控制 token 消耗。

官方文档：https://ai.google.dev/gemini-api/docs/video-understanding?hl=zh-cn

⚠️ 注意事项

所有字段名必须用 camelCase（如 inlineData、videoMetadata、startOffset）。写成 snake_case（如 video_metadata）不会报错，但参数会被静默忽略，YouTube 的 file_data 写法会直接返回 400。

maxOutputTokens、temperature、mediaResolution 必须放在 generationConfig 下，thinkingLevel 必须放在 generationConfig.thinkingConfig 下。放在根节点不报错，但不生效。

本网关暂不支持 File API 上传（/upload/v1beta/files），视频只能通过 inlineData（Base64 内联）或 fileData（YouTube 链接）传入。

thinkingLevel 传 MINIMAL 时偶尔会返回：Thinking level is unsupported: THINKING_LEVEL_MINIMAL，建议用 LOW。

视频请求耗时波动大（实测 7 秒到 200 秒以上都有），客户端超时建议设为 300 秒以上，并加重试。

请避免上传包含以下内容的视频：

未成年人相关的不当内容、色情或性暗示内容

血腥暴力、恐怖主义、武器制作、违法犯罪过程

自残、自杀等可能造成现实伤害的内容

针对个人或群体的仇恨、骚扰、威胁内容

含有他人隐私信息（证件、银行卡、病历等）的画面

否则接口可能拒绝处理，或返回 finishReason: SAFETY

🎯 关键提示

视频传入方式（二选一）：

inlineData：Base64 内联，适合小文件。data 只填编码本身，不要带 data:video/mp4;base64, 前缀

fileData.fileUri：YouTube 链接，仅支持公开视频

mimeType 支持 video/mp4 / video/mpeg / video/mov / video/avi / video/x-flv / video/mpg / video/webm / video/wmv / video/3gpp，必须和实际文件格式一致

videoMetadata 必须和视频放在同一个 part 里，单独放一个 part 不生效：

startOffset / endOffset：截取片段，格式为 "10s"。截取后只对片段内的画面和音频计费

fps：抽帧率，默认 1，必须大于 0。token 与帧数成正比，以 20 秒视频为例：

0.2：约 264 视频 token，适合 PPT 录屏、讲座等画面静态的长视频

1：约 1320 视频 token，日常档

5：约 6600 视频 token，适合运动、操作演示等画面变化快的视频

mediaResolution 控制每帧的精细度，档位差异如下：

默认 / LOW / MEDIUM：约 66 token/帧，三者实测一致

HIGH：约 264 token/帧，是默认的 4 倍，适合识别字幕、小字、细节

音频单独计费，约 25 token/秒（20 秒约 500 token）。响应中有时会把音频 token 合并到 VIDEO 一起统计。

💡 实用提示

转录指令建议写清楚输出格式，例如「转录视频中的语音并标注 MM:SS 时间戳，同时按时间戳描述画面」。

可以在 text 中直接用 MM:SS 引用时间点提问，例如「00:15 时画面上显示了什么」。

建议在指令中加一句「没有语音时请明确说明」，防止模型对静音片段编造语音内容。

长视频优先调低 fps 节省 token；需要识别画面中的文字时，再用 MEDIA_RESOLUTION_HIGH。

长视频的完整转录文本较长，maxOutputTokens 要设得充足（如 8192 以上）。思考 token 也计入上限，超出时 finishReason 为 MAX_TOKENS。

普通转录任务 thinkingLevel 用 LOW 即可，HIGH 会明显增加耗时和 token 消耗。

多轮追问时，把模型上一轮的回复用 role: model 回传，role 只接受 user / model。

鉴权 Authorization: sk-xxx 和 Authorization: Bearer sk-xxx 两种写法都可以。

请求参数

Path 参数

Query 参数

Header 参数

Body 参数application/json必填

示例

{
    "contents": [
        {
            "role": "user",
            "parts": [
                {
                    "inlineData": {
                        "mimeType": "video/mp4",
                        "data": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1wNDEAAAAIZnJlZQ..."
                    },
                    "videoMetadata": {
                        "startOffset": "0s",
                        "endOffset": "20s",
                        "fps": 1
                    }
                },
                {
                    "text": "转录视频中的语音并标注 MM:SS 时间戳，同时按时间戳描述画面内容。没有语音时请明确说明。"
                }
            ]
        }
    ],
    "generationConfig": {
        "maxOutputTokens": 8192,
        "temperature": 0.2,
        "mediaResolution": "MEDIA_RESOLUTION_LOW",
        "thinkingConfig": {
            "thinkingLevel": "LOW"
        }
    }
}

请求示例代码

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

请求参数

请求示例代码

返回响应