GET
/v1/schemas/grok/image/v1/images/generations
Accept:
| field | recorded source |
|---|---|
| schema | Source linked above. upstream-spec Source trace592b360ae23c430da1461f6cadcab06ccc85a577134893ff1f73c4c7879d116b{
"fetchedAt": 1792732296,
"extractorVersion": "1",
"verifiedAt": null
} |
Request body
11 properties · 0 required · 6 $defs| property | type | description | constraints |
|---|---|---|---|
| aspect_ratio | enum | Aspect ratio of the generated image. Can be `1:1`, `3:4`, `4:3`, `9:16`, `16:9`, `2:3`, `3:2`, `9:19.5`, `19.5:9`, `9:20`, `20:9`, `1:2`, `2:1`, `21:9`, `5:2`, or `auto`. Defaults to `auto` for automatically selecting the best ratio for the prompt. Only suppor… | 1:1 | 3:4 | 4:3 | 9:16 | 16:9 | 2:3 · +10 more · nullable |
| deferred | any | If set, the request returns immediately with a `request_id` and the image is generated in the background. Poll `GET /v1/images/{request_id}` for the result. Only `response_format: "url"` is supported in this mode. | |
| model | any | Model to be used. | |
| n | any | Number of images to be generated | 1 ≤ n ≤ 10 · format: int32 · default: 1 |
| output | ImageOutput | Optional output destination. When present, each generated image is uploaded via HTTP PUT to the matching signed URL instead of xAI-hosted storage and the response `url` is that upload URL. Requires `response_format: "url"`; Zero Data Retention teams must set t… | nullable |
| prompt | string | Prompt for image generation. | |
| resolution | enum | Resolution of the generated image. Defaults to `1k`. Only supported by grok-imagine models. | 1k | 2k | 1.5k · nullable |
| response_format | any | Response format to return the image in. Can be url or b64_json. If b64_json is specified, the image will be returned as a base64-encoded string instead of a url to the generated image file. | default: "url" |
| storage_options | StorageOptions | Optional output storage configuration. When present, the generated image(s) are stored in the Files API and a `file_output` reference is returned in the response alongside the ephemeral URL. | nullable |
| user | any | A unique identifier representing your end-user, which can help xAI to monitor and detect abuse. | |
| quality | enum | Generation quality. Defaults to `auto`, which serves `low` for generation and `medium` for editing; images are billed at the quality served. Only supported by grok-imagine-image-2.0. Documented in the image generation guide and the official TypeScript SDK, abs… | low | medium | auto |
Types
6 $defsImageAspectRatioenum
Aspect ratio for image generation. Only supported by grok-imagine models.
1:1 | 3:4 | 4:3 | 9:16 | 16:9 | 2:3 · +10 more
ImageOutputobject
Output destination for generated images.
| upload_urls* | string[] | Signed URLs to upload the generated images via HTTP PUT, one per image: the list length must equal `n` (default 1). Each PUT sends a `Content-Type` equal to the image's `mime_type` in the response (`image/jpeg` unless the requested quality produces PNG), so si… |
ImageResolutionenum
Resolution for image generation. Only supported by grok-imagine models.
1k | 2k | 1.5k
PublicUrlInputboolean | object
Accepts either `true` (create public URL with defaults) or a configuration object with explicit options.
PublicUrlOptionsobject
Configuration for creating a public URL alongside file storage.
| expires_after | any | Seconds from now until the public URL expires. Must be between 3600 (1 hour) and 2592000 (30 days). | format: int64 |
StorageOptionsobject
Configuration for storing generation output in the Files API. When provided in a generation request, the output is stored as a permanent file and a `file_output` reference is included in the response.
| expires_after | any | Seconds from now until the file auto-expires. Maximum 2592000 (30 days). If omitted, the file does not expire. | format: int64 |
| filename* | string | Filename for the stored file. | |
| public_url | boolean | object | `true` = create public URL with default options (no independent expiry). Object = create public URL with explicit configuration. Omit = no public URL (file stored privately). | nullable |
Validate a payload
before you spend tokensshell
$ curl -X POST https://modelschemas.com/v1/validate \
-d '{"provider":"grok","endpointId":"v1/images/generations","payload":{…}}'
→ {"valid": false, "errors": [{"path": "#", "keyword": "required", …}]}