Grok Imagine Image 2.0

Model IDxai/grok-imagine-image/v2.0/edit

xAI
Image to image
Image

Edit a reference image with a text instruction.

Call this model API quickstart

Overview

Model developer: xAI
API channel: fal.ai
Resolution: 1k · 2k
Aspect ratios: 14 aspect ratios
Supported protocols: fal-task

Call this model

Create an API key, add account credit, and confirm this model is available to your key before sending a request.

LLM index

Copy the complete model reference, including every published protocol, for your AI assistant.

API protocol

POST/v1/tasks/fal

Request parameters

Request parameters
Parameter	Required	Type	Description
`model`	Required	`string`	Use this exact public model ID. Constraints const = "xai/grok-imagine-image/v2.0/edit"
`output_format`	Optional	`string`	Encoding format of the generated image. Default `"jpeg"` Constraints enum = ["jpeg","png","webp"]
`quality`	Optional	`string`	Requested image quality tier. Default `"medium"` Constraints enum = ["low","medium"]
`resolution`	Optional	`string`	Output resolution. Values are case-sensitive and specific to this model. Default `"1k"` Constraints enum = ["1k","2k"]
`aspect_ratio`	Optional	`string`	Requested output width-to-height ratio. Default `"auto"` Constraints enum = ["auto","2:1","20:9","19.5:9","16:9","4:3","3:2","1:1","2:3","3:4","9:16","9:19.5","9:20","1:2"]
`sync_mode`	Optional	`boolean`	Only false is supported. This gateway submits asynchronous tasks. Default `false` Constraints enum = [false]
`num_images`	Optional	`integer`	Number of images requested in this task. Default `1` Constraints minimum = 1 maximum = 4
`image_urls`	Conditional	`array<string>`	Reference images to edit. Supply a nonempty array of HTTP(S) URLs or base64 image data URLs. Required unless a reference image is supplied through images, image, or input_reference. Constraints maxItems = 5
`prompt`	Required	`string`	Describe the subject, scene, and desired generation. Constraints maxLength = 8000
`n`	Optional	`integer`	Alias for num_images. Do not supply a conflicting image count. Default `1` Constraints minimum = 1 maximum = 4
`size`	Optional	`string`	Alias for image_size or resolution. Prefer the exact native value in this table; pixel-size aliases may not match case-sensitive resolution values.
`parameters`	Optional	`object`	Alternative container for the native parameters in this table. Do not repeat a setting with a different value.
`metadata`	Optional	`object`	Alternative container: place native parameters inside metadata.parameters.
`images`	Optional	`array<string>`	Alternative to image_urls. Every supplied item is a reference image to edit. Constraints maxItems = 5
`image`	Optional	`string \| array<string>`	Alternative reference image alias. Do not combine it with native reference fields or input_reference.
`input_reference`	Optional	`string \| array<string>`	Alternative reference image alias. Do not combine it with native reference fields or image.

Request notes

Authenticate every request with Authorization: Bearer and your Scenepond API key. Keep the key on your server.
Parameter values are case-sensitive. Missing or null settings use documented defaults when available; valid zero and false values are retained.
The parameter table uses native names at the JSON top level. The same settings can be placed in parameters or metadata.parameters; unknown nested settings and conflicting duplicate values are rejected.
Task submission returns a queued task, not the generated media. Poll status, then list artifacts after SUCCESS.
Do not automatically resubmit a timed-out POST. Preserve the returned task ID and inspect task status before creating another billable task.
Defaults and limits follow this gateway and the linked provider schema. Settings may change after a provider or gateway update.
Replace example.com with your own accessible reference image. Supply either native reference fields or images/input_reference aliases, never both.

Minimum request

1curl --fail-with-body -X POST "https://scenepond-api-production.up.railway.app/v1/tasks/fal" \
2  -H "Authorization: Bearer $SCENEPOND_API_KEY" \
3  -H "Content-Type: application/json" \
4  --data-binary @- <<'JSON'
5{
6  "model": "xai/grok-imagine-image/v2.0/edit",
7  "image_urls": [
8    "https://example.com/reference.png"
9  ],
10  "prompt": "A quiet lakeside at sunrise"
11}
12JSON

Run this example in a shell with cURL installed. Set SCENEPOND_API_KEY before running.

Illustrative responses

Response examples show the structure only. IDs, URLs, and values are placeholders.

Submission response

1{
2  "id": "task_EXAMPLE",
3  "task_id": "task_EXAMPLE",
4  "status": "queued",
5  "model": "xai/grok-imagine-image/v2.0/edit",
6  "created_at": 1700000000
7}

Completed task status

1{
2  "task_id": "task_EXAMPLE",
3  "platform": "fal",
4  "status": "SUCCESS",
5  "progress": "100%",
6  "fail_reason": "",
7  "created_at": 1700000000,
8  "finished_at": 1700000060
9}

Artifact listing

1{
2  "task_id": "task_EXAMPLE",
3  "artifacts": [
4    {
5      "key": "image-1",
6      "type": "image",
7      "content_url": "https://scenepond-api-production.up.railway.app/v1/tasks/task_EXAMPLE/artifacts/image-1/content"
8    }
9  ]
10}

Follow-up requests

2. Check task status

Set SCENEPOND_TASK_ID to task_id. Poll every few seconds until SUCCESS or FAILURE. Status includes progress and fail_reason, but no media.

1curl --fail-with-body -X GET "https://scenepond-api-production.up.railway.app/v1/tasks/$SCENEPOND_TASK_ID" \
2  -H "Authorization: Bearer $SCENEPOND_API_KEY"

Run this example in a shell with cURL installed. Set SCENEPOND_API_KEY before running.

3. Get the results

After SUCCESS, list artifacts. Use each returned content_url to download the media with authorization; treat signed URLs as private.

1curl --fail-with-body -X GET "https://scenepond-api-production.up.railway.app/v1/tasks/$SCENEPOND_TASK_ID/artifacts" \
2  -H "Authorization: Bearer $SCENEPOND_API_KEY"

Run this example in a shell with cURL installed. Set SCENEPOND_API_KEY before running.

Use it in your application

Use the task API in your application to submit generation requests and retrieve results by task ID.

API documentation

Model access and request limits depend on your account, API key, and service configuration.

Pricing

Image generation unit priceUSD 0.04 – 0.08 / imageReference image unit priceUSD 0.01 / unitPrices vary by specifications · 4 tiers

Prices by specification

Output resolution: 1k · Output image quality: low

Image generation unit price

USD 0.04 / image

Reference image unit price

USD 0.01 / unit

Output resolution: 1k · Output image quality: medium

Image generation unit price

USD 0.06 / image

Reference image unit price

USD 0.01 / unit

Output resolution: 2k · Output image quality: low

Image generation unit price

USD 0.06 / image

Reference image unit price

USD 0.01 / unit

Output resolution: 2k · Output image quality: medium

Image generation unit price

USD 0.08 / image

Reference image unit price

USD 0.01 / unit

Applicable conditions	Image generation unit price	Reference image unit price
Output resolution: 1k · Output image quality: low	USD 0.04 / image	USD 0.01 / unit
Output resolution: 1k · Output image quality: medium	USD 0.06 / image	USD 0.01 / unit
Output resolution: 2k · Output image quality: low	USD 0.06 / image	USD 0.01 / unit
Output resolution: 2k · Output image quality: medium	USD 0.08 / image	USD 0.01 / unit

Get an API key Add funds

Prices depend on model settings. Usage records show recorded deductions; asynchronous task charges may be adjusted after completion.

Call this model

Create an API key, add account credit, and confirm this model is available to your key before sending a request.

LLM index

Copy the complete model reference, including every published protocol, for your AI assistant.

API protocol

POST/v1/tasks/fal

Request parameters

Request parameters
Parameter	Required	Type	Description
`model`	Required	`string`	Use this exact public model ID. Constraints const = "xai/grok-imagine-image/v2.0/edit"
`output_format`	Optional	`string`	Encoding format of the generated image. Default `"jpeg"` Constraints enum = ["jpeg","png","webp"]
`quality`	Optional	`string`	Requested image quality tier. Default `"medium"` Constraints enum = ["low","medium"]
`resolution`	Optional	`string`	Output resolution. Values are case-sensitive and specific to this model. Default `"1k"` Constraints enum = ["1k","2k"]
`aspect_ratio`	Optional	`string`	Requested output width-to-height ratio. Default `"auto"` Constraints enum = ["auto","2:1","20:9","19.5:9","16:9","4:3","3:2","1:1","2:3","3:4","9:16","9:19.5","9:20","1:2"]
`sync_mode`	Optional	`boolean`	Only false is supported. This gateway submits asynchronous tasks. Default `false` Constraints enum = [false]
`num_images`	Optional	`integer`	Number of images requested in this task. Default `1` Constraints minimum = 1 maximum = 4
`image_urls`	Conditional	`array<string>`	Reference images to edit. Supply a nonempty array of HTTP(S) URLs or base64 image data URLs. Required unless a reference image is supplied through images, image, or input_reference. Constraints maxItems = 5
`prompt`	Required	`string`	Describe the subject, scene, and desired generation. Constraints maxLength = 8000
`n`	Optional	`integer`	Alias for num_images. Do not supply a conflicting image count. Default `1` Constraints minimum = 1 maximum = 4
`size`	Optional	`string`	Alias for image_size or resolution. Prefer the exact native value in this table; pixel-size aliases may not match case-sensitive resolution values.
`parameters`	Optional	`object`	Alternative container for the native parameters in this table. Do not repeat a setting with a different value.
`metadata`	Optional	`object`	Alternative container: place native parameters inside metadata.parameters.
`images`	Optional	`array<string>`	Alternative to image_urls. Every supplied item is a reference image to edit. Constraints maxItems = 5
`image`	Optional	`string \| array<string>`	Alternative reference image alias. Do not combine it with native reference fields or input_reference.
`input_reference`	Optional	`string \| array<string>`	Alternative reference image alias. Do not combine it with native reference fields or image.

Request notes

Authenticate every request with Authorization: Bearer and your Scenepond API key. Keep the key on your server.
Parameter values are case-sensitive. Missing or null settings use documented defaults when available; valid zero and false values are retained.
The parameter table uses native names at the JSON top level. The same settings can be placed in parameters or metadata.parameters; unknown nested settings and conflicting duplicate values are rejected.
Task submission returns a queued task, not the generated media. Poll status, then list artifacts after SUCCESS.
Do not automatically resubmit a timed-out POST. Preserve the returned task ID and inspect task status before creating another billable task.
Defaults and limits follow this gateway and the linked provider schema. Settings may change after a provider or gateway update.
Replace example.com with your own accessible reference image. Supply either native reference fields or images/input_reference aliases, never both.

Minimum request

1curl --fail-with-body -X POST "https://scenepond-api-production.up.railway.app/v1/tasks/fal" \
2  -H "Authorization: Bearer $SCENEPOND_API_KEY" \
3  -H "Content-Type: application/json" \
4  --data-binary @- <<'JSON'
5{
6  "model": "xai/grok-imagine-image/v2.0/edit",
7  "image_urls": [
8    "https://example.com/reference.png"
9  ],
10  "prompt": "A quiet lakeside at sunrise"
11}
12JSON

Run this example in a shell with cURL installed. Set SCENEPOND_API_KEY before running.

Illustrative responses

Response examples show the structure only. IDs, URLs, and values are placeholders.

Submission response

1{
2  "id": "task_EXAMPLE",
3  "task_id": "task_EXAMPLE",
4  "status": "queued",
5  "model": "xai/grok-imagine-image/v2.0/edit",
6  "created_at": 1700000000
7}

Completed task status

1{
2  "task_id": "task_EXAMPLE",
3  "platform": "fal",
4  "status": "SUCCESS",
5  "progress": "100%",
6  "fail_reason": "",
7  "created_at": 1700000000,
8  "finished_at": 1700000060
9}

Artifact listing

1{
2  "task_id": "task_EXAMPLE",
3  "artifacts": [
4    {
5      "key": "image-1",
6      "type": "image",
7      "content_url": "https://scenepond-api-production.up.railway.app/v1/tasks/task_EXAMPLE/artifacts/image-1/content"
8    }
9  ]
10}

Follow-up requests

2. Check task status

Set SCENEPOND_TASK_ID to task_id. Poll every few seconds until SUCCESS or FAILURE. Status includes progress and fail_reason, but no media.

1curl --fail-with-body -X GET "https://scenepond-api-production.up.railway.app/v1/tasks/$SCENEPOND_TASK_ID" \
2  -H "Authorization: Bearer $SCENEPOND_API_KEY"

Run this example in a shell with cURL installed. Set SCENEPOND_API_KEY before running.

3. Get the results

After SUCCESS, list artifacts. Use each returned content_url to download the media with authorization; treat signed URLs as private.

1curl --fail-with-body -X GET "https://scenepond-api-production.up.railway.app/v1/tasks/$SCENEPOND_TASK_ID/artifacts" \
2  -H "Authorization: Bearer $SCENEPOND_API_KEY"

Run this example in a shell with cURL installed. Set SCENEPOND_API_KEY before running.

Pricing

Image generation unit priceUSD 0.04 – 0.08 / imageReference image unit priceUSD 0.01 / unitPrices vary by specifications · 4 tiers

Prices by specification

Output resolution: 1k · Output image quality: low

Image generation unit price

USD 0.04 / image

Reference image unit price

USD 0.01 / unit

Output resolution: 1k · Output image quality: medium

Image generation unit price

USD 0.06 / image

Reference image unit price

USD 0.01 / unit

Output resolution: 2k · Output image quality: low

Image generation unit price

USD 0.06 / image

Reference image unit price

USD 0.01 / unit

Output resolution: 2k · Output image quality: medium

Image generation unit price

USD 0.08 / image

Reference image unit price

USD 0.01 / unit

Applicable conditions	Image generation unit price	Reference image unit price
Output resolution: 1k · Output image quality: low	USD 0.04 / image	USD 0.01 / unit
Output resolution: 1k · Output image quality: medium	USD 0.06 / image	USD 0.01 / unit
Output resolution: 2k · Output image quality: low	USD 0.06 / image	USD 0.01 / unit
Output resolution: 2k · Output image quality: medium	USD 0.08 / image	USD 0.01 / unit

Prices depend on model settings. Usage records show recorded deductions; asynchronous task charges may be adjusted after completion.