xAI

Grok Imagine

grok-imagine/image-to-image

xAI's creative generation model, supporting image-to-image editing and style guidance, with up to 9 reference images to control composition and characters; called through the unified HiAPI.ai interface

grok-imagine/image-to-image grok-imagine/image-to-video grok-imagine/text-to-image grok-imagine/text-to-video

Try grok-imagine/image-to-image

Input

Showcases

View all showcases

Output

image

Fill in the parameters and run — results show up here.

Pricing

grok-imagine/image-to-image per image

Unit Price	$0.030

Positioning Overview

grok-imagine/image-to-image is an image editing model from xAI, accessible through the unified HiAPI.ai interface. Using prompts as editing instructions, it generates new images based on 1 to 3 reference images, supporting selectable 1k/2k resolutions, 14 aspect ratios, and jpeg/png/webp output formats. It is suited for developers who need to perform rewrites, style transfer, or composition adjustments starting from existing images, bringing controllable image editing capabilities into their own product workflows.

Key Highlights

Reference-image-driven controllable editing — Takes 1 to 3 public URL images as input and describes the rewrite goal with a prompt, so subjects and compositions are grounded rather than generated from thin air.
Wide aspect ratio coverage — Supports 14 aspect ratios from 2:1 to 1:2; auto directly inherits the ratio of the first input image, fitting both landscape and portrait placements.
Selectable resolution and format — Output can be 1k or 2k, with support for jpeg, png, and webp formats, producing files directly usable for downstream purposes.

Capability Details

Reference-image-conditioned editing: Submit 1 to 3 public jpeg/png/webp images along with an editing instruction, and the model generates a rewritten image based on them, suited for targeted modifications on existing assets.

Aspect ratio control: Choose auto or 14 fixed ratios; auto follows the first input image, making it easy to produce batches of images sized to match ad placements.

Resolution and format output: Output resolution can be 1k or 2k, and formats include jpeg, png, and webp, letting developers directly specify result specs based on front-end display or subsequent processing needs.

Long instruction support: Prompts can be up to 8000 characters, accommodating detailed editing descriptions so complex rewrite requirements can be fully expressed in a single instruction.

Use Cases

Design teams: targeted rewrites of existing assets — Upload existing product or scene images and describe the modifications to produce new images that preserve the original composition, for asset replacement or variant generation.
Content operations: batch image creation for ad placements — Generate landscape or portrait images using reference images plus ratio parameters, directly usable for multi-size social media and ad placement campaigns.
App developers: integrate image editing features — Package reference-image editing with format and resolution parameters into an in-product editing entry point, so users can upload an image and get processed results.

Limitations and Selection Advice

Input accepts only 1 to 3 public URL images in jpeg/png/webp; SVG is not supported, and only one image can be produced per request. Its capabilities are limited to reference-image-based image editing and do not include video generation, audio generation, or text-to-image generation; for those needs, choose text-to-image or video models from the same series. Scenarios requiring batch output of multiple images or native resolutions above 2k also require a different model.

What's new

View changelog →

New model New models: grok-imagine-image-2.0/text-to-image and grok-im… Aug 14, 2026

Frequently asked questions

View all FAQs →

What is the standard Grok Imagine route best for?

It suits high-volume ideation, social assets, landscapes, and cinematic scenes. Current 1k and 2k output share one flat price.
How does standard differ from Quality?

Standard emphasizes speed and a low flat price. Quality is a separate model route focused on material, detail, and light, with tiered 1k/2k pricing.
Which ratios are available?

Thirteen landscape, square, and portrait ratios ranging from 2:1 and 20:9 to 1:2.
Does this page accept references?

No. Use grok-imagine/image-to-image for reference editing.

Create a generation task

POST https://api.hiapi.ai/v1/tasks

Headers

AuthorizationstringRequired

Account API key. Required on every request. Example: Bearer YOUR_HIAPI_API_KEY. Get your API key

Content-TypestringOptional

The request body is always parsed as JSON; when sent, only application/json (optionally with charset) is accepted — any other value returns 415. Example: application/json.

Idempotency-KeystringOptional

Idempotency key, up to 255 bytes. Retries with the same key from the same account create the task only once; replays return the original taskId.

Idempotency key

On network timeouts or client retries, the same key creates the task only once — no double charges (scope: the API key's account). Use a business-unique identifier as the key (e.g. "order-42"); replays return the original taskId, and keys expire 24 hours after the first request. See the Unified Async API overview for the full scenario matrix.

Body

modelstringRequired

Current fixed value: grok-imagine/image-to-image

routestringOptional

Current fixed value: default

inputobjectRequired

Business parameters for grok-imagine/image-to-image and route default — see the parameter table below.

promptstringRequiredminLength 1maxLength 8000

Instruction text for editing, describing the desired output effect in natural language.

image_urlsarrayRequiredminItems 1maxItems 3

Array of input reference images; provide 1 to 3 publicly accessible jpeg, png, or webp image URLs. SVG format is not supported.

Array [ string ]

resolutionstringOptionalDefault: "1k"

Resolution of the output image, default 1k.

Options:1k2k

aspect_ratiostringOptionalDefault: "auto"

Aspect ratio of the generated image, default auto, which follows the aspect ratio of the first input image.

Options:auto2:120:919.5:916:94:33:21:1

Show all (6)

2:33:49:169:19.59:201:2

output_formatstringOptionalDefault: "jpeg"

Format of the output image, default jpeg.

Options:jpegpngwebp

callbackobjectOptional

Terminal-state notification config. When omitted, no callback is delivered — poll the task yourself. See the callback note below.

Callbacks (Webhook)

Provide callback.url when creating a task and HiAPI POSTs to your service once the task reaches a terminal state — no polling needed. The callback payload mirrors the task detail structure; signature verification, delivery retries and idempotency are documented on the Unified Async API overview page.

urlstringRequired

Required when callback is present. A POST is sent to this URL once the task reaches a terminal state; must be a valid http(s) URL.

whenstringOptionalDefault: "final"

Only final is supported today — notified on both success and fail.

Options:final

storagestringOptionalDefault: "temp"

Artifact storage tier: temp (default, retained about 7 days) or persistent (long-term, billed by size). Insufficient balance or exceeding the storage cap silently downgrades to temp; the effective tier is shown in the task detail response.

Options:temppersistent

Request examples

# Submit an async task; returns a taskId immediately (no waiting for generation)
curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "grok-imagine/image-to-image",
  "input": {
    "prompt": "…",
    "image_urls": "…",
    "resolution": "1k",
    "aspect_ratio": "auto",
    "output_format": "jpeg"
  }
}'

const res = await fetch("https://api.hiapi.ai/v1/tasks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HIAPI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "grok-imagine/image-to-image",
    input: {
      "prompt": "…",
      "image_urls": "…",
      "resolution": "1k",
      "aspect_ratio": "auto",
      "output_format": "jpeg"
    }
  }),
});
const task = await res.json();
// { code: 200, message: "success", data: { taskId } }

import os, requests

res = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "grok-imagine/image-to-image",
        "input": {
          "prompt": "…",
          "image_urls": "…",
          "resolution": "1k",
          "aspect_ratio": "auto",
          "output_format": "jpeg"
        }
    },
)
print(res.json())  # { code, message, data: { taskId } }

200 OK

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR"
  }
}

400 Bad Request

{
  "code": 400,
  "message": "invalid request",
  "data": null,
  "error_code": "INVALID_REQUEST"
}

Get task detail

GET https://api.hiapi.ai/v1/tasks/:id

Response fields

taskIdstringRequired

Task ID, always prefixed with tk-hiapi-.

modelstringRequired

Resolved full model name. Tasks submitted with the route parameter return base@route (e.g. gpt-image-2/text-to-image@ext); otherwise identical to the name passed at creation.

routestringOptional

Present only when the task was submitted with an explicit route parameter; echoes the submitted value.

statusstringRequired

Task status.

Status values

queued Queued, not started yet. handling Being processed. archiving Processing finished, artifacts being prepared. success Terminal: completed, artifacts available (output returned). fail Terminal: failed (error returned). After submission, check status: success and fail are terminal, everything else is non-terminal. Poll every 1–3 seconds until terminal. On success, download artifacts from output[].url and transfer them before expireAt; pass storage: "persistent" at creation time when long-term retention is needed.

creatednumberRequired

Task creation time (Unix seconds).

completednumberRequired

Unix seconds when the task reached a terminal state; fixed to 0 while not terminal.

outputarrayOptional

Present only when status == success. Artifact list — always an array; a single task may return multiple types at once (e.g. video + first_frame).

Array [ object ]

Array items

urlstringRequired

Artifact URL, directly downloadable.

typestringRequired

Current possible values: video, image, audio, first_frame, last_frame, thumbnail; more may be added later.

expireAtnumberRequired

Unix seconds until which the artifact remains accessible; download or transfer before it expires.

errorobjectOptional

Present only when status == fail.

codestringRequired

Business error code.

messagestringRequired

Error description.

Response examples

Success

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "happyhorse-1-0",
    "status": "success",
    "created": 1777282033,
    "completed": 1777282099,
    "output": [
      {
        "url": "https://cdn.hiapi.ai/tasks/.../video.mp4",
        "type": "video",
        "expireAt": 1777886899
      }
    ]
  }
}

Processing (non-terminal)

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "archiving",
    "created": 1777282033,
    "completed": 0
  }
}

Failed

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "fail",
    "created": 1777282033,
    "completed": 1777282099,
    "error": {
      "code": "TASK_FAILED",
      "message": "task failed"
    }
  }
}