---
title: "Deploy an image generator (create or new version)"
method: POST
path: "/image-generators"
tags: ["image-generators"]
---

# Deploy an image generator (create or new version)

`POST /image-generators`

## Request

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

Create a **caller-owned** image generator or append a new version to one with the same ``name``. First deploy must omit ``expected_version_token``; subsequent deploys must include the latest token returned by deploy, list, or get. Token mismatch returns 409. Creating a new generator whose ``name`` matches an active platform-managed (``scope=system``) generator returns 409. Returns ``{generator_id, name, current_version, version, version_token, status, provider, model, generation_contract, config_hash}``.

## Request body

- DeployImageGeneratorInput: Payload for ``deploy_image_generator``: create a new image generator or append a new version to an existing one (owner-scoped, name-uniqueness within owner).
  - `name` string, required: Image generator name, unique per owner among non-revoked generators. Lowercase letters, digits, and hyphens; no spaces.
  - `description` string, required: Short summary of what this image generator produces.
  - `provider` 'fal': Generation provider backing this image generator.
  - `model` string, required: Provider endpoint identifier for the image model (e.g. a slug such as ``provider-org/model-name``). Must resolve to a known image endpoint with an authoritative per-image price.
  - `generation_contract` 'text_to_image' | 'image_to_image', required: Input shape at generation time. ``text_to_image``: generates an image from a text prompt only. ``image_to_image``: requires a reference image URL in addition to a prompt.
  - `default_params` object: Default generation parameters merged with per-call overrides at run time (e.g. image size, safety settings). Callers may override individual keys via ``param_overrides`` on ``generate_image``.
  - `expected_version_token` string, uuid, nullable: Optimistic-concurrency token. Required when re-deploying an existing generator to confirm you have seen the latest version (get it from ``deploy_image_generator``, ``list_image_generators``, or ``get_image_generator``). Must be omitted on first deploy. Mismatch returns a Conflict with the current token.

## Response `201`

Successful Response

- object

## Other responses

- `400`: Validation error: unpriceable model or bad contract.
- `401`: Authentication required.
- `409`: Conflict: missing or mismatched ``expected_version_token``, or name reserved for a platform-managed generator.
- `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)