从文本生成视频

Agent 主路径

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

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

AI 指南

给 AI 的集成说明

接入自有应用时，可以把这份 API 指南复制给 Claude、Codex 或其他编程助手。

工具参数

{
  "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 选择应用最终模型声明的默认值；仅根据用户意图或当前模型发现结果填写。显式指定的模型不得被静默替换。

MiniMax H3

设置 model: "minimax-h3" 可使用 MiniMax H3。该模型必须提供提示词，固定生成 2K 视频，时长为 4–15 秒的整数。可用控制项为 prompt、resolution、 duration、aspect_ratio 和 watermark；该模式不接受输入音频。生成视频按每秒 590 credits 计费。

任务状态与恢复

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

通过 REST 调用

直接协议集成可使用 POST /v1/videos/text-to-video 与共享任务端点，并遵循 API 操作定义。 REST/OpenAPI 是备用集成路径；Skill + MCP 才是标准 Agent 体验。