テキストから画像を生成

Agent の主経路

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

被写体、構図、スタイル、キャンバス、出力数を確定します。
通常は model を省略するか model: "auto" を使います。モデル、制御項目、互換性、価格を比較する前に、capability: "text_to_image" で beatra.models.list を呼び出します。
不透明な client_request_id を 1 つ作り、一度だけ送信して、返された task_id を保存します。
終了状態になるまで beatra.tasks.get で同じタスクを確認します。

AI ガイド

AI 連携 Markdown

独自アプリケーションに組み込む場合は、この 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 を省略するとランダムです。
enhance_prompt と reasoning を省略または null にすると、選択モデルの既定値が使われます。
明示キャンバス、ネガティブプロンプト、パレット、プロンプト拡張、推論、seed の可否は beatra.models.list に従います。互換性のない項目は無視されず、エラーになります。

現在の安定した画像エイリアスは wan2.7-image-pro、wan2.7-image、qwen-image-2.0-pro、qwen-image-2.0 です。1 枚あたりの価格は beatra.models.list のリアルタイム発見を正とし、agent プロンプトへ複製しないでください。モデル側が 4 枚を超える組画像を作れる場合でも、公開出力は最大 4 枚です。

課金、タスクの正しい状態、復旧

要求数に応じた credits が予約されますが、最終的には正常に保存された画像数だけが課金されます。一部成功では実際の artifact 数に精算されます。終了したタスクの usage と billing を最終値として扱います。

queued と running は失敗ではありません。作成応答を失った場合だけ、同じ client_request_id でまったく同じ引数を再送します。実行中という理由で別タスクを作らないでください。引数を変更した場合は新しい ID が必要です。

REST で呼び出す

独自統合では POST /v1/images/generations と共通タスク API を使用できます。完全な構造は生成済みの API operation を参照してください。推奨の統合方法は Skill + MCP です。REST はカスタムアプリケーション向けです。