ApiGenerateRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/spritecook-ai/json-schema/spritecook-ai-api-generate-request-schema.json",
  "title": "ApiGenerateRequest",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/spritecook-ai-openapi.json#/components/schemas/ApiGenerateRequest",
  "properties": {
    "prompt": {
      "type": "string",
      "maxLength": 5000,
      "minLength": 1,
      "title": "Prompt",
      "description": "What to generate, e.g. 'a medieval iron sword, side view'"
    },
    "width": {
      "type": "integer",
      "maximum": 512.0,
      "minimum": 16.0,
      "title": "Width",
      "description": "Requested/fallback width hint in pixels. The final asset width can differ.",
      "default": 64
    },
    "height": {
      "type": "integer",
      "maximum": 512.0,
      "minimum": 16.0,
      "title": "Height",
      "description": "Requested/fallback height hint in pixels. The final asset height can differ.",
      "default": 64
    },
    "variations": {
      "type": "integer",
      "maximum": 4.0,
      "minimum": 1.0,
      "title": "Variations",
      "description": "Number of image variations to generate",
      "default": 1
    },
    "pixel": {
      "type": "boolean",
      "title": "Pixel",
      "description": "True for pixel art with crisp edges and grid alignment. False for detailed/HD art with smooth gradients and fine detail",
      "default": true
    },
    "pixel_perfect": {
      "type": "boolean",
      "title": "Pixel Perfect",
      "description": "Apply pixel-perfect grid alignment post-processing (only applies when pixel=True)",
      "default": true
    },
    "outline_repair": {
      "type": "boolean",
      "title": "Outline Repair",
      "description": "Repair pixel art outlines after background removal: restores clipped outline pixels and removes background fringe (only applies to pixel art with a transparent background)",
      "default": true
    },
    "bg_mode": {
      "type": "string",
      "pattern": "^(transparent|white|include)$",
      "title": "Bg Mode",
      "description": "Background mode: transparent, white, or include",
      "default": "transparent"
    },
    "project_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Project Id",
      "description": "Assign generated assets to a project"
    },
    "theme": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 500
        },
        {
          "type": "null"
        }
      ],
      "title": "Theme",
      "description": "Art theme/setting context, e.g. 'dark fantasy medieval'"
    },
    "style": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 500
        },
        {
          "type": "null"
        }
      ],
      "title": "Style",
      "description": "Art style direction, e.g. '16-bit SNES style'"
    },
    "aspect_ratio": {
      "type": "string",
      "pattern": "^(1:1|16:9|9:16)$",
      "title": "Aspect Ratio",
      "description": "Aspect ratio for generation",
      "default": "1:1"
    },
    "smart_crop": {
      "type": "boolean",
      "title": "Smart Crop",
      "description": "Auto-crop output to content bounds",
      "default": true
    },
    "smart_crop_mode": {
      "type": "string",
      "pattern": "^(tightest|power_of_2)$",
      "title": "Smart Crop Mode",
      "description": "Crop mode",
      "default": "tightest"
    },
    "model": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Model",
      "description": "AI model to use. Defaults to gemini-nano-banana-2.1"
    },
    "mode": {
      "type": "string",
      "pattern": "^(assets|texture|ui)$",
      "title": "Mode",
      "description": "Generation mode: assets, texture, or ui",
      "default": "assets"
    },
    "resolution": {
      "type": "string",
      "pattern": "^(1K|2K|4K)$",
      "title": "Resolution",
      "description": "Output resolution tier. 2K and 4K need the Adventurer plan or higher.",
      "default": "1K"
    },
    "quality": {
      "type": "string",
      "pattern": "^(low|medium|high)$",
      "title": "Quality",
      "description": "GPT Image 2 quality tier",
      "default": "medium"
    },
    "colors": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array",
          "maxItems": 64
        },
        {
          "type": "null"
        }
      ],
      "title": "Colors",
      "description": "Color palette constraint, list of hex codes (max 64)"
    },
    "style_asset_ids": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array",
          "maxItems": 14
        },
        {
          "type": "null"
        }
      ],
      "title": "Style Asset Ids",
      "description": "Owned style guide images; combined with context/edit images up to the model reference limit"
    },
    "reference_asset_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Reference Asset Id",
      "description": "Asset ID to use as one specific visual/context reference"
    },
    "edit_asset_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Edit Asset Id",
      "description": "Asset ID to edit with the explicit request settings. Exact source geometry is best-effort rather than guaranteed."
    },
    "runpod_alpha_threshold_enabled": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Runpod Alpha Threshold Enabled",
      "description": "Alpha threshold toggle for Basic background removal. Defaults to true for the public API. When false, runpod_alpha_cutoff is ignored."
    },
    "runpod_alpha_cutoff": {
      "anyOf": [
        {
          "type": "integer",
          "maximum": 255.0,
          "minimum": 0.0
        },
        {
          "type": "null"
        }
      ],
      "title": "Runpod Alpha Cutoff",
      "description": "Binary alpha cutoff for Basic background removal. Defaults to 96 for the public API when runpod_alpha_threshold_enabled is true."
    }
  },
  "type": "object",
  "required": [
    "prompt"
  ]
}