_GenerateImageBody

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/goodeye-dev/json-schema/goodeye-dev-generate-image-body-schema.json",
  "title": "_GenerateImageBody",
  "description": "Request body for ``POST /image-generators/{generator_id}/runs``.\n\nThe ``generator_id`` in the path is the primary generator reference. To\nuse the authenticated one-off model path (a concrete model identifier, no\ndeployed generator), supply ``model`` in the body and use any placeholder\npath segment (e.g. ``-``). ``generator`` and ``model`` are mutually\nexclusive in the underlying call: when ``model`` is set the path id is\nignored.\n\nCaller-shape errors return 400 with no run row written. Provider and\ntimeout errors return 201 with ``status=\"error\"`` and an ``error_code``\nof ``provider_error``, ``runtime_error``, or ``timeout``.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/goodeye-dev-openapi.json#/components/schemas/_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"
  ]
}