image-generators

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

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}.

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

Path parameters

generator_idstring required

Request body

modelstring 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.

promptstring required

Text description of the image to generate.

reference_image_urlstring nullable

Public HTTP or HTTPS URL of the reference image. Required for image_to_image generators; rejected for text_to_image ones.

num_imagesinteger

Number of images to generate in a single call (1 to 4). Each image is billed separately.

seedinteger 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_overridesobject 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.

versioninteger nullable

Pin to a specific deployed generator version. Defaults to the generator's current version.

skill_idstring nullable

Optional skill UUID for provenance. Access-checked: a skill the caller cannot see surfaces as 404.

skill_versioninteger nullable

Skill version invoking this run, paired with skill_id.

skill_refstring nullable

Free-form skill label (slug, name) for human-readable provenance.

run_idstring nullable

Optional caller-supplied correlation ID stamped onto the run row.

visibilitystring

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

Successful Response

object required

Changes

No recorded changes to this operation across all 1 revision of this API.