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

# Playground

> Submit a real Grok Imagine image task from this page, then poll it with the returned task id.

Fill in your API key and a prompt, then send. This hits the live API — the same
endpoint your code would call.

<Warning>
  **Requests sent from this page are real and are billed to your key.**
  A single image costs \$0.02 to \$0.08 depending on the model and tier. Nothing
  here is a sandbox or a mock.
</Warning>

## Parameters

<ParamField body="model" type="string" required>
  Which model to run. Accepts `grok-imagine-image`, `grok-imagine-image-2.0` or
  `grok-imagine-image-quality`, matched exactly — no aliases.
</ParamField>

<ParamField body="input" type="object" required>
  The generation parameters. Any key not listed below is rejected with
  `invalid_params`.

  <Expandable title="input">
    <ParamField body="input.prompt" type="string" required>
      What to generate. Must not be empty; at most 32000 bytes.
    </ParamField>

    <ParamField body="input.resolution" type="string" default="1k">
      `1k` or `2k`. Lowercase — uppercase is rejected.
    </ParamField>

    <ParamField body="input.quality" type="string" default="low">
      `low` or `medium`. **Only accepted by `grok-imagine-image-2.0`**; on the
      other two models it comes back as an unknown field.
    </ParamField>

    <ParamField body="input.aspect_ratio" type="string">
      One of `auto` `1:1` `16:9` `9:16` `4:3` `3:4` `3:2` `2:3` `2:1` `1:2`
      `19.5:9` `9:19.5` `20:9` `9:20` `21:9` `5:2`. Omit it to use the model's
      own default framing.
    </ParamField>

    <ParamField body="input.n" type="integer" default="1">
      How many images to produce, 1 to 4. Each one is a separate entry in
      `outputs`, and each one is billed.
    </ParamField>

    <ParamField body="input.images" type="string[]">
      Reference images to edit or compose from, up to 3. Each entry is an
      `https` URL or a base64 data URI, and each adds about \$0.01.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="callback_url" type="string">
  An `https` URL to POST the finished task to, so you can skip polling. Must be
  `https` — anything else is rejected at submit time.
</ParamField>

## What comes back

Submitting returns immediately, in well under a second. The image is **not** in
this response — generation happens in the background.

| Field        | Type    | Notes                                  |
| ------------ | ------- | -------------------------------------- |
| `id`         | string  | The task id. Everything else needs it. |
| `status`     | string  | `queued` on a fresh task.              |
| `created_at` | integer | Unix seconds, UTC.                     |

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "task_2wZ1SuRH4VzXxONqGrH9oCLEZiBQTAVF",
    "status": "queued",
    "created_at": 1788189088
  }
  ```
</ResponseExample>

## Then poll for the result

This playground covers the create call only. Take the `id` from the response
above and read the task until `status` reaches `completed` or `failed` — expect
about 7 to 10 seconds.

```bash theme={null}
curl https://api.widerouter.com/v1/task/$TASK_ID \
  -H "Authorization: Bearer $WIDEROUTER_API_KEY"
```

A finished task carries an `outputs` array:

```json theme={null}
{
  "id": "task_2wZ1SuRH4VzXxONqGrH9oCLEZiBQTAVF",
  "model": "grok-imagine-image",
  "status": "completed",
  "created_at": 1788189088,
  "completed_at": 1788189094,
  "expires_at": 1788275494,
  "outputs": ["https://r2cdn.agisuitepro.com/o/2026/08/31/task_2wZ1SuRH4VzXxONqGrH9oCLEZiBQTAVF_0.jpg"],
  "counts": { "requested": 1, "succeeded": 1, "failed": 0 },
  "usage": { "cost_in_usd_ticks": 200000000 }
}
```

<Info>
  Output URLs are unauthenticated and expire 24 hours after the task finishes.
  `usage.cost_in_usd_ticks` is the **list price**; your balance moves by that
  figure times your group multiplier — see
  [pricing](/models/grok-imagine/image/overview#pricing).
</Info>

## Next steps

<CardGroup cols={2}>
  <Card title="Overview" icon="image" href="/models/grok-imagine/image/overview">
    Every parameter, the resolution and quality grid, and measured latency.
  </Card>

  <Card title="Async task API" icon="clock" href="/api/async-tasks">
    The polling loop, callbacks and the full error table.
  </Card>
</CardGroup>