images:write

images:write The images:write scope lets you start asynchronous AI image generation into a site’s Media Library and regenerate an existing generated image in place. It is included in the Full Access and Content Generation presets and in the MCP Read + Create profile. Reading images back (including polling a generation) uses images:read; keys that hold only images:write may still poll GET /public/images/{imageId}. Generation is gated by the site’s IMAGE_GENERATION plan entitlement. Denied sites receive 403 plan_upgrade_required before any asset or job is created.

Endpoints

Method	Path	Description
`POST`	`/public/images/generate`	Start (or regenerate) an AI image
`GET`	`/public/images/{imageId}`	Poll generation status (also under `images:read`)

Generate image

POST /public/images/generate

Returns 202 with image_id (the Media Library asset id). Send X-Idempotency-Key to make retries safe. Pass asset_id in the body to regenerate an existing image.

Example

curl -X POST https://api.app.hrizn.io/v1/public/images/generate \
  -H "X-API-Key: hzk_your_key_here" \
  -H "X-Idempotency-Key: 6f1d2c3b-4a5e-4f60-9b7c-8d9e0f1a2b3c" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"A silver mid-size SUV parked outside a dealership at golden hour","aspect_ratio":"16:9"}'

const res = await fetch("https://api.app.hrizn.io/v1/public/images/generate", {
  method: "POST",
  headers: {
    "X-API-Key": "hzk_your_key_here",
    "X-Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    prompt: "A silver mid-size SUV parked outside a dealership at golden hour",
    aspect_ratio: "16:9",
  }),
});
const { data } = await res.json(); // { image_id, generation_id, status: "generating" }

import requests, uuid

response = requests.post(
    "https://api.app.hrizn.io/v1/public/images/generate",
    headers={
        "X-API-Key": "hzk_your_key_here",
        "X-Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "prompt": "A silver mid-size SUV parked outside a dealership at golden hour",
        "aspect_ratio": "16:9",
    },
)
data = response.json()["data"]

Get image

GET /public/images/{imageId}

Returns status (generating, complete, error), image_url once complete, and error on failure — plus the full image read projection (alt text, AI metadata, prompts, variants) documented under images:read.

Webhooks

Subscribe to image.generation.completed and image.generation.failed instead of polling. Both carry asset_id (the image_id), generation_id, and idempotency_key; completed events add image_url and reused, failed events add error.

{
  "event_type": "image.generation.completed",
  "site_id": "8f1c...",
  "timestamp": "2026-09-06T14:02:11.000Z",
  "data": {
    "asset_id": "2c9c5b1e-6d0d-4c74-9c8f-3b1e0a5d8f21",
    "generation_id": "7a3f2e10-1b2c-4d5e-8f90-abcdef123456",
    "idempotency_key": "6f1d2c3b-4a5e-4f60-9b7c-8d9e0f1a2b3c",
    "article_id": null,
    "image_url": "https://assets.app.hrizn.io/public/media-library/8f1c.../7a3f2e10.jpg",
    "reused": false
  }
}

See Webhooks for delivery and signature details.

Getting Started

Concepts

Guides

Scopes

Endpoints

Generate image

Example

Get image

Webhooks

​Endpoints

​Generate image

​Example

​Get image

​Webhooks

Endpoints

Generate image

Example

Get image

Webhooks