Skip to main content
POST
Text-to-image: generate images from a text prompt
The interactive Playground on the right lets you test the endpoint directly. Enter your API Key in Authorization (format: Bearer sk-xxx), fill in prompt, pick aspect_ratio / resolution, and send.
When to use this page: text-to-image generation from a prompt alone — no image upload involved. To modify an existing image or fuse several, use the Image Editing endpoint.
⚠️ Do not send reference images to this endpointPassing image / image_url / images here raises no error. It returns 200 and generates a brand-new image from the prompt — the reference is silently discarded and you are still billed.With no error signal, this usually surfaces only when someone notices the output has nothing to do with the input. Any workflow with a reference image must use /v1/images/edits.
⚠️ Invalid parameters do not raise errorsInvalid aspect_ratio (e.g. 5:7), resolution (e.g. 1K, 1024x1024) and response_format (e.g. base64) all silently fall back to defaults and still return an image. When output does not match expectations, check the parameter spelling first — note that resolution values are lowercase 1k / 2k.One exception: resolution: "4k" returns 503 model_service_unavailable, meaning the tier is unsupported, not that the channel is down. Retrying will not help.
All image APIs are synchronous: there is no async task ID, so a disconnected client loses the result while the request is still billed. 1K takes about 9 seconds and 2K about 15-17 seconds, so set the client timeout to 360 seconds — see Image API Best Practices.

Code Examples

Python (OpenAI SDK)

Python (raw requests)

cURL

Node.js (native fetch)

Browser JavaScript

Parameter Reference

Actual output pixels per aspect ratio:
seed is not supported (accepted without error but has no effect — results are not reproducible), and neither is mask inpainting. OpenAI-style fields such as size / quality / style are silently ignored.

Response Format

Response field pitfalls
  • Each data[] entry contains either url or b64_json depending on response_format — never both.
  • revised_prompt is not returned, nor are respect_moderation / model. Do not assume they exist.
  • b64_json is raw base64 with no data:image/...;base64, prefix — decode it directly.
  • created is always 0 and cannot be used as a timestamp.
  • With n > 1 the data array holds multiple entries — do not read only data[0].
usage cannot be used for reconciliation: prompt_tokens is always 1000 x n, independent of actual prompt length. This family is billed at a flat rate per image ($0.02 / $0.045); use the APIYI Console billing records for actual charges.

Authorizations

Authorization
string
header
required

API Key created in the APIYI Console

Body

application/json
model
enum<string>
default:grok-imagine-image
required

Model ID. The quality variant delivers higher fidelity at a higher price

Available options:
grok-imagine-image,
grok-imagine-image-quality
prompt
string
required

Prompt, English or Chinese. Describe subject, scene, style and lighting in detail

Example:

"A photorealistic red wooden boat moored on a glassy alpine lake at dawn, mist over the water, snow-capped peaks behind, cinematic photography"

n
integer
default:1

Number of images, 1-10. Values of 11 or above return 400; 0 is silently treated as 1

Required range: 1 <= x <= 10
Example:

1

aspect_ratio
enum<string>
default:1:1

Output aspect ratio. Actual pixel dimensions per resolution tier:

Values outside this enum do not raise an error — they silently fall back to 1:1.

Available options:
1:1,
16:9,
9:16,
4:3,
3:4
Example:

"16:9"

resolution
enum<string>
default:1k

Resolution tier. 1k is roughly 0.9-1.05 megapixels and returns JPEG; 2k is roughly 4.2-4.5 megapixels and returns PNG (5-6 MB per image). Both tiers cost the same.

4k returns 503; other invalid values (such as 1K or 1024x1024) silently fall back to 1k.

Available options:
1k,
2k
Example:

"1k"

response_format
enum<string>
default:url

Response format. url returns a direct image link (no signed query params); b64_json returns a raw base64 string (without the data: prefix).

Invalid values silently fall back to the default url.

Available options:
url,
b64_json
Example:

"url"

Response

Images generated successfully

created
integer

Creation timestamp. Always 0 for this model — do not use it for timing

Example:

0

data
object[]

Array of image results, length equals the requested n

usage
object

Placeholder values — do not use for billing reconciliation. prompt_tokens is always 1000 x n, regardless of actual prompt length. Use the Console billing records instead.