> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 同步调用 API

> VEO 3.1 同步调用接口，适合实时交互场景

<Warning>
  开始前，请注册 API易，获取 API 密钥 [https://api.apiyi.com/token](https://api.apiyi.com/token)  (复制令牌)
</Warning>

## 同步调用说明

VEO 3.1 支持同步调用方式，使用对话补全接口 `/v1/chat/completions`，适合需要实时交互的场景。

<Info>
  **调用方式对比：**

  * **同步调用**：适合实时交互，支持流式输出，可以看到生成进度
  * **异步调用**：适合批量处理，提交任务后轮询获取结果，详见 [异步调用 API](/api-capabilities/veo/async-api)
</Info>

## 快速开始

<Steps>
  <Step title="准备 API 密钥">
    前往 [API易控制台](https://api.apiyi.com/account/profile) 获取 API 密钥
  </Step>

  <Step title="发送请求">
    使用对话补全接口生成视频，支持流式和非流式两种方式
  </Step>

  <Step title="获取结果">
    实时获取生成进度和视频链接
  </Step>
</Steps>

## 认证方式

所有 API 请求都需要在请求头中包含 API 密钥：

```bash theme={null}
Authorization: sk-your-api-key
```

<Tip>
  **安全提醒：** 请勿在客户端代码中暴露 API 密钥。建议在服务端环境变量中存储。
</Tip>

## 示例 1：文生视频

最简单的方式，使用文本描述生成视频：

```bash theme={null}
curl --location --request POST 'https://api.apiyi.com/v1/chat/completions' \
--header 'Content-Type: application/json' \
--header 'Authorization: sk-your-api-key' \
--data-raw '{
    "messages": [{"role": "user", "content": "画只猪在天上飞"}],
    "model": "veo-3.1",
    "stream": true,
    "n": 2
}'
```

### 参数说明

| 参数         | 类型      | 必填 | 说明                  |
| ---------- | ------- | -- | ------------------- |
| `messages` | array   | 是  | 对话消息数组，包含用户的提示词     |
| `model`    | string  | 是  | 使用的模型名称，如 `veo-3.1` |
| `stream`   | boolean | 否  | 是否开启流式输出，默认 false   |
| `n`        | integer | 否  | 生成视频数量，默认 1，最大 4    |

<Note>
  **模型选择：** 默认为竖屏，使用 `veo-3.1-landscape` 可生成横屏视频，使用 `-fast` 后缀可使用快速模型。
</Note>

## 示例 2：帧转视频（Frame-to-Video）

使用一张或两张图片作为关键帧生成视频：

```bash theme={null}
curl --location --request POST 'https://api.apiyi.com/v1/chat/completions' \
--header 'Content-Type: application/json' \
--header 'Authorization: sk-your-api-key' \
--data-raw '{
    "messages": [{
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": "根据两张图片生成一个完整的过渡视频"
            },
            {
                "type": "image_url",
                "image_url": {
                    "url": "开始帧图片URL或base64"
                }
            },
            {
                "type": "image_url",
                "image_url": {
                    "url": "结束帧图片URL或base64（可选）"
                }
            }
        ]
    }],
    "model": "veo-3.1-landscape-fast-fl",
    "stream": true,
    "n": 1
}'
```

### 图片参数说明

<Info>
  * **开始帧图片**：必传，仅限一张
  * **结束帧图片**：可选，如果不传则自动生成过渡效果
  * **图片格式**：支持 URL 或 base64 编码
</Info>

## 流式响应说明

开启流式输出后（`stream: true`），系统会实时返回生成进度和结果：

### 响应示例

````text theme={null}
data: {"id":"foaicmpl-xxx","object":"chat.completion.chunk","created":1762181811,"model":"veo-3.1-fast","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"foaicmpl-xxx","object":"chat.completion.chunk","created":1762181811,"model":"veo-3.1-fast","choices":[{"index":0,"delta":{"content":"```json\n{\n    \"prompt\": \"画只猪在天上飞\",\n    \"mode\": \"竖屏模式\"\n}\n```\n\n"},"finish_reason":null}]}

data: {"id":"foaicmpl-xxx","object":"chat.completion.chunk","created":1762181811,"model":"veo-3.1-fast","choices":[{"index":0,"delta":{"content":"> ⌛️ 视频正在生成中，请耐心等待...\n\n"},"finish_reason":null}]}

data: {"id":"foaicmpl-xxx","object":"chat.completion.chunk","created":1762181811,"model":"veo-3.1-fast","choices":[{"index":0,"delta":{"content":"> 🏃 进度：9.0%\n\n"},"finish_reason":null}]}

data: {"id":"foaicmpl-xxx","object":"chat.completion.chunk","created":1762181811,"model":"veo-3.1-fast","choices":[{"index":0,"delta":{"content":"> 🏃 进度：18.0%\n\n"},"finish_reason":null}]}

...

data: {"id":"foaicmpl-xxx","object":"chat.completion.chunk","created":1762181811,"model":"veo-3.1-fast","choices":[{"index":0,"delta":{"content":"> 🏃 进度：90.2%\n\n"},"finish_reason":null}]}

data: {"id":"foaicmpl-xxx","object":"chat.completion.chunk","created":1762181811,"model":"veo-3.1-fast","choices":[{"index":0,"delta":{"content":"> ✅ 第1个视频生成成功，[点击这里](https://veo-video.gptkey.asia/assets/flow/xxx.mp4) 查看视频~~~\n\n"},"finish_reason":null}]}

data: {"id":"foaicmpl-xxx","object":"chat.completion.chunk","created":1762181811,"model":"veo-3.1-fast","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":16,"completion_tokens":292,"total_tokens":308}}

data: [DONE]
````

### 响应说明

<Accordion>
  <AccordionItem title="进度更新">
    流式响应会实时返回生成进度，格式为：`> 🏃 进度：XX.X%`
  </AccordionItem>

  <AccordionItem title="视频链接">
    生成完成后，会返回视频的下载链接，格式为：`> ✅ 第N个视频生成成功，[点击这里](视频URL) 查看视频~~~`
  </AccordionItem>

  <AccordionItem title="完成标识">
    当所有视频生成完成后，会返回 `finish_reason: "stop"` 和 `data: [DONE]`
  </AccordionItem>
</Accordion>

## 生成速度

<Info>
  **VEO 3.1 生成速度：** 比 Sora 2 快 50%！

  * **快速模型** (`-fast`)：约 30-60 秒
  * **标准模型**：约 1-2 分钟
</Info>

## 下一步

<CardGroup cols={2}>
  <Card title="异步调用 API" icon="hourglass" href="/api-capabilities/veo/async-api">
    了解异步调用方式、模型定价和代码示例
  </Card>

  <Card title="VEO 概览" icon="video" href="/api-capabilities/veo/overview">
    返回 VEO 3.1 产品概览页面
  </Card>
</CardGroup>