GET

/v1/schemas/grok/image/v1/images/edits

Accept:

kind inputactivity imagehash f3671b87…extracted Oct 23, 2026version currentsource upstream spec ↗

field	recorded source
schema	Source linked above. upstream-spec Source trace `592b360ae23c430da1461f6cadcab06ccc85a577134893ff1f73c4c7879d116b` { "fetchedAt": 1792732296, "extractorVersion": "1", "verifiedAt": null }

Request body

13 properties · 1 required · 7 $defs

property	type	description	constraints
prompt*	string	Prompt for image editing.
aspect_ratio	enum	Aspect ratio of the output image for image editing with multiple images. For single image editing, do not set this. It will always auto-detect from the input image.	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 edit is generated in the background. Poll `GET /v1/images/{request_id}` for the result. Only `response_format: "url"` is supported in this mode.
image	ImageUrl	Input image to perform edit on. Mutually exclusive with `images`.	nullable
images	ImageUrl[]	List of input images for multi-reference editing. Mutually exclusive with `image`. When multiple images are provided, refer to them as \<IMAGE_0\>, \<IMAGE_1\>, etc. in the prompt.
model	any	Model to be used.
n	any	Number of image edits to be generated.	format: int32
output	ImageOutput	Optional output destination. When present, each edited 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 this…	nullable
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

7 $defs

ImageAspectRatioenum

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

ImageUrlobject

Image input for generation and editing requests. Accepts a public URL, a base64-encoded data URL, or a file_id from the xAI Files API.

file_id	any	File ID from the xAI Files API. Mutually exclusive with `url`. The file must be an image (JPEG, PNG, or WebP) and fully uploaded.
url	string	Public URL or base64-encoded data URL of the image (JPEG, PNG, or WebP). Also accepts `image_url` for compatibility. Required when `file_id` is not set.

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 tokens

shell

$ curl -X POST https://modelschemas.com/v1/validate \
    -d '{"provider":"grok","endpointId":"v1/images/edits","payload":{…}}'
→ {"valid": false, "errors": [{"path": "#", "keyword": "required", …}]}