{
  "openapi": "3.0.3",
  "info": {
    "title": "Hex Character Pack Avatar Generator API",
    "description": "High-performance pixel art avatar generation API powered by the Hex Character Asset Pack by Jose Javier (SnowHex). Supports arbitrary resolution scaling (16px to 1024px+), PNG and SVG vector formats, deterministic seeds, and isolated asset retrieval.",
    "version": "1.0.0",
    "contact": {
      "name": "Jose Javier (SnowHex) - Original Asset Creator",
      "url": "https://snowhex.itch.io/hex-character-asset-pack"
    }
  },
  "servers": [
    {
      "url": "/",
      "description": "Local server"
    }
  ],
  "paths": {
    "/api/portrait": {
      "get": {
        "summary": "Generate Avatar (GET)",
        "description": "Composites an avatar from chosen or randomized components and returns the rendered image.",
        "parameters": [
          {
            "name": "size",
            "in": "query",
            "description": "Output dimension in pixels (width and height). Standard sizes: 16, 64, 128, 256, 512, 1024.",
            "schema": { "type": "integer", "default": 256, "minimum": 16, "maximum": 4096 }
          },
          {
            "name": "format",
            "in": "query",
            "description": "Output format: 'png' for pixel art image or 'svg' for crisp vector wrapper.",
            "schema": { "type": "string", "enum": ["png", "svg"], "default": "png" }
          },
          {
            "name": "skin",
            "in": "query",
            "description": "Skin tone index (0 to 11).",
            "schema": { "type": "integer", "minimum": 0, "maximum": 11 }
          },
          {
            "name": "hair_style",
            "in": "query",
            "description": "Hairstyle index (0 to 31, or 'none' for bald).",
            "schema": { "type": "string" }
          },
          {
            "name": "hair_color",
            "in": "query",
            "description": "Hair color (dark, blonde, blue, red, green, orange, pink, lilac, magent, blue_green, brown, dark_blue, dark_brown, light_brown, light_green, white).",
            "schema": { "type": "string", "default": "dark" }
          },
          {
            "name": "clothes_style",
            "in": "query",
            "description": "Clothing style index (0 to 11, or 'none').",
            "schema": { "type": "string" }
          },
          {
            "name": "clothes_color",
            "in": "query",
            "description": "Clothing color palette name.",
            "schema": { "type": "string", "default": "dark" }
          },
          {
            "name": "eyes_style",
            "in": "query",
            "description": "Eyes expression index (0 to 11).",
            "schema": { "type": "integer", "minimum": 0, "maximum": 11 }
          },
          {
            "name": "eyes_color",
            "in": "query",
            "description": "Eyes iris color name.",
            "schema": { "type": "string", "default": "dark" }
          },
          {
            "name": "eyebrows_style",
            "in": "query",
            "description": "Eyebrows expression index (0 to 11).",
            "schema": { "type": "integer", "minimum": 0, "maximum": 11 }
          },
          {
            "name": "eyebrows_color",
            "in": "query",
            "description": "Eyebrows color name.",
            "schema": { "type": "string" }
          },
          {
            "name": "mouth_style",
            "in": "query",
            "description": "Mouth expression index (0 to 11), automatically tinted to skin tone.",
            "schema": { "type": "integer", "minimum": 0, "maximum": 11 }
          },
          {
            "name": "bg_pattern",
            "in": "query",
            "description": "Background pattern index (0 to 11, or 'none').",
            "schema": { "type": "string" }
          },
          {
            "name": "bg_color",
            "in": "query",
            "description": "Background color name, 'none', or custom 6-digit hex color.",
            "schema": { "type": "string" }
          },
          {
            "name": "seed",
            "in": "query",
            "description": "Deterministic seed string. Any input producing the same avatar reproducibly.",
            "schema": { "type": "string" }
          },
          {
            "name": "download",
            "in": "query",
            "description": "Send Content-Disposition: attachment header to trigger download in browser.",
            "schema": { "type": "boolean", "default": false }
          }
        ],
        "responses": {
          "200": {
            "description": "Generated avatar image",
            "content": {
              "image/png": { "schema": { "type": "string", "format": "binary" } },
              "image/svg+xml": { "schema": { "type": "string" } }
            }
          }
        }
      },
      "post": {
        "summary": "Generate Avatar (POST JSON)",
        "description": "Generates an avatar via JSON payload.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/HexRenderOptions" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Generated avatar image",
            "content": {
              "image/png": { "schema": { "type": "string", "format": "binary" } },
              "image/svg+xml": { "schema": { "type": "string" } }
            }
          }
        }
      }
    },
    "/api/part": {
      "get": {
        "summary": "Get Isolated Part Asset",
        "description": "Returns an individual component sprite on a transparent background at any requested resolution.",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "required": true,
            "description": "Component category",
            "schema": { "type": "string", "enum": ["hair", "clothes", "eyes", "eyebrows", "mouth", "skin", "bg"] }
          },
          {
            "name": "style",
            "in": "query",
            "required": true,
            "description": "Component index (0..31 for hair, 0..11 for others)",
            "schema": { "type": "integer" }
          },
          {
            "name": "color",
            "in": "query",
            "description": "Palette color name",
            "schema": { "type": "string", "default": "dark" }
          },
          {
            "name": "skin",
            "in": "query",
            "description": "Skin tone index (used for mouth lip shading)",
            "schema": { "type": "integer", "default": 0 }
          },
          {
            "name": "size",
            "in": "query",
            "description": "Output resolution in pixels (default: 60)",
            "schema": { "type": "integer", "default": 60 }
          },
          {
            "name": "format",
            "in": "query",
            "description": "Output format: 'png' or 'svg'",
            "schema": { "type": "string", "enum": ["png", "svg"], "default": "png" }
          },
          {
            "name": "download",
            "in": "query",
            "description": "Trigger browser download",
            "schema": { "type": "boolean", "default": false }
          }
        ],
        "responses": {
          "200": {
            "description": "Isolated component image",
            "content": {
              "image/png": { "schema": { "type": "string", "format": "binary" } },
              "image/svg+xml": { "schema": { "type": "string" } }
            }
          }
        }
      }
    },
    "/api/parts": {
      "get": {
        "summary": "List Available Parts & Palette",
        "description": "Returns the complete catalog manifest including skin tones, standard palette colors, categories, counts, and direct asset URLs.",
        "responses": {
          "200": {
            "description": "Manifest JSON",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/HexPartsResponse" }
              }
            }
          }
        }
      }
    },
    "/api/openapi.json": {
      "get": {
        "summary": "OpenAPI Specification",
        "description": "Returns the OpenAPI 3.0 specification for this API in JSON format.",
        "responses": {
          "200": {
            "description": "OpenAPI Spec",
            "content": {
              "application/json": { "schema": { "type": "object" } }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "HexRenderOptions": {
        "type": "object",
        "properties": {
          "size": { "type": "integer", "example": 256 },
          "format": { "type": "string", "enum": ["png", "svg"], "example": "png" },
          "skin": { "type": "integer", "example": 1 },
          "hair_style": { "type": "integer", "example": 8 },
          "hair_color": { "type": "string", "example": "blonde" },
          "clothes_style": { "type": "integer", "example": 4 },
          "clothes_color": { "type": "string", "example": "red" },
          "eyes_style": { "type": "integer", "example": 2 },
          "eyes_color": { "type": "string", "example": "blue" },
          "eyebrows_style": { "type": "integer", "example": 2 },
          "eyebrows_color": { "type": "string", "example": "dark" },
          "mouth_style": { "type": "integer", "example": 3 },
          "bg_pattern": { "type": "integer", "example": 0 },
          "bg_color": { "type": "string", "example": "lilac" },
          "seed": { "type": "string", "example": "user_42" }
        }
      },
      "HexPartsResponse": {
        "type": "object",
        "properties": {
          "pack": { "type": "string", "example": "hex" },
          "name": { "type": "string", "example": "Hex Character Pack Pixel Art" },
          "default_size": { "type": "integer", "example": 256 },
          "supported_sizes": { "type": "array", "items": { "type": "integer" } },
          "supported_formats": { "type": "array", "items": { "type": "string" } },
          "skin_tones": { "type": "array", "items": { "type": "object" } },
          "palette_colors": { "type": "array", "items": { "type": "object" } },
          "categories": { "type": "array", "items": { "type": "object" } }
        }
      }
    }
  }
}