# 从文本生成视频
> 根据场景描述创建视频，并可选用音频引导。

根据场景描述创建视频，并可选用音频引导。

## Agent 主路径

通过 Universal Skill 调用 MCP 工具 `beatra.videos.generate`。该工具会计费，
并返回异步任务。

1. 先确定场景、运动、时长与清晰度。
2. 当模型、音频支持、约束或价格会影响选择时，用
   `capability: "text_to_video"` 调用 `beatra.models.list`；否则省略
   `model` 或使用 `auto`。
3. 本地音频先经 `beatra.assets.upload` 上传，再使用其 artifact ID。
4. 为最终参数生成一个不透明的 `client_request_id`，只提交一次。
5. 使用 `beatra.tasks.get` 轮询同一个任务，直到终态。

## AI 指南

AI integration guide: https://docs.beatra.ai/llms/videos-text-to-video.md

## 工具参数

```json
{
  "prompt": "镜头缓慢推向暖色窗光下的陶瓷杯",
  "audio": { "type": "artifact", "artifact_id": "artifact_optional_audio" },
  "resolution": "720p",
  "duration": 6,
  "client_request_id": "vid-text-opaque-1"
}
```

`audio` 可选，且必须由所选模型支持；纯视觉生成时应省略。

## 模型、控制与成本

通用控制项包括 `prompt`、`negative_prompt`、`resolution`、
`duration`、`aspect_ratio`、`seed`、`enhance_prompt` 和 `watermark`；
每一项都应按所选模型的元数据使用。

`beatra.models.list` 是可选模型、音频支持、分辨率、时长、宽高比、默认值
和价格的当前事实源。不要把静态模型目录或价格表复制进 Agent 提示词。

分辨率和时长通常影响成本。用户没有明确偏好时应省略这些参数，让请求相关的
`auto` 选择应用最终模型声明的默认值；仅根据用户意图或当前模型发现结果填写。
显式指定的模型不得被静默替换。

### Seedance 2.5

设置 `model: "seedance-2.5"` 或 `"seedance-2.5-fast"` 可调用 **Seedance 2.5**（以及 `"seedance-2.0"` / `"seedance-2.0-fast"`）。Seedance 2.5 支持电影级镜头运动、多宽高比与音画同步选项；请使用 `capability: "text_to_video"` 调用 `beatra.models.list` 获取实时每秒积分价格与支持的分辨率/时长组合。

### MiniMax H3

设置 `model: "minimax-h3"` 可使用 MiniMax H3。该模型必须提供提示词，时长为
4–15 秒的整数。公共 `720p` 输出每秒
370 积分；`2k` 输出每秒 590 积分。显式选择 H3 并省略分辨率时默认
720p。可用控制项为 `prompt`、`resolution`、`duration`、`aspect_ratio` 和
`watermark`；该模式不接受输入音频。

### Wan 3.0

设置 `model: "wan3.0-video"` 或 `wan3.0-video-prime`，时长 2–30 秒，分辨率
`480p` / `720p` / `1080p`（默认 `720p`）。可选 `audio` 为驱动音频，不计费。
`wan3.0-video` 的 `480p` 为每输出秒 225 积分，高阶版为 335。不支持
`negative_prompt`。价格以 `beatra.models.list` 为准。

## 任务状态与恢复

`queued` 和 `running` 都不是失败。持续轮询同一 `task_id`，不能因为任务仍
在运行就创建替代任务。若创建响应丢失，以同一 `client_request_id` 和完全
相同的参数重试；任一输入改变都必须使用新 ID。产物、实际模型和计费只以
终态任务响应为准。

## 通过 REST 调用

直接协议集成可使用 `POST /v1/videos/text-to-video` 与共享任务端点，并遵循
[API 操作定义](https://docs.beatra.ai/zh/docs/api-reference/operations/videos/videos_t2v_v1_videos_text_to_video_post)。
REST/OpenAPI 是备用集成路径；Skill + MCP 才是标准 Agent 体验。