# Beatra Skill + MCP — Generate images from text

> Create one or more images without a source image.
> Self-contained workflow guide for AI agents.
> Human-readable page: https://docs.beatra.ai/en/docs/capabilities/images/text-to-image

- Primary surface: the Universal Beatra Skill with authenticated MCP.
- Install or reconnect: https://beatra.ai/install.md
- MCP endpoint: `https://mcp.beatra.ai/mcp`
- Billable action: `beatra.images.generate`
- Dynamic model facts: call `beatra.models.list` with `capability: "text_to_image"` only when model constraints, controls, or prices matter.
- Interaction model: create one opaque `client_request_id`, submit the finalized arguments exactly once, then poll the returned `task_id` with `beatra.tasks.get` until terminal.
- Local media: call `beatra.assets.upload`, perform the returned HTTPS PUT exactly, and use the artifact ID from the PUT response.

REST/OpenAPI is the fallback protocol path, not the primary agent packaging.

---

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

## 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 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](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.

---

## Appendix: shared Skill + MCP contract

### Retry identity

One logical generation has one `client_request_id`. If the create response is
lost, retry the exact same arguments with that ID. If any prompt, media, model,
or output control changes, use a new ID. Never create another paid task merely
because the first task is `queued` or `running`.

### Polling and billing truth

Poll with `beatra.tasks.get` using bounded backoff. Stop at `succeeded`,
`failed`, or `canceled`. Only the task response is authoritative for the
resolved model, artifacts, charged credits, and refunded credits.

### Recovery

Preserve structured Beatra error codes. Reconnect on authentication failure;
stop and request a balance action on insufficient balance; refresh current
constraints with `beatra.models.list` after model validation; request a new
upload grant after expiration or MIME/length mismatch. Changed generation
arguments always require a new `client_request_id`.