# Grok Imagine Image 2.0 — Scenepond API

Model ID: `xai/grok-imagine-image/v2.0/text-to-image`

Model developer: xAI

Purpose: Text to image

Source page: https://open.scenepond.ai/en/models/xai%2Fgrok-imagine-image%2Fv2.0%2Ftext-to-image#api

Reviewed: 2026-10-01

Base URL: `https://scenepond-api-production.up.railway.app/v1`

Authenticate every request with Authorization: Bearer and your Scenepond API key. Keep the key on your server.

## Native task API

`POST /v1/tasks/fal`

### Minimum request

#### cURL

```bash
curl --fail-with-body -X POST "https://scenepond-api-production.up.railway.app/v1/tasks/fal" \
  -H "Authorization: Bearer $SCENEPOND_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "xai/grok-imagine-image/v2.0/text-to-image",
  "prompt": "A quiet lakeside at sunrise"
}
JSON
```

#### Python

```python
import os
import json
from urllib.parse import quote
from urllib.request import Request, urlopen

payload = json.loads("{\n  \"model\": \"xai/grok-imagine-image/v2.0/text-to-image\",\n  \"prompt\": \"A quiet lakeside at sunrise\"\n}")

request = Request(
    "https://scenepond-api-production.up.railway.app/v1/tasks/fal",
    headers={
        "Authorization": "Bearer " + os.environ["SCENEPOND_API_KEY"],
        "Content-Type": "application/json",
    },
    data=json.dumps(payload).encode("utf-8"),
    method="POST",
)
with urlopen(request) as response:
    result = json.load(response)
print(json.dumps(result, indent=2))
```

#### JavaScript

```javascript
const response = await fetch("https://scenepond-api-production.up.railway.app/v1/tasks/fal", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SCENEPOND_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "model": "xai/grok-imagine-image/v2.0/text-to-image",
  "prompt": "A quiet lakeside at sunrise"
})
});
if (!response.ok) throw new Error(`API error: ${response.status} ${await response.text()}`);
const result = await response.json();
console.log(result);
```

### Request parameters

- `model` — **Required**; `string`. Use this exact public model ID.
  - Constraints: `const = "xai/grok-imagine-image/v2.0/text-to-image"`

- `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: `"1:1"`
  - Constraints: `enum = ["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]`

- `prompt` — **Required**; `string`. Describe the subject, scene, and desired generation.
  - Constraints: `maxLength = 8000`

- `num_images` — **Optional**; `integer`. Number of images requested in this task.
  - Default: `1`
  - Constraints: `minimum = 1`; `maximum = 4`

- `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.

### Illustrative responses

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

#### Submission response

```json
{
  "id": "task_EXAMPLE",
  "task_id": "task_EXAMPLE",
  "status": "queued",
  "model": "xai/grok-imagine-image/v2.0/text-to-image",
  "created_at": 1700000000
}
```

#### Completed task status

```json
{
  "task_id": "task_EXAMPLE",
  "platform": "fal",
  "status": "SUCCESS",
  "progress": "100%",
  "fail_reason": "",
  "created_at": 1700000000,
  "finished_at": 1700000060
}
```

#### Artifact listing

```json
{
  "task_id": "task_EXAMPLE",
  "artifacts": [
    {
      "key": "image-1",
      "type": "image",
      "content_url": "https://scenepond-api-production.up.railway.app/v1/tasks/task_EXAMPLE/artifacts/image-1/content"
    }
  ]
}
```

### 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.

##### cURL

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

##### Python

```python
import os
import json
from urllib.parse import quote
from urllib.request import Request, urlopen

request = Request(
    "https://scenepond-api-production.up.railway.app/v1/tasks/" + quote(os.environ["SCENEPOND_TASK_ID"], safe="") + "",
    headers={
        "Authorization": "Bearer " + os.environ["SCENEPOND_API_KEY"],
        "Content-Type": "application/json",
    },
    method="GET",
)
with urlopen(request) as response:
    result = json.load(response)
print(json.dumps(result, indent=2))
```

##### JavaScript

```javascript
if (!process.env.SCENEPOND_TASK_ID) throw new Error("Set SCENEPOND_TASK_ID first");
const response = await fetch("https://scenepond-api-production.up.railway.app/v1/tasks/" + encodeURIComponent(process.env.SCENEPOND_TASK_ID) + "", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.SCENEPOND_API_KEY}`,
    "Content-Type": "application/json"
  }
});
if (!response.ok) throw new Error(`API error: ${response.status} ${await response.text()}`);
const result = await response.json();
console.log(result);
```

#### 3. Get the results

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

##### cURL

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

##### Python

```python
import os
import json
from urllib.parse import quote
from urllib.request import Request, urlopen

request = Request(
    "https://scenepond-api-production.up.railway.app/v1/tasks/" + quote(os.environ["SCENEPOND_TASK_ID"], safe="") + "/artifacts",
    headers={
        "Authorization": "Bearer " + os.environ["SCENEPOND_API_KEY"],
        "Content-Type": "application/json",
    },
    method="GET",
)
with urlopen(request) as response:
    result = json.load(response)
print(json.dumps(result, indent=2))
```

##### JavaScript

```javascript
if (!process.env.SCENEPOND_TASK_ID) throw new Error("Set SCENEPOND_TASK_ID first");
const response = await fetch("https://scenepond-api-production.up.railway.app/v1/tasks/" + encodeURIComponent(process.env.SCENEPOND_TASK_ID) + "/artifacts", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.SCENEPOND_API_KEY}`,
    "Content-Type": "application/json"
  }
});
if (!response.ok) throw new Error(`API error: ${response.status} ${await response.text()}`);
const result = await response.json();
console.log(result);
```

### 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.

## Sources

- [Provider model reference](https://fal.ai/models/fal-ai/xai/v2/text-to-image/api)