文本生成图像

Agent 主路径

没有源图像时，通过 Universal Skill 调用 beatra.images.generate。该工具会创建一个计费的异步任务。

先确定主体、构图、风格、画布和输出数量。
普通请求省略 model 或使用 model: "auto"。需要比较模型、控制项、兼容性或价格时，先用 capability: "text_to_image" 调用 beatra.models.list。
创建一个不透明的 client_request_id，只提交一次，并保存返回的 task_id。
使用 beatra.tasks.get 轮询同一任务，直到进入终态。

AI 指南

给 AI 的集成说明

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

工具参数

{
  "prompt": "蓝调时刻的一间安静花店，带雕花木门",
  "count": 1,
  "canvas": { "type": "preset", "tier": "2K", "aspect": "16:9" },
  "output_relationship": "independent",
  "client_request_id": "img-generate-opaque-1"
}

需要明确目标尺寸时，可以使用 { "type": "target", "width": 1536, "height": 1024 }。最终应以已保存图像的实际尺寸为准。

上限、默认值和控制项

每次可请求 1–4 张输出，count 默认为 1。
生成和参考变换默认使用 2K / 16:9；编辑默认使用 2K / source，继承第一张基础图像的比例。
output_relationship 默认为 independent；只有实时模型信息允许时才使用 sequence。
省略 seed 时使用随机值。
省略或传 null 的 enhance_prompt、reasoning 使用所选模型的默认值。
精确画布、负向提示词、调色板、提示词增强、推理和种子能力以 beatra.models.list 为准；不兼容控制项会报错，不会被静默忽略。

当前稳定图像别名为 wan2.7-image-pro、wan2.7-image、qwen-image-2.0-pro 和 qwen-image-2.0。每张单价以 beatra.models.list 实时发现为准，不要把价格复制进 agent 提示词。即使某个模型的组图能力更高，公开输出也始终最多 4 张。

计费、任务状态与恢复

请求会按期望数量预留额度，但最终只按成功保存的图像数量结算。部分成功会按实际 artifact 数量收费。最终以终态任务的 usage 和 billing 为准。

queued 与 running 都不是失败。若创建响应丢失，只能使用同一个 client_request_id 重试完全相同的参数；不要因为任务仍在运行就创建替代任务。任何参数变化都需要新 ID。

REST 回退路径

自定义集成可以调用 POST /v1/images/generations，然后使用通用任务接口。完整结构见生成的 API operation。REST/OpenAPI 是回退集成路径；Skill + MCP 才是标准 Agent 体验。