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

# Image Generation

> Generate provider-neutral AI image assets for your active business.

`POST /api/v1/images` creates an AI-generated image for the active business attached to your API key. The response includes the generated image URL, watermark state, daily usage, and a request receipt.

Use an API key with the `content:write` scope. This endpoint is available on Growth plans and higher.

<ParamField header="X-NearIQ-Key" type="string" required>
  Your API key from Settings > API Keys.
</ParamField>

## Request body

| Name     | Type   | Required | Default          | Notes                                                                                        |
| -------- | ------ | -------- | ---------------- | -------------------------------------------------------------------------------------------- |
| `prompt` | string | yes      | -                | Description of the image you want, 1-1000 characters.                                        |
| `preset` | enum   | no       | `social_graphic` | Output intent: `social_graphic`, `gbp_post`, `ad_creative`, `product_photo`, or `blog_hero`. |
| `style`  | enum   | no       | -                | Optional visual treatment: `photorealistic`, `illustration`, `minimal`, or `bold`.           |

## Example

<RequestExample>
  ```bash cURL theme={null}
  curl https://app.neariq.io/api/v1/images \
    -X POST \
    -H "X-NearIQ-Key: niq_your_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "Modern gym interior with natural light and branded wall signage",
      "preset": "social_graphic",
      "style": "photorealistic"
    }'
  ```

  ```javascript JavaScript theme={null}
  const image = await client.generateImage({
    prompt: 'Modern gym interior with natural light and branded wall signage',
    preset: 'social_graphic',
    style: 'photorealistic',
  })
  ```

  ```python Python theme={null}
  image = client.generate_image(
      prompt="Modern gym interior with natural light and branded wall signage",
      preset="social_graphic",
      style="photorealistic",
  )
  ```
</RequestExample>

## Response

```json theme={null}
{
  "url": "https://...",
  "prompt": "Modern gym interior with natural light and branded wall signage",
  "preset": "social_graphic",
  "watermarked": false,
  "disclaimer": null,
  "usage": {
    "used": 4,
    "limit": 25,
    "remaining": 21,
    "resetsAt": "2026-06-10T00:00:00.000Z"
  },
  "_receipt": {
    "requestId": "req_...",
    "generatedAt": "2026-06-09T16:20:00.000Z"
  }
}
```

| Field         | Type    | Notes                                                                                                      |
| ------------- | ------- | ---------------------------------------------------------------------------------------------------------- |
| `url`         | string  | Generated image URL. Download or save the asset in your workflow before relying on long-term availability. |
| `watermarked` | boolean | Whether the output includes NearIQ watermarking for the current plan.                                      |
| `usage`       | object  | Daily image-generation usage for the billing account.                                                      |
| `_receipt`    | object  | Request metadata for audit and support.                                                                    |

## Errors

| Status | Meaning                                                         |
| ------ | --------------------------------------------------------------- |
| `400`  | Invalid request body.                                           |
| `403`  | Plan or API-key scope does not allow image generation.          |
| `429`  | Daily image generation limit reached.                           |
| `503`  | Image generation is not configured for the current environment. |

Generated images are scoped to your active business. Organization members also need the image-generation permission for team-owned businesses.