> ## 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 API: xAI Text-to-Image & Image-to-Image

> xAI image generation API for text-to-image and image-to-image generation with fast turnaround, flexible sizes, and prompt controls.

## Overview

The model ID remains `grok-image`. Use the preferred REST URLs below. The previous `/generateTask/grok-image` and `/statusTask/grok-image` URLs remain supported with the same parameters and pricing.

Grok Imagine Image is an xAI image model for text-to-image generation and multi-reference image-to-image workflows. Use this page when you are ready to call the API after trying the model in the APIXO playground.

| Capability | Value |
| - | - |
| Model ID | `grok-image` |
| Modes | `text-to-image`, `image-to-image` |
| Prompt length | 1-5000 characters |
| Reference images | 1-5 URLs for `image-to-image` |
| Aspect ratios | `1:1`, `3:2`, `2:3`, `16:9`, `9:16` for `text-to-image` |
| Output | 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` | Submit a generation task |
| `GET` | `/statusTask/grok-imagine-image?taskId={taskId}` | Poll task status and retrieve results |

All requests require your APIXO API key:

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

Submit requests also require:

```http theme={null}
Content-Type: application/json
```

## Copy-paste async quickstart

This minimal request submits a text-to-image task and returns a `taskId`.

```bash theme={null}
curl -X POST "https://api.apixo.ai/api/v1/generateTask/grok-imagine-image" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_type": "async",
    "input": {
      "mode": "text-to-image",
      "prompt": "a cozy cyberpunk cafe with neon lights",
      "aspect_ratio": "3:2"
    }
  }'
```

Successful response:

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

Save the `taskId`; you need it to poll for the final result.

## Poll for result

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

Processing response:

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

Success response:

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "success",
    "resultJson": "{\"resultUrls\":[\"https://file.apixo.ai/xxx.png\"]}",
    "createTime": 1767965610929,
    "completeTime": 1767965635929,
    "costTime": 25000
  }
}
```

Failed response:

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "failed",
    "failCode": "SensitiveContent",
    "failMsg": "Content was rejected by safety checks, please adjust the prompt",
    "createTime": 1767965610929,
    "completeTime": 1767965620132,
    "costTime": 9039
  }
}
```

Parse `resultJson` after `state` becomes `success`:

```javascript theme={null}
const payload = JSON.parse(data.resultJson);
const imageUrls = payload.resultUrls;
```

## Request body

### Text-to-image

```json theme={null}
{
  "request_type": "async",
  "input": {
    "mode": "text-to-image",
    "prompt": "a serene mountain landscape at dawn",
    "aspect_ratio": "16:9"
  }
}
```

### Image-to-image

```json theme={null}
{
  "request_type": "async",
  "input": {
    "mode": "image-to-image",
    "prompt": "blend these references into a cinematic portrait",
    "image_urls": [
      "https://example.com/subject.png",
      "https://example.com/style.png"
    ]
  }
}
```

## Parameters

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

Result delivery mode. Omit this field or use `async` for polling with `statusTask`, or use `callback` for webhook delivery.

**callback\_url** `string`

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

**input** `object` *required*

Grok Imagine Image input parameters.

**properties**

**mode** `string` *required*

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

**prompt** `string` *required*

Text prompt describing the desired image or edit. Supports 1-5000 characters. Empty prompts are rejected.

**aspect\_ratio** `string` (default: 1:1)

Output aspect ratio for `text-to-image`. Supported values: `1:1`, `3:2`, `2:3`, `16:9`, `9:16`. This parameter is not forwarded for `image-to-image`.

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

Reference image URLs. Required for `image-to-image`. Supports 1-5 URLs. Each URL must be public and each array item must be a non-empty string. Supported formats are JPG, JPEG, PNG, and WEBP, with a maximum size of 10 MB per image.

## Response format

### Submit task response

`POST /generateTask/grok-imagine-image` returns a task ID when the task is accepted:

**code** `integer`

API status code. `200` means the task was accepted.

**message** `string`

Human-readable status message.

**data.taskId** `string`

Unique task identifier used with the status endpoint.

### Status response fields

**taskId** `string`

Unique task identifier.

**state** `string`

Current task state: `pending`, `processing`, `success`, or `failed`.

**resultJson** `string`

JSON string containing the generated image URLs. Present when `state` is `success`.

**failCode** `string`

Machine-readable failure code. Present when `state` is `failed`.

**failMsg** `string`

Human-readable failure message. Present when `state` is `failed`.

**createTime** `integer`

Task creation timestamp in Unix milliseconds.

**completeTime** `integer`

Task completion timestamp in Unix milliseconds. Present after completion.

**costTime** `integer`

Processing duration in milliseconds. Present after completion.

## Webhook callback mode

Use callback mode when your backend should receive the final result automatically instead of polling.

```bash theme={null}
curl -X POST "https://api.apixo.ai/api/v1/generateTask/grok-imagine-image" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_type": "callback",
    "callback_url": "https://your-server.com/webhooks/apixo",
    "input": {
      "mode": "text-to-image",
      "prompt": "a clean product photo of wireless earbuds on soft stone",
      "aspect_ratio": "1:1"
    }
  }'
```

Callback delivery uses the same final payload shape as the status response. See [Webhooks](https://apixo.ai/docs/api-reference/webhooks.md) for delivery requirements and retry behavior.

## Billing

New non-LLM requests use **1 credit = `$0.001`**. Calculate the full amount, including billable quantity and add-ons, apply the applicable account discount, then round the request 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. See [credit conversion and rounding](https://apixo.ai/docs/pricing.md#credit-conversion-and-rounding).

The rates below match the main [API Pricing](https://apixo.ai/pricing/api) catalog's public base-price table updated on October 30, 2026. Check that page for current rates and any account discount before budgeting.

Text-to-image is billed once per request and returns two images by default. The request price covers those outputs. Image-to-image is billed per generated image.

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

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

For example, a text-to-image request that returns its default two images costs `$0.040` in total, before any account discount.

For current API rates in USD, see [API pricing](https://apixo.ai/pricing/api).

## Latency and polling

Actual latency may vary by prompt complexity, reference image access, queue load, and result storage time.

| Mode | Typical generation time | Recommended first poll | Poll interval |
| - | - | - | - |
| `text-to-image` | About 25s on average | 15s after task creation | 3s |
| `image-to-image` | About 25s on average | 15s after task creation | 3s |

> [!TIP]
>
> For high-concurrency production workloads, use callback mode to avoid frequent polling.

Result URLs are valid for 15 days. Download and store important outputs promptly.

Prompts can be written in English or Chinese. More specific scene, style, lighting, and composition details usually produce better results. Output is PNG by default; if you need transparency, describe that requirement in the prompt.

Rate limits and concurrency can vary by account, API key, and route. If you receive `429`, slow down requests and retry with backoff. For account-level details, see [System APIs](https://apixo.ai/docs/api-reference/system.md).

## Errors and troubleshooting

### HTTP errors

| Code | Meaning | What to do |
| - | - | - |
| `400` | Invalid request body, missing `mode`, missing `prompt`, invalid `aspect_ratio`, malformed `image_urls`, or inaccessible image URL | Fix the request before retrying |
| `401` | Missing or invalid API key | Check the `Authorization` header |
| `402` | Insufficient balance or quota | Add balance or switch account/key |
| `429` | Rate limit or concurrency limit reached | Retry with exponential backoff |
| `500` | Internal error or unknown task failure | Retry with backoff or contact support if it persists |
| `502` | Service or network error | Retry with backoff |

### Validation notes

| Parameter | Backend behavior |
| - | - |
| `input.mode` | Required for routing. Must be `text-to-image` or `image-to-image`. |
| `input.prompt` | Required string. Must not be empty and must not exceed 5000 characters. |
| `input.aspect_ratio` | Optional for `text-to-image`. Must be `1:1`, `3:2`, `2:3`, `16:9`, or `9:16` if provided. Defaults to `1:1` for `text-to-image`. |
| `input.image_urls` | Required and non-empty for `image-to-image`. Must be an array of strings and cannot contain more than 5 images. |

### Task failure codes

`failCode` identifies the task failure. Common values include:

| Fail code | Meaning | What to do |
| - | - | - |
| `PromptInvalid` | Prompt was invalid or rejected | Rewrite the prompt and retry |
| `SensitiveContent` | Prompt or input/output content was rejected by safety checks | Change the prompt or reference image |
| `ImageFormatIncorrect` | Reference image format could not be processed | Use a public, direct image URL in a common image format |
| `RateLimited` | A rate limit was reached | Retry with exponential backoff |
| `Timeout` | The task timed out | Retry later or use callback mode |
| `Unknown error` | An unknown task failure occurred | Retry with backoff or contact support with the `taskId` |

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

To animate an image after generation, use a successful `grok-image` task with [Grok Imagine Video](https://apixo.ai/docs/models/video/grok-imagine-video.md#image-to-video-from-a-grok-imagine-image-task). This creates a new video from an image result; it does not extend an existing video.

## MCP integration

The [complete model schema](https://apixo.ai/docs/models/schemas/image/grok-imagine-image.json) declares result decoding in `mcp.result` and supported file bindings in `mcp.attachments`. These are client integration metadata, not generation input parameters. Attachment paths: `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)
* [Generate Task](https://apixo.ai/docs/api-reference/generate-task.md)
* [Status Task](https://apixo.ai/docs/api-reference/status-task.md)
* [Webhooks](https://apixo.ai/docs/api-reference/webhooks.md)
* [Error Codes](https://apixo.ai/docs/api-reference/errors.md)
* [Parameter Specification](https://apixo.ai/docs/api-reference/parameters.md)
* [Routing Strategies](https://apixo.ai/docs/concepts/routing-strategies.md)
* [Try Grok Imagine Image in the APIXO Playground](https://apixo.ai/models/grok-image)
* [API pricing](https://apixo.ai/pricing/api)


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