---
title: "Edit an image based on a prompt. This is the endpoint for making edit requests to image generation models."
method: POST
path: "/v1/images/edits"
tags: ["v1"]
---

# Edit an image based on a prompt. This is the endpoint for making edit requests to image generation models.

`POST /v1/images/edits`

## Request body

- EditImageRequest — Request for editing image
  - `aspect_ratio` '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' | 'auto' — Aspect ratio for image generation. Only supported by grok-imagine models.
  - `image` ImageUrl — 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` string, nullable — 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.
  - `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.
    - `file_id` string, nullable — 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.
  - `model` string, nullable — Model to be used.
  - `n` integer, nullable — Number of image edits to be generated.
  - `prompt` string, required — Prompt for image editing.
  - `resolution` '1k' | '2k' — Resolution for image generation. Only supported by grok-imagine models.
  - `response_format` string, nullable — 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.
  - `storage_options` StorageOptions — 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` integer, nullable — Seconds from now until the file auto-expires. Maximum 2592000 (30 days). If omitted, the file does not expire.
    - `filename` string, required — Filename for the stored file.
    - `public_url` union — Accepts either `true` (create public URL with defaults) or a configuration object with explicit options. **Variant order matters for `#[serde(untagged)]`:** `Flag` must come before `Options` so that JSON `true`/`false` match `Flag` rather than falling through to the object variant. **Serialization note:** Proto→REST readback always constructs `Options(...)`, never `Flag`, so responses always emit the object form. `Flag` only appears on the deserialization (request) path.
      - boolean — `true` = create public URL with default options (no independent expiry). `false` = no public URL (equivalent to omitting the field).
      - PublicUrlOptions — Configuration for creating a public URL alongside file storage.
        - `expires_after` integer, nullable — Seconds from now until the public URL expires. Must be between 3600 (1 hour) and 2592000 (30 days). If omitted and the file has a TTL (`expires_after` on the file), the public URL inherits the file's expiry. If omitted and the file has no TTL, the public URL remains valid indefinitely until the file is deleted or the URL is explicitly revoked via `POST /v1/files/{file_id}/public-url/revoke`.
  - `user` string, nullable — A unique identifier representing your end-user, which can help xAI to monitor and detect abuse.

## Response `200`

Success

- GeneratedImageResponse — Image generation response for `/v1/image/generations` endpoint
  - `data` GeneratedImage[], required — A list of generated image objects.
    - `b64_json` string, nullable — A base64-encoded string representation of the generated image (without the data-URI prefix), if `b64_json` is specified as `response_format` in the request.
    - `file_output` FileOutput — Information about a generated file stored in the Files API.
      - `expires_at` integer, nullable — Unix timestamp (seconds) when the stored file expires and will be automatically deleted. Only present when the file has an expiration.
      - `file_id` string, required — Files API file_id of the stored file.
      - `filename` string, required — Filename of the stored file.
      - `public_url` string, nullable — Public URL for the stored file. Only present when the request included `storage_options.public_url` and creation succeeded.
      - `public_url_error` string, nullable — Human-readable error when `storage_options.public_url` was set but public URL creation failed. The file was stored successfully.
      - `public_url_expires_at` integer, nullable — Unix timestamp (seconds) when the public URL expires. Present when the public URL has an expiry, either from an explicit `expires_after` in the request or inherited from the file's TTL.
    - `mime_type` string, nullable — The MIME type of the generated image (e.g. `image/png`, `image/jpeg`, `image/webp`).
    - `storage_error` string, nullable — Human-readable error when `storage_options` was set but the upload failed. Absent on success or when storage was not requested.
    - `url` string, nullable — A url to the generated image, if `response_format` is not specified or with `url` in the request.
  - `usage` MediaUsage — Billing and cost information for media generation requests (image and video). The optional token fields follow the OpenAI Images API shape (`input_tokens` / `output_tokens` / `total_tokens` with per-side detail objects) and are populated only for image models with token-based usage reporting. They are omitted entirely for models billed per image and for video requests.
    - `cost_in_usd_ticks` integer, required — The cost of this request expressed in USD ticks. One USD cent equals 100,000,000 ticks, so one US dollar equals 10,000,000,000 ticks.
    - `input_tokens` integer, nullable — Total input tokens: prompt text tokens + input image tokens (the sum of `input_tokens_details`, where `cached_tokens` is a subset of `text_tokens`, not additive).
    - `input_tokens_details` MediaInputTokensDetails — Breakdown of media generation input tokens.
      - `cached_tokens` integer, required — Text tokens served from cache from previous requests (a subset of `text_tokens`).
      - `image_tokens` integer, required — Input image tokens, as reported by the image engine.
      - `text_tokens` integer, required — Prompt text tokens consumed by the prompt-rewriting (upsampler) LLM, including any served from cache.
    - `output_tokens` integer, nullable — Total output tokens: rewritten-prompt text tokens + reasoning tokens + generated image tokens (the sum of `output_tokens_details`).
    - `output_tokens_details` MediaOutputTokensDetails — Breakdown of media generation output tokens.
      - `image_tokens` integer, required — Generated image tokens, as reported by the image engine.
      - `reasoning_tokens` integer, required — Reasoning (thinking) tokens generated by the prompt-rewriting (upsampler) LLM.
      - `text_tokens` integer, required — Rewritten-prompt text tokens generated by the prompt-rewriting (upsampler) LLM, excluding reasoning tokens.
    - `total_tokens` integer, nullable — Total tokens (input + output).

## Other responses

- `400` — Bad request. The request is invalid or an invalid API key is provided.
- `422` — Unprocessable Entity. There are missing fields in the request body.

---

[API](https://skmtc.net/x/apis/xai-s-rest-api.md) · [All operations](https://skmtc.net/x/apis/xai-s-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/x/xai-s-rest-api/versions/8f6014272113/schema)