Goodeye Image Generators API

openapi: 3.2.0
info:
  title: Goodeye Image Generators API
  version: 0.1.0
servers:
- url: /v1
tags:
- name: image-generators
paths:
  /image-generators:
    post:
      tags:
      - image-generators
      summary: Deploy an image generator (create or new version)
      description: 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}``.
      operationId: deploy_image_generator_route_image_generators_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeployImageGeneratorInput'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Deploy Image Generator Route Image Generators Post
        '400':
          description: 'Validation error: unpriceable model or bad contract.'
        '401':
          description: Authentication required.
        '409':
          description: 'Conflict: missing or mismatched ``expected_version_token``, or name reserved for a platform-managed generator.'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - image-generators
      summary: List active image generators visible to the caller
      description: 'Returns ``{items: [...], next_cursor: str | null}`` with one entry per non-revoked image generator the caller owns. Platform ``scope=system`` generators never appear here. Anonymous callers get an empty list.'
      operationId: list_image_generators_route_image_generators_get
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          default: 50
          title: Limit
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Cursor
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response List Image Generators Route Image Generators Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /image-generators/{generator_id}:
    get:
      tags:
      - image-generators
      summary: Get one image generator version (config, contract, params)
      description: Defaults to the current version; pass ``?version=N`` to pin. Returns the full deploy-time payload plus ``config_hash`` for drift detection. ``generator_id`` must be a UUID. Platform-managed (``scope=system``), unauthorized, or revoked generators are always 404.
      operationId: get_image_generator_route_image_generators__generator_id__get
      parameters:
      - name: generator_id
        in: path
        required: true
        schema:
          type: string
          title: Generator Id
      - name: version
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          title: Version
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Image Generator Route Image Generators  Generator Id  Get
        '401':
          description: Authentication required.
        '404':
          description: Image generator not found, revoked, or not owned by caller.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - image-generators
      summary: Revoke an image generator
      description: Sets ``status='revoked'`` and ``revoked_at`` for **caller-owned** ``scope=user`` generators only (UUID). Platform ``scope=system`` generators are always 404. The generator disappears from list/get/run for the owner; existing run rows are retained. Irreversible; replace by deploying a fresh generator under a new name.
      operationId: revoke_image_generator_route_image_generators__generator_id__delete
      parameters:
      - name: generator_id
        in: path
        required: true
        schema:
          type: string
          title: Generator Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Revoke Image Generator Route Image Generators  Generator Id  Delete
        '401':
          description: Authentication required.
        '404':
          description: Image generator not found, already revoked, or not owned by caller.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /image-generators/{generator_id}/runs:
    post:
      tags:
      - image-generators
      summary: Generate one or more images from a prompt using a deployed generator
      description: Generates one or more images using the referenced generator. Path ``generator_id`` is a UUID, ``uuid@version`` to pin a version, or ``system:`` 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}``.
      operationId: generate_image_route_image_generators__generator_id__runs_post
      parameters:
      - name: generator_id
        in: path
        required: true
        schema:
          type: string
          title: Generator Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/_GenerateImageBody'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Generate Image Route Image Generators  Generator Id  Runs Post
        '400':
          description: Caller-shape error (bad generator ref, contract mismatch, or model path rejected for anonymous caller).
        '404':
          description: Generator not found, not publicly runnable, or referenced skill not visible to caller.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /image-generators/{generator_id}/permanent:
    delete:
      tags:
      - image-generators
      summary: Permanently delete an image generator
      description: 'Permanently and immediately erase a **caller-owned** ``scope=user`` image generator. The generator, all its versions (provider config, model, parameters), all run records, and all anonymous run records are removed from the live system at once. There is no recovery path. Use ``DELETE /{generator_id}`` (revoke) to deactivate without erasing, keeping the audit trail intact. Serving gate: if any live published template version carries a snapshot that references this generator, deletion is refused (409). Unpublish the relevant template version(s) first, then retry. Platform ``scope=system`` generators and another user''s generators always surface as 404. Encrypted backups age out within the platform''s standard retention window (up to three months), so the data is not instantly erased from all systems everywhere, but it is no longer accessible through any product surface after this call. Returns ``{generator_id, name, deleted: true}``.'
      operationId: delete_image_generator_route_image_generators__generator_id__permanent_delete
      parameters:
      - name: generator_id
        in: path
        required: true
        schema:
          type: string
          title: Generator Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Delete Image Generator Route Image Generators  Generator Id  Permanent Delete
        '401':
          description: Authentication required.
        '404':
          description: Image generator not found, not owned by caller, or platform-managed (scope=system).
        '409':
          description: Generator is referenced by a live published template version. Unpublish the template version(s) first.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    _GenerateImageBody:
      properties:
        model:
          anyOf:
          - type: string
          - type: 'null'
          title: Model
          description: 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:
          type: string
          minLength: 1
          title: Prompt
          description: Text description of the image to generate.
        reference_image_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Reference Image Url
          description: Public HTTP or HTTPS URL of the reference image. Required for ``image_to_image`` generators; rejected for ``text_to_image`` ones.
        num_images:
          type: integer
          maximum: 4.0
          minimum: 1.0
          title: Num Images
          description: Number of images to generate in a single call (1 to 4). Each image is billed separately.
          default: 1
        seed:
          anyOf:
          - type: integer
          - type: 'null'
          title: Seed
          description: 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:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Param Overrides
          description: 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:
          anyOf:
          - type: integer
            minimum: 1.0
          - type: 'null'
          title: Version
          description: Pin to a specific deployed generator version. Defaults to the generator's current version.
        skill_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Skill Id
          description: 'Optional skill UUID for provenance. Access-checked: a skill the caller cannot see surfaces as 404.'
        skill_version:
          anyOf:
          - type: integer
          - type: 'null'
          title: Skill Version
          description: Skill version invoking this run, paired with ``skill_id``.
        skill_ref:
          anyOf:
          - type: string
            maxLength: 256
          - type: 'null'
          title: Skill Ref
          description: Free-form skill label (slug, name) for human-readable provenance.
        run_id:
          anyOf:
          - type: string
            maxLength: 128
          - type: 'null'
          title: Run Id
          description: Optional caller-supplied correlation ID stamped onto the run row.
        visibility:
          type: string
          title: Visibility
          description: 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.
          default: public
      type: object
      required:
      - prompt
      title: _GenerateImageBody
      description: '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``.'
    DeployImageGeneratorInput:
      properties:
        name:
          type: string
          maxLength: 128
          minLength: 1
          pattern: ^[a-z0-9][a-z0-9-]*$
          title: Name
          description: Image generator name, unique per owner among non-revoked generators. Lowercase letters, digits, and hyphens; no spaces.
        description:
          type: string
          maxLength: 1024
          minLength: 1
          title: Description
          description: Short summary of what this image generator produces.
        provider:
          type: string
          const: fal
          title: Provider
          description: Generation provider backing this image generator.
          default: fal
        model:
          type: string
          maxLength: 256
          minLength: 1
          title: Model
          description: 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:
          type: string
          enum:
          - text_to_image
          - image_to_image
          title: Generation Contract
          description: '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:
          additionalProperties: true
          type: object
          title: Default Params
          description: 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:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Expected Version Token
          description: 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.
      type: object
      required:
      - name
      - description
      - model
      - generation_contract
      title: DeployImageGeneratorInput
      description: '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).'
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError