Qwen Image 2.1

POST https://api.beatapi.io/v1/images/tasks

Generate or edit an image with up to ten public HTTPS references, 1K or 2K output and optional transparent PNG or WebP.

Supported modes

Request rules: auto follows the first reference image; without images it renders 1:1. enhance_prompt defaults to true without images and false with images. A transparent background requires png or webp, not jpeg. Reference example URLs are placeholders; replace them with accessible HTTPS images. These examples describe the saved public contract, not completed model calls.

Async flow: Create the task, save data.id, then poll the Task with GET /v1/tasks/{task_id}. On succeeded, read data.output.media. On failed, read data.error_code and data.error_message, then follow the error and retry policy.

Using a local file? upload a local input first and pass the returned data.url.

Authorization

Authorization   string   required

Send your BeatAPI API key as a Bearer token. Create one on the Dashboard.

Authorization: Bearer <BEATAPI_API_KEY>

Keep permanent API keys on trusted servers. Content-Type: application/json is required for the request body. Idempotency-Key is optional when the endpoint exposes it and is recommended for safe retries with the exact same body.

Request body

aspect_ratio   enum<string>   optional

auto follows the first reference image; without images it renders 1:1.

Available options: auto, 1:1, 4:3, 3:4, 3:2, 2:3, 16:9, 9:16, 21:9, 9:21
Default: "auto"

background   enum<string>   optional

opaque or transparent. Transparent output requires PNG or WebP.

Available options: opaque, transparent
Default: "opaque"

enhance_prompt   boolean   optional

Rewrites the prompt before rendering. Defaults to true without images and false with images; no unconditional default.

images   string[]   optional

One to ten public HTTPS image URLs. Omit for text-to-image.

Count: 1 to 10 items

model   enum<string>   required

Must be qwen-image-2.1.

Available options: qwen-image-2.1

output_format   enum<string>   optional

Output file format. Use png or webp with transparent background; jpeg cannot retain alpha.

Available options: png, webp, jpeg
Default: "png"

prompt   string   required

Generation or reference-editing instructions, from 1 to 5000 characters.

Length: 1 to 5000 characters

resolution   enum<string>   optional

Output tier, 1K or 2K. A prompt cannot select a different tier.

Available options: 1K, 2K
Default: "1K"

seed   integer   optional

Optional integer from 0 to 2147483647; no -1 value and no documented default.

Range: 0 to 2147483647

Request examples

Text to image

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header 'Authorization: Bearer <BEATAPI_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "qwen-image-2.1",
  "prompt": "A white porcelain crane above misty mountains, no text."
}'

Transparent WebP

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header 'Authorization: Bearer <BEATAPI_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "qwen-image-2.1",
  "prompt": "A single green glass perfume bottle, isolated on a transparent background, no text.",
  "resolution": "2K",
  "aspect_ratio": "1:1",
  "background": "transparent",
  "output_format": "webp",
  "enhance_prompt": true,
  "seed": 0
}'

Reference image

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header 'Authorization: Bearer <BEATAPI_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "qwen-image-2.1",
  "prompt": "Keep the product shape and label from the reference, place it on a pale stone counter under soft morning light.",
  "images": [
    "https://example.com/product.png"
  ],
  "resolution": "1K",
  "aspect_ratio": "auto",
  "background": "opaque",
  "output_format": "png",
  "enhance_prompt": false,
  "seed": 42
}'

Response

Contract example only, not an executed task or generated result. The 1K example amount comes from the bundled Qwen price catalogue; actual usage is returned by the task.

{
  "data": {
    "id": "task_8K2qA",
    "object": "task",
    "task_kind": "image",
    "capability_id": "qwen-image-2.1",
    "capability_version": null,
    "media_type": "image",
    "model": "qwen-image-2.1",
    "status": "queued",
    "stage": "queued",
    "created_at": 1782210000,
    "updated_at": 1782210000,
    "completed_at": null,
    "output": null,
    "usage": {
      "credits_reserved": 0.03,
      "credits_charged": 0.03,
      "credits_settled": 0,
      "credits_refunded": 0
    },
    "request_id": "req_abc123",
    "error_code": null,
    "error_message": null
  }
}

Errors