> ## Documentation Index
> Fetch the complete documentation index at: https://apixo.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Grok Imagine Image 2.0 API: Image Generation & Editing

> Generate one image from text or edit images with up to five references using the Grok Imagine Image 2.0 API.

## Overview

Grok Imagine Image 2.0 supports text-to-image generation and image-to-image editing. Each successful task returns one image.

| Capability | Value |
| - | - |
| Model ID | `grok-imagine-image-2-0` |
| Modes | `text-to-image`, `image-to-image` |
| Prompt | Required for text-to-image; optional for image-to-image; up to 8,000 characters |
| Reference images | 1–5 URLs for image-to-image |
| Aspect ratios | `1:1`, `2:3`, `3:2`, `16:9`, `9:16`; image-to-image also supports `auto` |
| Output | One image URL in `resultJson.resultUrls` |

## Endpoint and authentication

Base URL:

```text theme={null}
https://api.apixo.ai/api/v1
```

| Method | Endpoint | Purpose |
| - | - | - |
| `POST` | `/generateTask/grok-imagine-image-2-0` | Submit a generation or editing task |
| `GET` | `/statusTask/grok-imagine-image-2-0?taskId={taskId}` | Poll task status and retrieve the result |

Include `Authorization: Bearer YOUR_API_KEY` on every request and `Content-Type: application/json` when submitting JSON.

## Copy-paste async quickstart

```bash theme={null}
curl -X POST "https://api.apixo.ai/api/v1/generateTask/grok-imagine-image-2-0" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_type": "async",
    "input": {
      "mode": "text-to-image",
      "prompt": "A small wooden cabin beside a lake at sunrise",
      "aspect_ratio": "16:9"
    }
  }'
```

An accepted task returns a task ID. Acceptance does not mean generation is complete.

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {"taskId": "task_12345678"}
}
```

## Image-to-image

Provide 1–5 publicly accessible reference URLs. The prompt is optional; include it to describe the desired edit. Omitting `aspect_ratio` uses `auto`.

```json theme={null}
{
  "request_type": "async",
  "input": {
    "mode": "image-to-image",
    "image_urls": ["https://example.com/reference.png"],
    "prompt": "Keep the subject and change the background to a snowy mountain",
    "aspect_ratio": "auto"
  }
}
```

## Parameters

**request\_type** `string` (default: async)

Result delivery mode. Supported values: `async`, `callback`. Omit this field or use `async` to poll for the result.

**callback\_url** `string`

Required when `request_type` is `callback`. Provide a public HTTPS URL that receives the final task payload. See [Webhooks](https://apixo.ai/docs/api-reference/webhooks.md).

**input** `object` *required*

Grok Imagine Image 2.0 input parameters.

**properties**

**mode** `string` *required*

Generation mode. Supported values: `text-to-image`, `image-to-image`.

**prompt** `string`

Required and non-blank for `text-to-image`; optional for `image-to-image`. Maximum 8,000 characters. For image editing, omit it or provide an edit instruction.

**image\_urls** `string[]`

Required for `image-to-image`: 1–5 publicly accessible image URLs, each a non-empty string. Preserve the intended reference order. Ignored for `text-to-image`.

**aspect\_ratio** `string`

Output aspect ratio. Supported values: `1:1`, `2:3`, `3:2`, `16:9`, `9:16`, `auto`. The value `auto` is supported only for `image-to-image`. Defaults to `1:1` for `text-to-image` and `auto` for `image-to-image`.

## Poll for result

```bash theme={null}
curl "https://api.apixo.ai/api/v1/statusTask/grok-imagine-image-2-0?taskId=task_12345678" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Continue polling while `data.state` is `pending` or `processing`. Stop at `success` or `failed`.

Successful response:

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "success",
    "resultJson": "{\"resultUrls\":[\"https://example.com/generated.png\"]}",
    "createTime": 1793318400000,
    "completeTime": 1793318440000,
    "costTime": 40000
  }
}
```

`resultJson` is a JSON **string**, so parse it before reading the image URL:

```javascript theme={null}
const { resultUrls } = JSON.parse(response.data.resultJson);
const imageUrl = resultUrls[0];
```

### Status response fields

| Field in `data` | Type | Description |
| - | - | - |
| `taskId` | string | Task identifier returned at submission |
| `state` | string | `pending`, `processing`, `success`, or `failed` |
| `resultJson` | string | JSON string containing `resultUrls` on success |
| `failCode` | string | Failure code when the task fails |
| `failMsg` | string | Failure message when the task fails |
| `createTime` | integer | Task creation timestamp in Unix milliseconds |
| `completeTime` | integer | Task completion timestamp in Unix milliseconds, when available |
| `costTime` | integer | Total task duration in milliseconds, when available |

### Failed task example

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "failed",
    "failCode": "500",
    "failMsg": "Image generation failed."
  }
}
```

A successful status lookup can describe a failed generation. Check `data.state`, and retain the task ID when requesting support.

## Webhook callback mode

Set `request_type` to `callback` and provide `callback_url`; the model input is unchanged.

```json theme={null}
{
  "request_type": "callback",
  "callback_url": "https://your-server.com/webhooks/apixo",
  "input": {
    "mode": "text-to-image",
    "prompt": "An illustrated travel poster of a quiet seaside town",
    "aspect_ratio": "2:3"
  }
}
```

Webhook delivery uses the same public final task fields as polling. See [Webhooks](https://apixo.ai/docs/api-reference/webhooks.md) for delivery and retry requirements.

## Billing

Both modes cost **\$0.04 per generated image**, with one output image per successful task. Reference images do not add an input charge. Failed tasks are refunded.

| Mode | APIXO price | Market display reference |
| - | - | - |
| `text-to-image` | `$0.040 / image` | `$0.060 / image` |
| `image-to-image` | `$0.040 / image` | `$0.060 / image` |

The market display reference is a comparison value and does not affect the amount charged.

New non-LLM requests use **1 credit = `$0.001`**. Calculate the full request amount, apply any applicable account discount, then round the total upward to the next whole credit. Agreed fixed unit prices retain their precision and replace the standard price and discount; final rounding still applies. Without discounts, one successful task costs 40 credits. See [credit conversion and rounding](https://apixo.ai/docs/pricing.md#credit-conversion-and-rounding) and [current API prices](https://apixo.ai/pricing/api).

## Latency and polling

Generation time varies with prompt complexity, image access, and queue load. The following intervals are client recommendations, not latency guarantees.

| Mode | Recommended first poll | Poll interval |
| - | - | - |
| `text-to-image` | 10 seconds after task creation | 3–5 seconds, with backoff |
| `image-to-image` | 10 seconds after task creation | 3–5 seconds, with backoff |

Use callback mode for completion notifications. Stop polling at a terminal state, and save important outputs promptly.

## Errors and troubleshooting

* Missing `mode`, a missing or blank text-to-image `prompt`, an overlong prompt, an invalid aspect ratio, or an invalid image-to-image reference list causes a validation error.
* Use reference URLs that are accessible without authentication. If generation fails, inspect `failCode` and `failMsg`.
* Check your API key for authentication errors and your balance for insufficient-balance errors.
* Back off on rate limits. Do not resubmit an accepted task just because it is still processing; continue polling its task ID.

See [Error Codes](https://apixo.ai/docs/api-reference/errors.md) for shared API errors.

## MCP integration

The [complete model schema](https://apixo.ai/docs/models/schemas/image/grok-imagine-image-2-0.json) declares result decoding in `mcp.result` and supported file bindings in `mcp.attachments`. These are client integration metadata, not generation input parameters. Attachment path: `image_urls`. Preserve the user's file order. Model parameter validation remains on the API.

## Related links

* [Generation API Overview](https://apixo.ai/docs/models.md)
* [Image Models](https://apixo.ai/docs/models/image)
* [Grok Image](https://apixo.ai/docs/models/image/grok-image.md)
* [Webhooks](https://apixo.ai/docs/api-reference/webhooks.md)
* [Pricing](https://apixo.ai/docs/pricing.md)
* [Try Grok Imagine Image 2.0](https://apixo.ai/models/grok-imagine-image-2-0)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.