# Generate images from text
> Create one or more images without a source image.

Create one or more images without a source image.

## 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

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

## Tool arguments

```json
{
  "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). Requests Qwen cannot handle but GPT can, including long prompts at 2K and 4K, select 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 can be accepted. Read `pricing.options` from
`beatra.models.list` and select the option matching the actual 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](https://docs.beatra.ai/en/docs/api-reference/operations/images/images_generations_v1_images_generations_post).
Skill + MCP is the recommended integration; use REST for custom, non-agent
applications.