{
  "openapi": "3.1.0",
  "info": {
    "title": "Eye.Art Polyphemus API",
    "version": "1.0.0",
    "summary": "A conversational image-generation API with one public Polyphemus entry point.",
    "description": "Create raster images or editable SVGs, continue image conversations, and poll long-running raster jobs. No Eye.Art API key is required for anonymous use. Requests are rate-limited by caller network identity. Prompts, references, conversations, and outputs may be retained for up to 30 days. Artist names are visual influences, not endorsements."
  },
  "servers": [{ "url": "https://eye.art", "description": "Eye.Art production API" }],
  "tags": [
    { "name": "Image chat", "description": "Generate images, return synchronous SVG, and check raster job status." },
    { "name": "Conversations", "description": "List, read, create, or delete caller-owned image conversations." }
  ],
  "paths": {
    "/api/omni-image": {
      "post": {
        "tags": ["Image chat"],
        "operationId": "createImage",
        "summary": "Generate an image or editable SVG",
        "description": "Send one natural-language request to the Polyphemus router. Raster requests can use async=true to return a jobId for polling when the image archive is available; otherwise generation may complete synchronously. SVG generation is synchronous and returns editable SVG source. Reuse conversationId and an optional x-fingerprint for follow-up turns; otherwise the API derives anonymous identity from the request network and user agent.",
        "parameters": [
          { "$ref": "#/components/parameters/Fingerprint" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ImageRequest" },
              "examples": {
                "image": {
                  "summary": "Start an asynchronous image generation",
                  "value": { "model": "polyphemus", "message": "A quiet night greenhouse with one impossible red flower", "mode": "image", "artist": "polyphemus", "async": true }
                },
                "svg": {
                  "summary": "Create editable vector artwork",
                  "value": { "model": "polyphemus", "message": "A simple sailboat icon with a white sail, dark hull, three wave bands, and a rayed sun", "outputFormat": "svg", "artist": "matisse" }
                },
                "siteMatch": {
                  "summary": "Match a supplied page's visual language",
                  "value": { "model": "polyphemus", "message": "Create a calm coastal hero illustration with open space on the left for a headline", "mode": "site_match", "attachments": [{ "name": "hero.html", "type": "text/html", "text": "<main class=\"hero\"><h1>Keep the tide alive</h1><img class=\"art\" /></main>" }, { "name": "site.css", "type": "text/css", "text": "body { background: #eaf5ef; color: #173c36; font-family: Georgia, serif; } .hero { padding: 3rem; border-radius: 2rem; }" }] }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Generation completed synchronously (raster or SVG).",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompletedImage" } } }
          },
          "202": {
            "description": "Raster image accepted for asynchronous generation.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueuedImage" } } }
          },
          "400": { "$ref": "#/components/responses/ClientError" },
          "401": { "$ref": "#/components/responses/ClientError" },
          "413": { "$ref": "#/components/responses/ClientError" },
          "429": { "$ref": "#/components/responses/ClientError" },
          "502": { "$ref": "#/components/responses/ClientError" },
          "503": { "$ref": "#/components/responses/ClientError" }
        }
      },
      "get": {
        "tags": ["Image chat"],
        "operationId": "getImageJob",
        "summary": "Check an asynchronous image job",
        "description": "Poll with the jobId returned by POST. Send the same anonymous identity as the POST request. Poll at a reasonable interval; long creative workflows can take several minutes.",
        "parameters": [
          { "$ref": "#/components/parameters/Fingerprint" },
          { "name": "run", "in": "query", "required": true, "schema": { "type": "string", "minLength": 6, "maxLength": 180 }, "description": "Opaque job capability returned by an asynchronous POST." }
        ],
        "responses": {
          "200": { "description": "Job state; completed state includes images[0].url.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageJob" } } } },
          "401": { "$ref": "#/components/responses/ClientError" },
          "403": { "$ref": "#/components/responses/ClientError" },
          "404": { "$ref": "#/components/responses/ClientError" },
          "429": { "$ref": "#/components/responses/ClientError" },
          "503": { "$ref": "#/components/responses/ClientError" }
        }
      }
    },
    "/api/omni-image/conversations": {
      "get": {
        "tags": ["Conversations"],
        "operationId": "getConversations",
        "summary": "List conversations or read one conversation",
        "parameters": [
          { "$ref": "#/components/parameters/Fingerprint" },
          { "name": "conversationId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Omit to list recent conversations; provide an ID to read that conversation." },
          { "name": "includeReferences", "in": "query", "required": false, "schema": { "type": "boolean", "default": true } }
        ],
        "responses": {
          "200": { "description": "Conversation list or conversation transcript.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } },
          "401": { "$ref": "#/components/responses/ClientError" },
          "404": { "$ref": "#/components/responses/ClientError" },
          "429": { "$ref": "#/components/responses/ClientError" },
          "503": { "$ref": "#/components/responses/ClientError" }
        }
      },
      "post": {
        "tags": ["Conversations"],
        "operationId": "createConversation",
        "summary": "Create an empty conversation",
        "parameters": [{ "$ref": "#/components/parameters/Fingerprint" }],
        "responses": {
          "201": { "description": "Conversation created.", "content": { "application/json": { "schema": { "type": "object", "required": ["conversation"], "properties": { "conversation": { "type": "object", "additionalProperties": true } } } } } },
          "401": { "$ref": "#/components/responses/ClientError" },
          "429": { "$ref": "#/components/responses/ClientError" },
          "503": { "$ref": "#/components/responses/ClientError" }
        }
      },
      "delete": {
        "tags": ["Conversations"],
        "operationId": "deleteConversation",
        "summary": "Delete a caller-owned conversation and its saved references",
        "parameters": [
          { "$ref": "#/components/parameters/Fingerprint" },
          { "name": "conversationId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }
        ],
        "responses": {
          "200": { "description": "Conversation deleted.", "content": { "application/json": { "schema": { "type": "object", "required": ["deleted"], "properties": { "deleted": { "const": true } } } } } },
          "400": { "$ref": "#/components/responses/ClientError" },
          "401": { "$ref": "#/components/responses/ClientError" },
          "404": { "$ref": "#/components/responses/ClientError" },
          "429": { "$ref": "#/components/responses/ClientError" },
          "503": { "$ref": "#/components/responses/ClientError" }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "Fingerprint": {
        "name": "x-fingerprint",
        "in": "header",
        "required": false,
        "schema": { "type": "string", "minLength": 1, "maxLength": 200 },
        "description": "Optional stable anonymous conversation identity. Reuse it between generation, status polling, and conversation requests. If omitted, REST derives identity from network address and user agent. Do not send a forged x-forwarded-for header."
      }
    },
    "schemas": {
      "ImageRequest": {
        "type": "object",
        "required": ["message"],
        "properties": {
          "model": { "type": "string", "const": "polyphemus" },
          "message": { "type": "string", "minLength": 2, "maxLength": 4000, "description": "Natural-language image request. The model is a router over Eye.Art's image, artist, code-matching, small-art, motion, and vector workflows." },
          "mode": { "type": "string", "enum": ["image", "site_match", "small_art", "motion"], "description": "Public route choice: image uses smart routing, site_match selects page matching and needs page/code references, small_art adds compact-art planning, and motion selects pixel motion." },
          "artist": { "type": "string", "enum": ["polyphemus", "dali", "goya", "matisse", "leonardo", "van_gogh", "rothko", "ross"], "description": "Artist muse. Non-Polyphemus selections route to the matching artist machine; with site_match, small_art, or motion, the artist guides the selected mode. Polyphemus uses the mixed-muse router." },
          "outputFormat": { "type": "string", "enum": ["raster", "svg"], "default": "raster" },
          "async": { "type": "boolean", "default": false, "description": "When true, raster generation returns 202 and a jobId. SVG generation is synchronous." },
          "conversationId": { "type": "string", "format": "uuid" },
          "clearReferences": { "type": "boolean", "default": false, "description": "Clear saved image/page references from the conversation before this turn." },
          "history": { "type": "array", "maxItems": 12, "items": { "$ref": "#/components/schemas/ConversationTurn" } },
          "attachments": { "type": "array", "maxItems": 4, "items": { "$ref": "#/components/schemas/Attachment" } },
          "width": { "type": "integer", "minimum": 64, "maximum": 2048 },
          "height": { "type": "integer", "minimum": 64, "maximum": 2048 },
          "clientSource": { "type": "string", "maxLength": 64, "description": "Attribution hint for private usage analytics; does not verify a client identity." }
        },
        "additionalProperties": true
      },
      "ConversationTurn": {
        "type": "object",
        "required": ["role", "text"],
        "properties": { "role": { "type": "string", "enum": ["user", "assistant"] }, "text": { "type": "string", "maxLength": 2000 } },
        "additionalProperties": false
      },
      "Attachment": {
        "oneOf": [
          {
            "type": "object",
            "required": ["dataUrl"],
            "properties": {
              "name": { "type": "string", "maxLength": 120 },
              "type": { "type": "string", "enum": ["image/png", "image/jpeg", "image/webp"] },
              "dataUrl": { "type": "string", "description": "PNG/JPEG/WebP base64 data URL; up to 2 MB per image and 6 MB combined." }
            },
            "additionalProperties": false
          },
          {
            "type": "object",
            "required": ["name", "type", "text"],
            "properties": {
              "name": { "type": "string", "maxLength": 120, "description": "Include the relevant extension, such as .html, .css, .js, .jsx, .tsx, or .ts." },
              "type": { "type": "string", "enum": ["text/html", "text/css", "text/javascript", "text/jsx", "text/tsx", "text/typescript"] },
              "text": { "type": "string", "maxLength": 300000, "description": "Page/code text reference. Up to 300 KB." }
            },
            "additionalProperties": false
          }
        ]
      },
      "QueuedImage": {
        "type": "object",
        "required": ["model", "status", "jobId"],
        "properties": { "model": { "const": "polyphemus" }, "status": { "const": "queued" }, "jobId": { "type": "string" }, "conversationId": { "type": "string", "format": "uuid" }, "message": { "type": "string" }, "execution": { "type": "object", "additionalProperties": true } },
        "additionalProperties": true
      },
      "ImageJob": {
        "type": "object",
        "required": ["model", "status"],
        "properties": { "model": { "const": "polyphemus" }, "status": { "type": "string", "enum": ["queued", "running", "complete", "failed"] }, "progress": { "type": "string" }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/ImageResult" } }, "error": { "type": "string" } },
        "additionalProperties": true
      },
      "CompletedImage": {
        "type": "object",
        "required": ["model"],
        "properties": { "model": { "const": "polyphemus" }, "status": { "type": "string" }, "conversationId": { "type": "string", "format": "uuid" }, "message": { "type": "string" }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/ImageResult" } }, "outputFormat": { "type": "string", "const": "svg" }, "mediaType": { "type": "string", "const": "image/svg+xml" }, "svg": { "type": "string" }, "title": { "type": "string" }, "validation": { "type": "object", "additionalProperties": true }, "execution": { "type": "object", "additionalProperties": true } },
        "additionalProperties": true
      },
      "ImageResult": {
        "type": "object",
        "required": ["url"],
        "properties": { "url": { "type": "string", "format": "uri" }, "alt": { "type": "string" } },
        "additionalProperties": true
      },
      "ApiError": { "type": "object", "required": ["error"], "properties": { "error": { "type": "string" } }, "additionalProperties": true }
    },
    "responses": {
      "ClientError": { "description": "Request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }
    }
  }
}
