文本生成图像

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 为准；不兼容控制项会报错，不会被静默忽略。

当前稳定图像别名包括 qwen-image-3.0-pro、qwen-image-3.0、gpt-image-2.5-flare、gpt-image-2.5-sunburst 和 gpt-image-2，并保留 wan2.7-image-pro、wan2.7-image、qwen-image-2.0-pro 和 qwen-image-2.0。GPT Image 2.5 Flare 与 Sunburst 可显式选择，文生图 auto 中排在 Qwen 2.0 / Qwen 3 之后、gpt-image-2 之前；Qwen 接不住且 GPT 可吃的请求（含长 prompt 2K 与 4K）会选 Flare。显式选择 GPT Image 2 或 2.5 时，必须使用 count: 1、independent 输出关系和 1K、2K 或 4K 预设画布；不支持目标画布、seed、负向提示词、提示词增强、推理或调色板。GPT Image 2.5 的 prompt 上限为 20000 字符。公开价格：GPT Image 2 为 1K 90 / 2K 150 / 4K 230 credits，两个 2.5 模型为 1K 180 / 2K 300 / 4K 460 credits。4K 1:1 可以准入。从 beatra.models.list 的 pricing.options 选择与准入输出分辨率匹配的价格；不要把模型或价格复制进 agent 提示词。其他公开接口的输出上限仍为 4 张。

计费、任务状态与恢复

请求会按期望数量预留额度，但最终只按成功保存的图像数量结算。部分成功会按实际 artifact 数量收费；文生图没有供应商输入图片成本。最终以终态任务的 usage 和 billing 为准。

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

REST 回退路径

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