> ## Documentation Index
> Fetch the complete documentation index at: https://apidoc.cometapi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Edit images with Grok
> Edit one or more images with Grok by sending image URLs or data URIs in a JSON request.
Use this route to edit one or more images with Grok image models. The request body uses `application/json`.
## Provide image input
* Send exactly one of `image` or `images`.
* Use `image` for one source image.
* Use `images` for two or three source images.
* In each image object, use `url` for a public URL or data URI. `image_url` is a compatibility alias for `url`.
* Use `aspect_ratio` to control the output shape for multi-image edits.
Choose a Grok image model ID from the [Models page](/overview/models). The API examples use `grok-imagine-image-quality`.
Send Grok image edit requests as JSON. Multipart form data does not represent this request shape.
The OpenAI SDK `images.edit()` method sends multipart form data. Use a direct HTTP request for Grok JSON image edits.
For provider parameter details, see the [xAI image editing guide](https://docs.x.ai/developers/model-capabilities/images/editing).
## OpenAPI
````yaml api/openapi/image/grok/post-image-editing.openapi.json POST /v1/images/edits
openapi: 3.1.0
info:
title: Grok Image Editing API
version: 1.0.0
description: Edit images with Grok image models through CometAPI.
servers:
- url: https://api.cometapi.com
security:
- bearerAuth: []
paths:
/v1/images/edits:
post:
summary: Edit images with Grok
operationId: grok_image_editing
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- model
- prompt
oneOf:
- required:
- image
- required:
- images
properties:
model:
type: string
description: >-
The Grok image model ID. See the [Models
page](/overview/models) for available model IDs.
enum:
- grok-imagine-image
- grok-imagine-image-quality
example: grok-imagine-image-quality
prompt:
type: string
minLength: 1
description: A text instruction that describes the requested edit.
example: >-
Replace the daytime sky with a soft sunset and preserve the
building
image:
$ref: '#/components/schemas/ImageInput'
description: One source image. Use this field instead of `images`.
images:
type: array
minItems: 2
maxItems: 3
description: >-
Two or three source images. Use this field instead of
`image`.
items:
$ref: '#/components/schemas/ImageInput'
'n':
type: integer
minimum: 1
maximum: 10
default: 1
description: >-
The number of edited images to generate. Use an integer from
1 through 10.
aspect_ratio:
type: string
enum:
- '1:1'
- '3:4'
- '4:3'
- '16:9'
- '2:3'
- '3:2'
- '9:19.5'
- 19.5:9
- '9:20'
- '20:9'
- '1:2'
description: The output shape for a multi-image edit.
example: '16:9'
resolution:
type: string
enum:
- 1k
- 2k
description: The requested output resolution.
example: 1k
response_format:
type: string
enum:
- url
- b64_json
default: url
description: >-
The image representation in each response item. Use `url`
for a temporary download URL or `b64_json` for
Base64-encoded image bytes.
examples:
image-url:
summary: Image URL
value:
model: grok-imagine-image-quality
prompt: >-
Replace the daytime sky with a soft sunset and preserve the
building
image:
url: https://example.com/building.png
response_format: url
data-uri:
summary: Data URI
value:
model: grok-imagine-image-quality
prompt: Change the vase to cobalt blue and preserve the flowers
image:
url: data:image/png;base64,
resolution: 2k
response_format: b64_json
multiple-images:
summary: Multiple images
value:
model: grok-imagine-image-quality
prompt: >-
Place the ceramic lamp from the second image on the desk in
the first image
images:
- url: https://example.com/desk.png
- url: https://example.com/lamp.png
aspect_ratio: '16:9'
resolution: 1k
response_format: url
responses:
'200':
description: The edited image results.
content:
application/json:
schema:
$ref: '#/components/schemas/ImageResponse'
example:
data:
- url: https://cdn.example.com/edited-image.jpg
mime_type: image/jpeg
usage:
cost_in_usd_ticks: 600000000
x-codeSamples:
- lang: Shell
label: Image URL
source: |-
curl https://api.cometapi.com/v1/images/edits \
-H "Authorization: Bearer $COMETAPI_KEY" \
-H "Content-Type: application/json" \
--data-binary '{
"model": "grok-imagine-image-quality",
"prompt": "Replace the daytime sky with a soft sunset and preserve the building",
"image": {
"url": "https://example.com/building.png"
},
"response_format": "url"
}'
- lang: Python
label: Image URL
source: |-
import os
import requests
response = requests.post(
"https://api.cometapi.com/v1/images/edits",
headers={
"Authorization": f"Bearer {os.environ['COMETAPI_KEY']}",
"Content-Type": "application/json",
},
json={
"model": "grok-imagine-image-quality",
"prompt": (
"Replace the daytime sky with a soft sunset and preserve the building"
),
"image": {"url": "https://example.com/building.png"},
"response_format": "url",
},
timeout=180,
)
response.raise_for_status()
print(response.json())
- lang: JavaScript
label: Image URL
source: >-
const response = await fetch(
"https://api.cometapi.com/v1/images/edits",
{
method: "POST",
headers: {
Authorization: `Bearer ${process.env.COMETAPI_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "grok-imagine-image-quality",
prompt:
"Replace the daytime sky with a soft sunset and preserve the building",
image: { url: "https://example.com/building.png" },
response_format: "url",
}),
},
);
if (!response.ok) throw new Error(`Request failed:
${response.status}`);
console.log(await response.json());
- lang: Shell
label: Data URI
source: |-
curl https://api.cometapi.com/v1/images/edits \
-H "Authorization: Bearer $COMETAPI_KEY" \
-H "Content-Type: application/json" \
--data-binary '{
"model": "grok-imagine-image-quality",
"prompt": "Change the vase to cobalt blue and preserve the flowers",
"image": {
"url": "data:image/png;base64,"
},
"resolution": "2k",
"response_format": "b64_json"
}'
- lang: Python
label: Data URI
source: |-
import os
import requests
response = requests.post(
"https://api.cometapi.com/v1/images/edits",
headers={
"Authorization": f"Bearer {os.environ['COMETAPI_KEY']}",
"Content-Type": "application/json",
},
json={
"model": "grok-imagine-image-quality",
"prompt": "Change the vase to cobalt blue and preserve the flowers",
"image": {"url": "data:image/png;base64,"},
"resolution": "2k",
"response_format": "b64_json",
},
timeout=180,
)
response.raise_for_status()
print(response.json())
- lang: JavaScript
label: Data URI
source: >-
const response = await fetch(
"https://api.cometapi.com/v1/images/edits",
{
method: "POST",
headers: {
Authorization: `Bearer ${process.env.COMETAPI_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "grok-imagine-image-quality",
prompt: "Change the vase to cobalt blue and preserve the flowers",
image: { url: "data:image/png;base64," },
resolution: "2k",
response_format: "b64_json",
}),
},
);
if (!response.ok) throw new Error(`Request failed:
${response.status}`);
console.log(await response.json());
- lang: Shell
label: Multiple images
source: |-
curl https://api.cometapi.com/v1/images/edits \
-H "Authorization: Bearer $COMETAPI_KEY" \
-H "Content-Type: application/json" \
--data-binary '{
"model": "grok-imagine-image-quality",
"prompt": "Place the ceramic lamp from the second image on the desk in the first image",
"images": [
{"url": "https://example.com/desk.png"},
{"url": "https://example.com/lamp.png"}
],
"aspect_ratio": "16:9",
"resolution": "1k",
"response_format": "url"
}'
- lang: Python
label: Multiple images
source: |-
import os
import requests
response = requests.post(
"https://api.cometapi.com/v1/images/edits",
headers={
"Authorization": f"Bearer {os.environ['COMETAPI_KEY']}",
"Content-Type": "application/json",
},
json={
"model": "grok-imagine-image-quality",
"prompt": (
"Place the ceramic lamp from the second image on the desk "
"in the first image"
),
"images": [
{"url": "https://example.com/desk.png"},
{"url": "https://example.com/lamp.png"},
],
"aspect_ratio": "16:9",
"resolution": "1k",
"response_format": "url",
},
timeout=180,
)
response.raise_for_status()
print(response.json())
- lang: JavaScript
label: Multiple images
source: >-
const response = await fetch(
"https://api.cometapi.com/v1/images/edits",
{
method: "POST",
headers: {
Authorization: `Bearer ${process.env.COMETAPI_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "grok-imagine-image-quality",
prompt:
"Place the ceramic lamp from the second image on the desk in the first image",
images: [
{ url: "https://example.com/desk.png" },
{ url: "https://example.com/lamp.png" },
],
aspect_ratio: "16:9",
resolution: "1k",
response_format: "url",
}),
},
);
if (!response.ok) throw new Error(`Request failed:
${response.status}`);
console.log(await response.json());
components:
schemas:
ImageInput:
description: >-
A source image represented by `url` or the compatibility alias
`image_url`.
oneOf:
- type: object
additionalProperties: false
required:
- url
properties:
url:
type: string
description: >-
A public image URL or a data URI such as
`data:image/png;base64,`.
example: https://example.com/source.png
- type: object
additionalProperties: false
required:
- image_url
properties:
image_url:
type: string
description: >-
A compatibility alias for `url`. Supply a public image URL or a
data URI.
example: https://example.com/source.png
ImageResponse:
type: object
additionalProperties: false
required:
- data
- usage
properties:
data:
type: array
minItems: 1
description: The edited images.
items:
type: object
additionalProperties: false
required:
- mime_type
oneOf:
- required:
- url
- required:
- b64_json
properties:
url:
type: string
format: uri
description: A temporary image URL when `response_format` is `url`.
b64_json:
type: string
description: >-
Base64-encoded image bytes when `response_format` is
`b64_json`.
mime_type:
type: string
description: The media type of the edited image.
example: image/jpeg
usage:
type: object
required:
- cost_in_usd_ticks
additionalProperties: false
description: Usage details for the request.
properties:
cost_in_usd_ticks:
type: integer
minimum: 0
description: The request cost in USD ticks.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API key
description: Use your CometAPI API key as the bearer value.
````