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 are wan2.7-image-pro, wan2.7-image, qwen-image-2.0-pro, and qwen-image-2.0. Per-image prices come from beatra.models.list; do not copy them 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. 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.