# 文本生成图像
> 在没有源图像时，创建一张或多张图像。

在没有源图像时，创建一张或多张图像。

## Agent 主路径

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

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

## AI 指南

AI integration guide: https://docs.beatra.ai/llms/images-text-to-image.md

## 工具参数

```json
{
  "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 可以处理的请求（包括 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 积分，两个 2.5 模型为 1K 180 / 2K 300 / 4K 460 积分。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](https://docs.beatra.ai/zh/docs/api-reference/operations/images/images_generations_v1_images_generations_post)。REST/OpenAPI 是回退集成路径；Skill + MCP 才是标准 Agent 体验。