---
title: "Generate one to four images from text"
method: POST
path: "/v1/images/generations"
tags: ["images"]
---

# Generate one to four images from text

`POST /v1/images/generations`

## Request

- Base URL: `https://api.beatra.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.beatra.ai/v1/images/generations`
- Auth: none declared. Required headers: `Idempotency-Key`

Create an asynchronous image-generation task without source images. `auto` selects a live model that can satisfy the complete request; a concrete model is validated exactly as requested and is never substituted.

## Headers

- `x-request-id` string, nullable
- `Idempotency-Key` string, required
- `authorization` string, nullable

## Request body

- TextToImageRequest: Generate one to four images from a prompt.
  - `metadata` object, nullable: Caller-supplied metadata; ≤16 keys, key ≤64 chars, value ≤512 chars
  - `callback_url` string, nullable: HTTPS URL beatra will POST the final Task envelope to when the Task reaches a terminal state
  - `callback_signing_key_id` string, nullable: Optional standalone callback signing key. Omit for unsigned callback delivery; requires callback_url when provided.
  - `model` 'auto' | 'gpt-image-2.5-flare' | 'gpt-image-2.5-sunburst' | 'gpt-image-2' | 'image-01-live' | 'wan2.7-image-pro' | 'wan2.7-image' | 'qwen-image-3.0-pro' | 'qwen-image-3.0' | 'qwen-image-2.0-pro' | 'qwen-image-2.0': Use auto for compatibility-based selection from the configured live candidates. A concrete model is evaluated exactly as requested and is never substituted.
  - `prompt` string, required: Required prompt containing at least one non-whitespace character.
  - `count` integer: Requested output image count. The public range is one through four, and the selected model must support the exact count; Beatra does not split the request.
  - `canvas` union: Desired output canvas. Presets are quality tiers, and target dimensions may be normalized or vary; inspect output images for actual dimensions.
    - ImagePresetCanvas: Named canvas tier with an optional positive aspect ratio.
      - `type` 'preset', required
      - `tier` '1K' | '2K' | '4K', required: Named quality tier, not a promise of exact encoded dimensions.
      - `aspect` string, nullable: Positive width:height ratio whose components are integers from 1 to 999999, normalized by greatest common divisor. A tier describes quality, not exact pixels.
    - ImageTargetCanvas: Desired pixel target; the selected implementation may normalize actual output.
      - `type` 'target', required
      - `width` integer, required: Desired output width in pixels
      - `height` integer, required: Desired output height in pixels
  - `seed` integer, nullable: Optional random seed. Supplying it constrains model eligibility; omit it for model-managed randomness.
  - `negative_prompt` string, nullable: Optional content or qualities to avoid. Supplying it constrains model eligibility and is rejected when no compatible model is available.
  - `enhance_prompt` boolean, nullable: Ask the model to rewrite the prompt before generation. Omit or use null to keep the prompt exactly as written; an explicit boolean constrains model eligibility.
  - `palette` ImagePaletteColor[], nullable: Three to ten weighted RGB colors. Runtime validation requires the weights to sum exactly to 1.0000.
    - `color` string, required
    - `weight` union, required: Exact decimal weight greater than 0 and at most 1, with no more than 4 fractional digits. Decimal strings avoid binary-float ambiguity.
      - number
      - string
  - `output_relationship` 'independent' | 'sequence'
  - `reasoning` boolean, nullable: Omit or use null to retain the selected model's documented default; an explicit boolean constrains model eligibility.

## Response `202`

Task accepted

- TaskEnvelope: Standard Task envelope. Returned by every async-creation endpoint, GET /v1/tasks/{id}, and the body of customer callback POSTs.
  - `object` 'task'
  - `task_id` string, required
  - `status` 'queued' | 'running' | 'succeeded' | 'failed' | 'canceled', required
  - `capability` string, required
  - `workload_type` 'model' | 'social_operation'
  - `model` string, nullable: Caller-requested model verbatim (may be 'auto'). Null for social_operation tasks.
  - `resolved_model` string, nullable: Actual model that ran (null until execution starts; equals model for explicit-model calls)
  - `model_selection_reason` unknown
  - `social` SocialTaskIdentity
    - `platform` string, required
    - `operation_key` string, required
    - `operation_name` string, required
    - `schema_hash` string, required
  - `metadata` object, nullable
  - `input` object, nullable
  - `progress` AppApiV1SchemasCommonTaskProgress
    - `percent` integer, nullable
    - `stage` string, nullable
    - `message` string, nullable
  - `output` object, nullable
  - `warnings` TaskWarning[]
    - `code` string, required: e.g. option_clamped / auto_routed
    - `message` string, required
    - `field` string, nullable
  - `error` AppApiV1SchemasCommonTaskError
    - `code` string, required: Stable machine-readable public error code.
    - `type` string, required: Stable public error family.
    - `message` string, required: Human-readable safe failure reason.
    - `retryable` boolean, required: Whether the same logical request may succeed when retried unchanged.
    - `param` string, nullable: JSON Pointer to the relevant request or output field.
    - `details` object, nullable: Provider-neutral expected, received, supported, or candidate failure facts.
    - `request_id` string, required: Request trace identifier for support and correlation.
  - `usage` UsageObject
    - `input_tokens` integer, nullable
    - `output_tokens` integer, nullable
    - `cache_read_tokens` integer, nullable
    - `cache_creation_tokens` integer, nullable
    - `reasoning_tokens` integer, nullable
    - `image_count` integer, nullable
    - `image_pixels` integer, nullable
    - `video_seconds` number, nullable
    - `input_video_seconds` number, nullable: Authoritative input-video seconds included in settled video usage.
    - `output_video_seconds` number, nullable: Authoritative generated/output-video seconds included in settled video usage.
    - `audio_seconds` number, nullable
    - `characters` integer, nullable
    - `lines` UsageLine[]
      - `meter` string, required: e.g. input_token / output_token / image_count / input_video_second / output_video_second
      - `quantity` string, required: Decimal — number of meter units consumed
      - `unit` string, required: Display unit, e.g. 'token' / 'image' / 'second'
      - `billed_amount_credits` string, nullable: Credits charged for this usage line. Populated by PR-2/3.
    - `credits` string, nullable: Credits charged for this Task. Populated by PR-2 / PR-3.
  - `billing` TaskBilling
    - `charged_credits` string, nullable: Credits charged to wallet for this Task. Populated by PR-2/3.
    - `refunded_credits` string, nullable: Credits refunded for this Task. Populated by PR-3.
    - `granted_credits` string, nullable: Credits on this Task covered by a directed grant rather than by the wallet, net of any revocation. Absent when no grant applied.
    - `grant_source` string, nullable: Which grant covered it. Present exactly when granted_credits is.
    - `net_charged_credits` string, nullable: Final customer charge: charged_credits minus refunded_credits minus granted_credits. This is the number to report as what the Task cost.
  - `callback` TaskCallback
    - `url` string, required
    - `status` 'pending' | 'dispatching' | 'delivered' | 'retrying' | 'failed', required
    - `attempt_count` integer, required
    - `delivered_at` string, date-time, nullable
    - `last_error` string, nullable: Stable Beatra-owned callback delivery failure summary.
  - `created_at` string, date-time, required
  - `started_at` string, date-time, nullable
  - `deadline_at` string, date-time, nullable
  - `completed_at` string, date-time, nullable
  - `cancel_requested_at` string, date-time, nullable
  - `links` TaskLinks, required
    - `self` string, required
    - `cancel` string, nullable
    - `assets` string, nullable: Absolute customer-console URL for viewing and managing the generated artifacts.

## Other responses

- `422`: Unprocessable Entity

---

[API](https://skmtc.dev/beatra/apis/agent-service-api.md) · [All operations](https://skmtc.dev/beatra/apis/agent-service-api/llms.txt) · [OpenAPI document](https://skmtc.dev/beatra/apis/agent-service-api/revisions/58e440556498?raw)