---
title: "Generate one or more images from a prompt using a deployed generator."
method: POST
path: "/image-generators/{generator_id}/runs"
tags: ["image-generators"]
---

# Generate one or more images from a prompt using a deployed generator.

`POST /image-generators/{generator_id}/runs`

## Request

- Base URL: `https://api.goodeye.dev/v1`
- URL: `https://api.goodeye.dev/v1/image-generators/{generator_id}/runs`
- Auth: none declared

Generates one or more images using the referenced generator. Path ``generator_id`` is a UUID, ``uuid@version`` to pin a version, or ``system:<tier>`` for platform-managed quality tiers. Anonymous callers may invoke a system tier or a UUID iff it appears in some live ``template_versions.image_generator_snapshots``; spend is gated by the credit ledger. The ``model`` body field (authenticated one-off) is not usable from published templates or by anonymous callers. Caller-shape errors return 400; runtime and provider errors return 201 with ``status='error'`` and an ``error_code`` of ``provider_error``, ``runtime_error``, or ``timeout``. Returns ``{run_id, model_tier_or_model, image_url, image_urls, width, height, num_images, cost_usd, duration_ms, status, created_at, error_code, error_message}``.

## Path parameters

- `generator_id` string, required

## Request body

- GenerateImageBody: Request body for ``POST /image-generators/{generator_id}/runs``. The ``generator_id`` in the path is the primary generator reference. To use the authenticated one-off model path (a concrete model identifier, no deployed generator), supply ``model`` in the body and use any placeholder path segment (e.g. ``-``). ``generator`` and ``model`` are mutually exclusive in the underlying call: when ``model`` is set the path id is ignored. Caller-shape errors return 400 with no run row written. Provider and timeout errors return 201 with ``status="error"`` and an ``error_code`` of ``provider_error``, ``runtime_error``, or ``timeout``.
  - `model` string, nullable: Concrete image model identifier for an authenticated one-off generation. Not usable from published templates or by anonymous callers. When set, the path ``generator_id`` is ignored and this value is used directly. Mutually exclusive with the path generator.
  - `prompt` string, required: Text description of the image to generate.
  - `reference_image_url` string, nullable: Public HTTP or HTTPS URL of the reference image. Required for ``image_to_image`` generators; rejected for ``text_to_image`` ones.
  - `num_images` integer: Number of images to generate in a single call (1 to 4). Each image is billed separately.
  - `seed` integer, nullable: Optional integer seed for reproducible output. When set, the same prompt and seed produce consistent results across runs. Leave unset for varied, non-deterministic output.
  - `param_overrides` object, nullable: Per-call parameter overrides merged on top of the generator's default parameters (e.g. image size, aspect ratio). Keys not recognized by the model are passed through as-is.
  - `version` integer, nullable: Pin to a specific deployed generator version. Defaults to the generator's current version.
  - `skill_id` string, nullable: Optional skill UUID for provenance. Access-checked: a skill the caller cannot see surfaces as 404.
  - `skill_version` integer, nullable: Skill version invoking this run, paired with ``skill_id``.
  - `skill_ref` string, nullable: Free-form skill label (slug, name) for human-readable provenance.
  - `run_id` string, nullable: Optional caller-supplied correlation ID stamped onto the run row.
  - `visibility` string: Access level for the hosted copy of each generated image. ``public`` (default) returns a link that opens in any browser. ``private`` returns a link only the owner can open and forward, while the plain URL stays locked. Anonymous generations are always public.

## Response `201`

Successful Response

- object

## Other responses

- `400`: Caller-shape error (bad generator ref, contract mismatch, or model path rejected for anonymous caller).
- `404`: Generator not found, not publicly runnable, or referenced skill not visible to caller.
- `422`: Validation Error

---

[API](https://skmtc.dev/goodeye/apis/goodeye-api.md) · [All operations](https://skmtc.dev/goodeye/apis/goodeye-api/llms.txt) · [OpenAPI document](https://skmtc.dev/goodeye/apis/goodeye-api/revisions/547cb8bb6ede?raw)