curl --request POST \
--url https://api.poyo.ai/api/generate/submit \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "qwen-image-2.1",
"input": {
"prompt": "A bilingual technology poster with the headline Future Vision, precise typography, blue and silver palette",
"size": "3:4",
"resolution": "1K"
}
}
'{
"code": 200,
"data": {
"task_id": "task-unified-1790245800-qwen21",
"status": "not_started",
"created_time": "2026-09-24T10:30:00Z"
}
}Alibaba
Qwen Image 2.1
The Qwen Image 2.1 API generates one image from text, combines up to 10 reference images, or applies a mask edit. Output is 1K or 2K, and backgrounds can be opaque or transparent.
POST
/
api
/
generate
/
submit
curl --request POST \
--url https://api.poyo.ai/api/generate/submit \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "qwen-image-2.1",
"input": {
"prompt": "A bilingual technology poster with the headline Future Vision, precise typography, blue and silver palette",
"size": "3:4",
"resolution": "1K"
}
}
'{
"code": 200,
"data": {
"task_id": "task-unified-1790245800-qwen21",
"status": "not_started",
"created_time": "2026-09-24T10:30:00Z"
}
}- After submission, a
task_idwill be returned. If you provided acallback_url, when the task status becomesfinishedorfailed, a POST request will be sent to thecallback_url. - Regardless of whether
callback_urlis provided, you can retrieve the result through the unified Query Task Status endpoint.
qwen-image-2.1 for text-to-image generation, multi-reference image editing, transparent assets, and local edits. Each request produces one image.
Omit image_urls or pass an empty array for text-to-image. Provide 1–10 reference image URLs for image-to-image. Reference order matches references in your prompt, such as “the first image”. For stronger detail preservation, use four or fewer reference images.
Models
- qwen-image-2.1 — Qwen Image 2.1
Required parameters
promptis required, with non-empty text up to 5,000 characters.
Optional parameters
image_urlsaccepts up to 10 publicly accessible HTTP(S) reference URLs. JPEG, PNG, and WebP are supported, up to 30MB and 25MP per image. Media limits are checked during generation.sizesupports1:1,4:3,3:4,3:2,2:3,16:9,9:16,21:9, and9:21. Reference-image requests also supportauto. Defaults to1:1for text-to-image andautofor image-to-image.resolutionsupports1K(default) and2K.output_formatsupportspng(default),webp, andjpeg.prompt_extendcontrols prompt enhancement, enabled by default.enable_safety_checkercontrols content safety checking, enabled by default.backgroundsupportsopaque(default) andtransparent. Transparent output requires PNG or WebP.mask_urlaccepts an HTTP(S) mask URL, used with exactly one reference image and an opaque background.seedaccepts an optional integer. Omit it to generate with a random seed.
size, prompt_extend, and enable_safety_checker as shown above. negative_prompt and multiple-image output parameters are not supported.
Examples
Text-to-Image
{
"model": "qwen-image-2.1",
"input": {
"prompt": "A bilingual technology poster with the headline Future Vision, precise typography, blue and silver palette",
"size": "3:4",
"resolution": "1K"
}
}
Multi-Reference Generation
Replace the example URLs with publicly accessible images.{
"model": "qwen-image-2.1",
"input": {
"prompt": "Combine the product in the first image with the colors and lighting of the second image",
"image_urls": [
"https://example.com/product.png",
"https://example.com/style.jpg"
],
"size": "auto",
"resolution": "2K",
"prompt_extend": false
}
}
Transparent Assets
Describe the subject only. Background, scene, or surface descriptions may prevent a transparent result. JPEG cannot carry transparency.{
"model": "qwen-image-2.1",
"input": {
"prompt": "A playful corgi sticker, isolated subject",
"background": "transparent",
"output_format": "webp",
"seed": 20260921
}
}
Mask Editing
White mask areas are edited; black areas stay unchanged. Use a mask with the same aspect ratio as the reference image; its dimensions are scaled to the reference. Exactly one reference image is required, and transparent backgrounds are unavailable in this mode. The output follows the reference image’s aspect ratio.size and prompt_extend are ignored when a mask is supplied.
{
"model": "qwen-image-2.1",
"callback_url": "https://your-domain.com/callback",
"input": {
"prompt": "Replace the marked cushion with a blue velvet cushion",
"image_urls": ["https://example.com/room.png"],
"mask_url": "https://example.com/mask.png",
"resolution": "2K",
"output_format": "png"
}
}
Authorizations
All API endpoints require Bearer Token authentication.
Create an API key: sign in to PoYo, open Dashboard → API Key at poyo.ai/dashboard/api-key, and click to create a key.
Add it to the request header:
Authorization: Bearer YOUR_API_KEY
Body
application/json
Response
Task submitted successfully
Business status code. 200 means success; any other value means the request failed. Always check this field: some validation errors return HTTP 200 with code: 400 in the body.
200: Success400: Invalid request parameters401: Missing or invalid API key402: Insufficient credits403: Permission denied404: Resource not found408: Request timeout429: Rate limit exceeded500: Internal server error502: Upstream service error503: Service unavailable
See Error Codes for details.
Available options:
200, 400, 401, 402, 403, 404, 408, 429, 500, 502, 503 Example:
200
Show child attributes
Show child attributes