Generate images from text

Primary agent path

Use the Universal Skill with beatra.images.generate when there is no source image. It creates a billable asynchronous task.

1. Finalize the subject, composition, style, canvas, and output count.
2. Use model: "auto" or omit model for ordinary requests. Call beatra.models.list with capability: "text_to_image" before a model, control, compatibility, or price comparison.
3. Create one opaque client_request_id, submit once, and save the returned task_id.
4. Poll that task with beatra.tasks.get until terminal.

AI guide

Tool arguments

{
  "prompt": "A quiet flower shop with carved wooden doors at blue hour",
  "count": 1,
  "canvas": { "type": "preset", "tier": "2K", "aspect": "16:9" },
  "output_relationship": "independent",
  "client_request_id": "img-generate-opaque-1"
}

Use a target canvas such as { "type": "target", "width": 1536, "height": 1024 } when exact requested dimensions matter. Actual stored image dimensions remain authoritative.

Limits, defaults, and controls

• Request one to four outputs; count defaults to 1.
• Generate and transform default to a 2K 16:9 canvas. Edit defaults to a 2K canvas whose aspect ratio follows its base image.
• output_relationship defaults to independent; use sequence only when the selected interface card allows a coherent set.
• An omitted seed is random.
• Null or omitted enhance_prompt and reasoning use the selected model's documented default.
• Exact canvas, negative prompt, palette, prompt enhancement, reasoning, and seed availability is model- and intent-specific. Follow beatra.models.list; unsupported controls fail instead of being ignored.

The current stable image aliases also include qwen-image-3.0-pro and qwen-image-3.0, alongside wan2.7-image-pro, wan2.7-image, qwen-image-2.0-pro, qwen-image-2.0, gpt-image-2.5-flare, gpt-image-2.5-sunburst, and gpt-image-2. GPT Image 2.5 Flare and Sunburst are public for explicit selection and sit in text-to-image auto immediately before GPT Image 2 (after Qwen 2.0 / Qwen 3). GPT-eligible generate auto (including long-prompt 2K and 4K) selects Flare. An explicit GPT Image 2 or 2.5 request requires count: 1, an independent output, and a preset 1K, 2K, or 4K canvas. They do not accept a target canvas, seed, negative prompt, prompt enhancement, reasoning, or palette. GPT Image 2.5 accepts a 20,000-character prompt. Published per-successful-image prices are 90/150/230 credits for GPT Image 2 and 180/300/460 credits for both 2.5 models. A 4K 1:1 request is admitted. Read pricing.options from beatra.models.list and select the option matching the admitted output resolution; do not copy models or prices into an agent prompt. Wan sequence capacity above four is not exposed: every public output collection stops at four.

Billing, task status, and recovery

The request reserves the requested count, but it is charged only for successfully persisted images. A partial result therefore settles to its actual artifact count. Text-to-image has no supplier input-image component. Use terminal task usage and billing fields as final truth.

queued and running are not failures. If the create response is lost, retry the identical arguments with the same client_request_id; never create a replacement task merely because work is still running. Any changed argument requires a new ID.

REST API

Custom integrations may call POST /v1/images/generations and then use the shared task endpoints. Follow the generated API operation. Skill + MCP is the recommended integration; use REST for custom, non-agent applications.