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

# Generate image

> Start asynchronous AI image generation into the Media Library

Starts AI image generation into the site's Media Library and returns `202` with the `image_id` — the Media Library asset id — as soon as the job is queued. Poll [Get image](/api-reference/images/get-image) or subscribe to the `image.generation.completed` / `image.generation.failed` webhook events.

Pass `asset_id` to **regenerate** an existing generated image in place (same `image_id`, new render).

**Scope required:** `images:write`

<Warning>
  Plan entitlement (`IMAGE_GENERATION`) is checked before anything is created. A site without access receives `403 plan_upgrade_required` with `required_plan` in the error details, and no asset or job is created.
</Warning>

## Request body

<ParamField body="prompt" type="string" required>What to render — subject, setting, mood — in plain language (max 8,000 chars). Hrizn handles model prompting and the E-E-A-T disclaimer.</ParamField>
<ParamField body="aspect_ratio" type="string">`"16:9"`, `"1:1"`, `"4:5"`, etc. Defaults to landscape.</ParamField>
<ParamField body="article_id" type="string">Attach the image to a Hrizn content item as an article image.</ParamField>
<ParamField body="asset_id" type="string">Existing generated image to regenerate in place.</ParamField>
<ParamField body="reference_image_keys" type="string[]">Up to 4 Media Library asset keys used as visual references.</ParamField>
<ParamField body="idempotency_key" type="string">Alternative to the `X-Idempotency-Key` header. Replays with the same key return the same `image_id` without a second render.</ParamField>

<ResponseExample>
  ```json 202 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "data": {
      "image_id": "2c9c5b1e-6d0d-4c74-9c8f-3b1e0a5d8f21",
      "generation_id": "7a3f2e10-1b2c-4d5e-8f90-abcdef123456",
      "status": "generating",
      "message": "Generation typically completes within a few minutes. Configure webhooks to receive real-time status notifications: https://api-docs.hrizn.io/webhooks"
    }
  }
  ```

  ```json 403 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "error": {
      "code": "plan_upgrade_required",
      "message": "Pro plan required for AI image generation.",
      "details": {
        "feature": "IMAGE_GENERATION",
        "required_plan": "Pro",
        "current_plan": "free"
      }
    }
  }
  ```
</ResponseExample>

<Tip>
  Image generation usually finishes in under a minute. Configure [webhooks](/webhooks) for `image.generation.completed` (payload includes `asset_id` and `image_url`) rather than polling.
</Tip>


## OpenAPI

````yaml POST /images/generate
openapi: 3.1.0
info:
  title: Hrizn Public API
  version: 1.2.0
  description: >
    The Hrizn Public API allows partners to programmatically create content,
    manage inventory descriptions, and integrate with the Hrizn platform.


    All endpoints are prefixed with `/public` and require an API key passed via
    the `X-API-Key` header (except the health check).
  contact:
    email: support@hrizn.io
servers:
  - url: https://api.app.hrizn.io/v1/public
    description: Production
security:
  - apiKeyAuth: []
tags:
  - name: Analytics
    description: >-
      Warehoused Google Search Console and GA4 reads (Teams+ API access,
      analytics:read). URL Inspection is live only on pages/performance.
  - name: IdeaClouds
    description: Create and manage AI-powered keyword research
  - name: Content Intelligence
    description: AI-powered content gap analysis and recommendations
  - name: Content
    description: Generate content from IdeaClouds
  - name: Compliance
    description: Run OEM compliance checks on content
  - name: Content Tools
    description: Generate SEO metadata, schemas, and social snippets
  - name: Inventory
    description: Access vehicle data and AI descriptions
  - name: Images
    description: >-
      Media Library images. Read the library (images:read): list and fetch
      images with alt text, AI-written title/caption/description, the generating
      prompt, dimensions, article links, and social variant cuts. Generate
      (images:write): async AI image generation returning an image_id;
      completion is delivered via image.generation.completed /
      image.generation.failed webhooks.
  - name: Market
    description: >-
      Live local market listings, days supply, competitive set, and pricing
      insights (Unlimited plan + market_data:read)
  - name: Site
    description: View dealership details and configuration
  - name: Webhooks
    description: Manage webhook subscriptions for real-time events
  - name: Reference
    description: Look up available types, scopes, and events
  - name: Social
    description: >-
      Social Hub posting and reviews across all connected platforms (X,
      Facebook, Instagram, LinkedIn, Google Business Profile)
  - name: Health
    description: Health check (no authentication)
paths:
  /images/generate:
    post:
      tags:
        - Images
      summary: Generate AI image
      description: >-
        Starts asynchronous AI image generation into the site Media Library and
        returns 202 with the image_id (the Media Library asset id). Poll GET
        /images/{imageId} or subscribe to image.generation.completed /
        image.generation.failed. Pass asset_id to regenerate an existing
        generated image in place. Entitlement (IMAGE_GENERATION) is checked
        before anything is created — a denied plan returns 403
        plan_upgrade_required with no side effects. Generated images are
        representative renders carrying an E-E-A-T disclaimer.
      operationId: generateImage
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateImageRequest'
      responses:
        '202':
          description: Image generation started
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ImageGenerationAccepted'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/PlanUpgradeRequired'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Idempotency key reused with a different body or still in progress
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          description: Image generation temporarily unavailable
components:
  parameters:
    IdempotencyKey:
      name: X-Idempotency-Key
      in: header
      required: false
      schema:
        type: string
      description: >-
        Optional idempotency key. Repeats with the same key + body within 24h
        return the original response instead of creating a duplicate.
  schemas:
    GenerateImageRequest:
      type: object
      required:
        - prompt
      additionalProperties: false
      properties:
        prompt:
          type: string
          maxLength: 8000
          description: What to render (subject, setting, mood) in plain language.
          example: A silver mid-size SUV parked outside a dealership at golden hour
        aspect_ratio:
          type: string
          maxLength: 16
          description: e.g. "16:9", "1:1", "4:5". Defaults to landscape.
          example: '16:9'
        article_id:
          type: string
          format: uuid
          nullable: true
          description: Attach the image to a Hrizn content item as an article image.
        asset_id:
          type: string
          format: uuid
          nullable: true
          description: Existing generated image to regenerate in place.
        reference_image_keys:
          type: array
          maxItems: 4
          items:
            type: string
          description: Media Library asset keys used as visual references.
        idempotency_key:
          type: string
          maxLength: 200
          description: Alternative to the X-Idempotency-Key header.
    ImageGenerationAccepted:
      type: object
      properties:
        image_id:
          type: string
          format: uuid
          description: Media Library asset id; poll GET /images/{imageId} with it.
        generation_id:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - generating
        message:
          type: string
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: validation_error
            message:
              type: string
              example: 'keyword: Required'
            details:
              type: object
            request_id:
              type: string
  responses:
    BadRequest:
      description: Validation error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    PlanUpgradeRequired:
      description: Plan entitlement required (API_ACCESS or GOOGLE_SERVICES)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Your Hrizn API key (prefix hzk_)

````