# テキストから画像を生成
> 元画像なしで、1 枚以上の画像を作成します。

元画像なしで、1 枚以上の画像を作成します。

## Agent の主経路

元画像がない場合は、Universal Skill から `beatra.images.generate` を使用します。このツールは課金対象の非同期タスクを作成します。

1. 被写体、構図、スタイル、キャンバス、出力数を確定します。
2. 通常は `model` を省略するか `model: "auto"` を使います。モデル、制御項目、互換性、価格を比較する前に、`capability: "text_to_image"` で `beatra.models.list` を呼び出します。
3. 不透明な `client_request_id` を 1 つ作り、一度だけ送信して、返された `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` を省略するとランダムです。
- `enhance_prompt` と `reasoning` を省略または null にすると、選択モデルの既定値が使われます。
- 明示キャンバス、ネガティブプロンプト、パレット、プロンプト拡張、推論、seed の可否は `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 上限は 20,000 文字です。公開価格は 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 を使用できます。完全な構造は生成済みの [API operation](https://docs.beatra.ai/ja/docs/api-reference/operations/images/images_generations_v1_images_generations_post) を参照してください。推奨の統合方法は Skill + MCP です。REST はカスタムアプリケーション向けです。