{
  "openapi": "3.1.0",
  "info": {
    "title": "de-ASCII API",
    "description": "Reconstruct images from ASCII / ANSI art with bounded glyph-aware rendering, preserve source color and exact ASCII color grids, apply deterministic colorization when requested, run an optional AI restoration/enhancement pass that preserves composition and visible text, manage webhooks, and interact via MCP. Part of the PlatPhorm News network (deascii.platphormnews.com). Central MCP Hub at mcp.platphormnews.com.",
    "version": "1.0.0",
    "contact": {
      "name": "Michael Barbine",
      "email": "Michael@Barbineworldwide.com",
      "url": "https://github.com/mbarbine"
    },
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    },
    "x-keywords": [
      "deASCII",
      "de-ASCII",
      "ASCII to image",
      "ASCII art reconstruction",
      "ANSI art to PNG",
      "ANSI color reconstruction",
      "ANSI background color reconstruction",
      "ANSI terminal art reconstruction",
      "Unicode Braille art reconstruction",
      "box drawing ASCII reconstruction",
      "image from ASCII",
      "ASCII decoder",
      "ASCII converter inverse",
      "photo reconstruction from ASCII art",
      "AI image restoration",
      "text preserving ASCII reconstruction",
      "MCP image tool",
      "LLM-readable image utility",
      "answer engine optimization",
      "generative engine optimization",
      "PlatPhorm News developer tools"
    ],
    "x-repository": "https://github.com/platphorm/platphorm-deascii",
    "x-share-card": "https://deascii.platphormnews.com/sharecard",
    "x-locales": [
      {
        "hreflang": "en",
        "url": "https://deascii.platphormnews.com"
      },
      {
        "hreflang": "es",
        "url": "https://deascii.platphormnews.com/es"
      },
      {
        "hreflang": "fr",
        "url": "https://deascii.platphormnews.com/fr"
      },
      {
        "hreflang": "de",
        "url": "https://deascii.platphormnews.com/de"
      },
      {
        "hreflang": "pt-BR",
        "url": "https://deascii.platphormnews.com/pt-br"
      },
      {
        "hreflang": "ja",
        "url": "https://deascii.platphormnews.com/ja"
      }
    ],
    "x-blog": [
      {
        "title": "de-ASCII final polish upgrades readable reconstruction and game asset scaffolds",
        "url": "https://deascii.platphormnews.com/blog/final-polish-readable-reconstruction-game-scaffold"
      },
      {
        "title": "The road to November 19, 2026: ASCII streams become browser game assets",
        "url": "https://deascii.platphormnews.com/blog/november-19-2026-game-asset-roadmap"
      },
      {
        "title": "de-ASCII 1.0 turns ASCII art back into image output",
        "url": "https://deascii.platphormnews.com/blog/deascii-1-0-launch"
      }
    ]
  },
  "externalDocs": {
    "description": "de-ASCII documentation and launch notes",
    "url": "https://deascii.platphormnews.com/docs"
  },
  "servers": [
    {
      "url": "https://deascii.platphormnews.com",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "reconstruction",
      "description": "ASCII to image reconstruction"
    },
    {
      "name": "health",
      "description": "Service health monitoring"
    },
    {
      "name": "mcp",
      "description": "Model Context Protocol tools"
    },
    {
      "name": "webhooks",
      "description": "Webhook management"
    },
    {
      "name": "info",
      "description": "Service metadata"
    }
  ],
  "paths": {
    "/api/deascii": {
      "post": {
        "operationId": "reconstructImage",
        "tags": [
          "reconstruction"
        ],
        "summary": "Reconstruct an image from ASCII art",
        "description": "Accepts ASCII / ANSI art text and returns a reconstructed PNG image (base64 data URL or raw PNG). ANSI color is preserved. Monochrome ASCII can be deterministically colorized. Optionally runs an AI restoration/enhancement pass against the current reconstruction.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "ascii"
                ],
                "properties": {
                  "ascii": {
                    "type": "string",
                    "description": "Plain ASCII, ANSI terminal art, Unicode Braille/block/quadrant/box-drawing art, punctuation-heavy animation frames, or ASCII converter output (max 200,000 chars). ANSI SGR foreground/background, 16/256/truecolor, bold/faint, inverse, cursor, erase, and tabs are parsed best-effort."
                  },
                  "colors": {
                    "type": "array",
                    "description": "Optional exact hex color grid from ascii.platphormnews.com. Each row aligns to the ASCII text columns; compact chroma references remain sidecar metadata.",
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "pattern": "^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$"
                      }
                    }
                  },
                  "colorGrid": {
                    "type": "object",
                    "description": "Optional exact packed rgb24-b64-v1 color grid from ascii.platphormnews.com. Use this instead of colors to reduce request size without losing per-cell color fidelity."
                  },
                  "sourceFormat": {
                    "type": "string",
                    "description": "Optional import metadata such as platphorm-ascii-handoff.v1."
                  },
                  "charset": {
                    "type": "string",
                    "enum": [
                      "auto",
                      "standard",
                      "detailed",
                      "blocks",
                      "minimal",
                      "braille"
                    ],
                    "default": "auto"
                  },
                  "cellSize": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 32,
                    "default": 10
                  },
                  "cellWidth": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 64,
                    "description": "Optional cell width override"
                  },
                  "cellHeight": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 128,
                    "description": "Optional cell height override"
                  },
                  "cellAspect": {
                    "type": "number",
                    "minimum": 0.25,
                    "maximum": 4,
                    "default": 2
                  },
                  "smoothing": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 6,
                    "default": 3
                  },
                  "renderMode": {
                    "type": "string",
                    "enum": [
                      "tonal",
                      "hybrid",
                      "glyph"
                    ],
                    "default": "tonal",
                    "description": "tonal for best-match raster output; hybrid/glyph preserve bitmap text, digit, symbol, and icon texture."
                  },
                  "inverted": {
                    "type": "boolean",
                    "default": false
                  },
                  "background": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 1,
                    "default": 0
                  },
                  "contrast": {
                    "type": "number",
                    "minimum": 0.25,
                    "maximum": 2,
                    "default": 1.08
                  },
                  "sharpen": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 2,
                    "default": 0.3
                  },
                  "autoWrap": {
                    "type": "boolean",
                    "default": false
                  },
                  "wrapColumns": {
                    "type": "integer",
                    "minimum": 1,
                    "description": "Optional visible-character wrap column count"
                  },
                  "maxOutputPixels": {
                    "type": "integer",
                    "minimum": 1,
                    "default": 12000000,
                    "description": "Direct PNG allocation budget. Oversized requests auto-fit by default instead of failing."
                  },
                  "maxOutputDimension": {
                    "type": "integer",
                    "minimum": 256,
                    "default": 32767,
                    "description": "Per-axis canvas safety budget for browser/server output."
                  },
                  "autoFitOutput": {
                    "type": "boolean",
                    "default": true,
                    "description": "Scale oversized requested output down to fit maxOutputPixels/maxOutputDimension while preserving aspect ratio."
                  },
                  "adaptiveQuality": {
                    "type": "boolean",
                    "default": true,
                    "description": "Reduce expensive smoothing/sharpening on very large outputs to preserve runtime stability."
                  },
                  "colorize": {
                    "type": "object",
                    "description": "Deterministic colorization for monochrome ASCII. Ignored when the source includes ANSI or color-grid data.",
                    "properties": {
                      "mode": {
                        "type": "string",
                        "enum": [
                          "none",
                          "smart",
                          "palette",
                          "portrait",
                          "cool",
                          "warm"
                        ],
                        "default": "smart"
                      },
                      "strength": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 1,
                        "default": 0.88
                      },
                      "palette": {
                        "type": "array",
                        "description": "Custom palette for mode=palette. Items may be #rgb, #rrggbb, or RGB arrays.",
                        "items": {
                          "oneOf": [
                            {
                              "type": "string",
                              "pattern": "^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$"
                            },
                            {
                              "type": "array",
                              "prefixItems": [
                                {
                                  "type": "integer",
                                  "minimum": 0,
                                  "maximum": 255
                                },
                                {
                                  "type": "integer",
                                  "minimum": 0,
                                  "maximum": 255
                                },
                                {
                                  "type": "integer",
                                  "minimum": 0,
                                  "maximum": 255
                                }
                              ],
                              "minItems": 3,
                              "maxItems": 3
                            }
                          ]
                        }
                      }
                    }
                  },
                  "format": {
                    "type": "string",
                    "enum": [
                      "json",
                      "png"
                    ],
                    "default": "json"
                  },
                  "enhance": {
                    "type": "boolean",
                    "default": false,
                    "description": "Run an AI restoration/enhancement pass on the deterministic reconstruction."
                  },
                  "enhancePrompt": {
                    "type": "string",
                    "description": "Custom instruction for the AI enhancement pass. Keep prompts restoration-focused, preserve the provided image, and do not request new words, labels, numbers, symbols, or a different composition."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Reconstructed image",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "image": {
                          "type": "string",
                          "description": "PNG data URL"
                        },
                        "enhancedImage": {
                          "type": "string",
                          "nullable": true
                        },
                        "enhanceError": {
                          "type": "string",
                          "nullable": true
                        },
                        "enhanced": {
                          "type": "boolean"
                        },
                        "width": {
                          "type": "integer"
                        },
                        "height": {
                          "type": "integer"
                        },
                        "meta": {
                          "type": "object",
                          "properties": {
                            "colored": {
                              "type": "boolean"
                            },
                            "sourceColored": {
                              "type": "boolean"
                            },
                            "colorized": {
                              "type": "boolean"
                            },
                            "colorizeMode": {
                              "type": "string"
                            },
                            "colorizeStrength": {
                              "type": "number"
                            },
                            "colorizeScene": {
                              "type": "string",
                              "enum": [
                                "portrait",
                                "neutral"
                              ],
                              "nullable": true
                            }
                          },
                          "additionalProperties": true
                        }
                      }
                    }
                  }
                }
              },
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "422": {
            "description": "Reconstruction failed"
          }
        }
      }
    },
    "/api/deascii/from-ascii": {
      "post": {
        "operationId": "reconstructFromAsciiService",
        "tags": [
          "reconstruction"
        ],
        "summary": "Convert an image through ascii.platphormnews.com and reconstruct it",
        "description": "Calls the trusted ASCII converter using either JSON or NDJSON streaming transport, then reconstructs the returned ASCII into a PNG. Streaming is intended for large chunked artifacts and can request opt-in color-grid chunks for source-color round trips.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "asciiRequest"
                ],
                "properties": {
                  "transport": {
                    "type": "string",
                    "enum": [
                      "json",
                      "stream"
                    ],
                    "default": "stream"
                  },
                  "asciiEndpoint": {
                    "type": "string",
                    "enum": [
                      "https://ascii.platphormnews.com/api/convert",
                      "https://ascii.platphormnews.com/api/convert/stream"
                    ]
                  },
                  "asciiRequest": {
                    "type": "object",
                    "description": "Request body forwarded to the trusted ASCII converter. Stream transport defaults includeColorGrid=true for color-preserving round trips unless explicitly set false."
                  },
                  "deascii": {
                    "type": "object",
                    "description": "de-ASCII reconstruction options, such as cellAspect, renderMode, and cellSize."
                  },
                  "format": {
                    "type": "string",
                    "enum": [
                      "json",
                      "png"
                    ],
                    "default": "json"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Reconstructed PNG from ASCII service output"
          },
          "400": {
            "description": "Invalid request"
          },
          "502": {
            "description": "Trusted ASCII import failed"
          }
        }
      }
    },
    "/api/deascii/status": {
      "get": {
        "operationId": "getDeasciiStatus",
        "tags": [
          "reconstruction"
        ],
        "summary": "Get renderer and AI enhancement readiness",
        "description": "Returns public-safe renderer limits and AI enhancement configuration state. Secret values are never returned.",
        "responses": {
          "200": {
            "description": "Renderer and AI enhancement status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "renderer": {
                          "type": "object"
                        },
                        "aiEnhancement": {
                          "type": "object",
                          "properties": {
                            "status": {
                              "type": "string",
                              "enum": [
                                "configured",
                                "degraded",
                                "unavailable"
                              ]
                            },
                            "configured": {
                              "type": "boolean"
                            },
                            "provider": {
                              "type": "string",
                              "enum": [
                                "openai-images",
                                "vercel-ai-gateway"
                              ]
                            },
                            "model": {
                              "type": "string"
                            },
                            "authMode": {
                              "type": "string",
                              "enum": [
                                "openai-api-key",
                                "gateway-api-key",
                                "vercel-oidc",
                                "none"
                              ]
                            },
                            "details": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "operationId": "getHealth",
        "tags": [
          "health"
        ],
        "summary": "Service health check",
        "responses": {
          "200": {
            "description": "Health status"
          }
        }
      }
    },
    "/api/v1/health": {
      "get": {
        "operationId": "getHealthV1",
        "tags": [
          "health"
        ],
        "summary": "Versioned service health check",
        "responses": {
          "200": {
            "description": "Health status"
          }
        }
      }
    },
    "/api/info": {
      "get": {
        "operationId": "getInfo",
        "tags": [
          "info"
        ],
        "summary": "Service metadata and capabilities",
        "responses": {
          "200": {
            "description": "Service info"
          }
        }
      }
    },
    "/api/charsets": {
      "get": {
        "operationId": "listCharsets",
        "tags": [
          "info"
        ],
        "summary": "List available character sets",
        "responses": {
          "200": {
            "description": "Charset list"
          }
        }
      }
    },
    "/api/webhooks": {
      "get": {
        "operationId": "listWebhooks",
        "tags": [
          "webhooks"
        ],
        "summary": "List registered webhooks",
        "responses": {
          "200": {
            "description": "Webhook list"
          }
        }
      },
      "post": {
        "operationId": "subscribeWebhook",
        "tags": [
          "webhooks"
        ],
        "summary": "Register a webhook (protected)",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "201": {
            "description": "Created"
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      },
      "delete": {
        "operationId": "deleteWebhook",
        "tags": [
          "webhooks"
        ],
        "summary": "Delete a webhook (protected)",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted"
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      }
    },
    "/api/mcp": {
      "get": {
        "operationId": "mcpMetadata",
        "tags": [
          "mcp"
        ],
        "summary": "Model Context Protocol endpoint metadata",
        "responses": {
          "200": {
            "description": "MCP metadata"
          }
        }
      },
      "post": {
        "operationId": "mcpRpc",
        "tags": [
          "mcp"
        ],
        "summary": "Model Context Protocol JSON-RPC endpoint",
        "responses": {
          "200": {
            "description": "JSON-RPC response"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-PlatPhorm-API-Key",
        "description": "PLATPHORM_API_KEY for protected (mutating) capabilities. Bearer token also accepted."
      }
    }
  }
}