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

# 视频生成

## 功能说明

对应工具标识 `video_generate`。

`video_generate` 根据文本描述生成视频。下面的示例先用 `image_generate` 生成首帧与尾帧，再合成视频。

导入路径：`from veadk.tools.builtin_tools.video_generate import video_generate`

## 环境变量与前提

<Warning>
  附加要求：

  1. 配置用于智能体推理模型的 API Key；
  2. 配置用于视频生成的模型名称（`MODEL_VIDEO_NAME`）；
  3. 若使用首尾帧合成，还需配置图像生成模型名称（`MODEL_IMAGE_NAME`）。
</Warning>

环境变量：

* `MODEL_VIDEO_API_KEY`：视频生成模型的 API Key；未设置时依次回退到 `MODEL_AGENT_API_KEY` 和配置文件中的 `model.api_key`
* `MODEL_AGENT_API_KEY`：智能体推理模型的 API Key
* `MODEL_VIDEO_NAME`：视频生成模型名称
* `MODEL_VIDEO_API_BASE`：视频生成模型 API 地址，默认为火山方舟端点
* `MODEL_IMAGE_NAME`：图像生成模型名称

<Note>
  凭证在工具执行时解析，而非导入时。导入工具模块不会触发客户端初始化，也不会要求凭证已配置。
</Note>

`config.yaml` 配置项：

```yaml title="config.yaml" lines theme={null}
model:
  video:
    name: doubao-seedance-2-0-260128
    api_base: https://ark.cn-beijing.volces.com/api/v3/
    api_key: your-api-key-here
```

使用 BytePlus 时应按已开通服务显式设置对应的媒体模型名称、API 地址和 API Key；不要假定 `CLOUD_PROVIDER` 会覆盖这些媒体配置。图像或视频的能力与参数限制以所选模型服务为准。视频 API 地址与默认模型名在导入时确定，应在启动进程前配置

## 使用方法

```python title="examples/tools/video_generate/agent.py" lines theme={null}
import asyncio

from veadk import Agent, Runner
from veadk.memory.short_term_memory import ShortTermMemory
from veadk.tools.builtin_tools.image_generate import image_generate
from veadk.tools.builtin_tools.video_generate import video_generate, video_task_query

agent = Agent(
    name="video_generate_agent",
    model_name="doubao-seed-2-1-pro-260628",
    description="An expert in creating images and videos.",
    instruction=(
        "先用 image_generate 生成首帧和尾帧，再用 video_generate 合成视频，"
        "若返回待处理任务则用 video_task_query 查询；完成后返回视频 URL 并简述内容。"
    ),
    tools=[image_generate, video_generate, video_task_query],
)

runner = Runner(agent=agent, short_term_memory=ShortTermMemory())


async def main():
    response = await runner.run("生成一只小狗，再生成它飞上天空的画面，最终合成一个视频")
    print(response)


if __name__ == "__main__":
    asyncio.run(main())
```

## 参数与任务状态

| 参数 | 类型 | 默认值 | 说明 |
| :- | :- | :- | :- |
| `params` | `list[dict]` | 必填 | 视频生成请求列表 |
| `tool_context` | `ToolContext` | 自动注入 | 工具运行时上下文 |
| `batch_size` | `int` | `10` | 每批提交数量，应为正整数 |
| `max_wait_seconds` | `int` | `1200` | 每批轮询预算，用于计算查询轮次；不是严格的整体调用时限 |
| `model_name` | `str` | 配置或内置模型 | 本次生成使用的模型，默认值在导入时读取 |

每个请求必须有 `video_name: str` 与 `prompt: str`。其余字段未提供时使用服务默认行为：

| 字段 | 类型 | 默认值 | 说明 |
| :- | :- | :- | :- |
| `first_frame`、`last_frame` | `str \| None` | `None` | 首帧和尾帧图片 URL |
| `reference_images` | `list[str]` | `[]` | 参考图片 |
| `reference_videos` | `list[str]` | `[]` | 参考视频 |
| `reference_audios` | `list[str]` | `[]` | 参考音频 |
| `ratio`、`resolution` | `str \| None` | `None` | 所选模型支持的画面比例和分辨率 |
| `duration`、`frames` | `int \| None` | `None` | 时长秒数或帧数，按模型约束选择 |
| `camera_fixed` | `bool \| None` | `None` | 固定摄像机 |
| `seed` | `int \| None` | `None` | 随机种子 |
| `watermark` | `bool \| None` | `None` | 是否添加水印 |
| `generate_audio` | `bool \| None` | `None` | 是否生成音频，取决于模型能力 |
| `tools` | `list[dict] \| None` | `None` | 例如联网搜索，仅纯文生视频可用；包含任何参考输入时忽略 |

返回结果包含 `status`、`success_list`、`error_list`、`error_details` 和 `pending_list`。成功项为视频名称到 URL 的映射；待处理项含 `task_id`，本地等待结束不会取消远端生成任务，不能直接重新提交以代替查询

`video_task_query(task_id: str, tool_context: ToolContext)` 接收必填任务 ID 和自动注入的上下文，没有可选参数，返回 `status`、`video_url` 和 `error` 等字段。`queued`、`running` 表示仍在执行，`succeeded` 且有 URL 才可交付，`failed` 应查看错误。查询与生成需使用同一服务地址和有权限的凭证