{
  "openapi": "3.1.0",
  "info": {
    "title": "Synap402 — open-model AI, paid per call",
    "description": "OpenAI-compatible inference for agents. Pay per call in USDC on Base—no account or API key. Dedicated GPUs, streaming responses, and model-level pricing.",
    "version": "1.0.0",
    "contact": {
      "email": "weare@linkrra.com",
      "name": "Linkrra"
    },
    "x-guidance": "# Synap402: open-model inference for agents\n\nOpenAI-compatible chat completions on self-hosted open models, paid per call in USDC (Base or Solana) via x402. No account, no API key.\n\n## When to use this origin\n- You need an LLM completion (coding, JSON extraction, summarising, classification, vision description) and want the cheapest reliable call.\n- Typical cost: $0.001 per call for short requests; larger requests are usage-priced per token, capped at $0.05 per call.\n- Skip this origin for image/video generation, web search, or data enrichment; it sells text completions and the task tools below only (plus Hebrew/English TTS at /api/billing/x402/tts).\n\n## Agent workflow\n1. Read live models and per-token prices: GET /v1/models (free).\n2. Pick a door:\n   - POST /api/billing/x402/chat/completions with \"model\": \"auto\" (cheapest model that fits) or a model id from /v1/models.\n   - Or a fixed-model door: POST /api/billing/x402/models/{model}/chat/completions.\n3. Send a standard OpenAI chat-completions body: {\"model\", \"messages\", optional \"max_tokens\", \"temperature\", \"tools\", \"response_format\", \"stream\"}.\n4. The first request returns 402 with a quote for that exact request in accepts[]; pay it and resend. The 200 is the normal OpenAI chat.completion object.\n\n## Task tools (one fixed job per call, same x402 payment)\n- POST /api/billing/x402/tasks/code-patch {request, files:[{path,content}], language?, test_command?, max_tokens?} -> {patch, explanation, tests}; only supplied files may appear in the unified diff.\n- POST /api/billing/x402/tasks/structured-extraction {text, schema, instructions?, max_tokens?} -> {data} valid against your JSON Schema (checked server-side, one repair retry; still invalid = 422, not charged).\n- POST /api/billing/x402/tasks/vision-inspection {image_url | image_base64, question?} -> {summary, objects, visible_text, assessment} as schema-validated JSON.\n- POST /api/billing/x402/tasks/extract-json {text, schema, instructions?, max_tokens?} -> {data} valid against your JSON Schema (checked server-side, one repair retry; still invalid = 422, not charged).\n- POST /api/billing/x402/tasks/summarize-url {url, max_words?, focus?} -> {summary, title, url}; we fetch the page (public http/https, HTML or plain text, 2 MB, 10 s); a failed fetch is not charged.\n- POST /api/billing/x402/tasks/review-code {diff | code, language?, focus?} -> {summary, issues:[{severity, file?, line?, message, suggestion?}]}.\n- POST /api/billing/x402/tasks/describe-image {image_url | image_base64, question?} -> {description} (Qwen3-VL; PNG, JPEG, GIF or WebP up to 4 MB).\n- Each is quoted before payment from your input (a page or image not fetched yet is priced at its cap) and never charges more than the quote; a task that fails is never settled. First call free does not apply to task tools.\n\n## First call free\n- A new wallet's first call on gpt-oss-20b or qwen3-30b-a3b is free: sign the normal payment, it is verified but not collected. Non-streaming, up to 512 output tokens, within a daily allowance. The response carries X-Linkrra-Free-Call: first-call and payment.free=true.\n\n## Picking a model\n- Code and patches: qwen3-coder-30b.\n- Fast, cheap general and JSON: gpt-oss-20b (supports tools and json_schema).\n- Long context, general: gemma-4-26b-a4b-it (128K).\n- Images (pass image_url content parts): qwen3-vl-30b-a3b-instruct.\n\n## Notes\n- Unknown model names return 402 with suggested_model; it is a suggestion only, never substituted.\n- Set max_tokens to keep the quote low; the quote is for the request as sent.\n- gpt-oss-20b reasons before answering: give it max_tokens of at least 256, or it can spend the whole budget thinking and return empty content.\n- Overpayment is credited to the paying wallet and can be spent on later calls.\n- Prefer prepaid credit for heavy loops: POST /api/billing/x402/topup ($1 to $1000) funds a wallet balance.\n"
  },
  "servers": [
    {
      "url": "https://synap402.com"
    }
  ],
  "x-discovery": {
    "ownershipProofs": [
      "0xa9cc92d7aa63ba465e55198553ddc54ffb34f61ce5d00e2aa8f0dcc24695598632238b7b8e16ee914f2aa53677c75a1a8b53a5e24e02b4d2d33fd363890e35b61b",
      "0x4861df6f03de83d6c9d0799a4f9dbdcefb70fad00c0a9c751ebb753025d7336d100110bcf13e23c700b74cb73be87c5adfac933e43c8fae6a53bc4acba0c932f1c",
      "0x3f7be7eed22ee90a86ddf764f102a0bbe2df56de0deb425c8d219994c31dd8be736210646bd2b01fac74609c8fa5a959489576d275a0284d9c279cfd8c2e02aa1b",
      "565RAxgonF15YBaHTVUhLyrBGySpLNbwCLZLhYc166QxUZeL6vp6V6EtBchR1RNB9oKrQfPcHrw2smtMrtQaEvpq",
      "2mrP7eGJxXxyJWeekexpNdDoyGd7tjyBDdEt3xebbkij6tFEpojeJnoLhRNVQ2X11BX4dRiJ9NPjJDCYqXRMwXad",
      "2FVteGGnUNxrbYEke8DZYcedvoZ6F3W7LnpK6J47BC6jxPUcRj3qfJj9U1Ve7AJA3VYs4KgWBK2YVD8HwwKDirhh"
    ],
    "contactEmail": "michael@linkrra.com",
    "contactNote": "directories/programmes: michael@linkrra.com; API customers: info.contact.email"
  },
  "paths": {
    "/v1/models": {
      "get": {
        "operationId": "listModels",
        "summary": "Model catalogue with per-model USD prices per million tokens. Free.",
        "responses": {
          "200": {
            "description": "OpenAI-style model list with pricing metadata."
          }
        },
        "security": []
      }
    },
    "/api/billing/x402/chat/completions": {
      "post": {
        "operationId": "payPerCallChatCompletion",
        "summary": "LLM chat completions: OpenAI-compatible inference API (gpt-oss-20b, Gemma 4 26B, Qwen3 30B, Qwen3 Coder 30B, Qwen3 VL 30B). Pay per call in USDC on Base via x402, no account, no API key. From $0.001 per call.",
        "x-payment-info": {
          "protocols": [
            {
              "x402": {}
            }
          ],
          "price": {
            "mode": "dynamic",
            "currency": "USD",
            "min": "0.001",
            "max": "0.05"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "model",
                  "messages"
                ],
                "properties": {
                  "model": {
                    "type": "string",
                    "description": "\"auto\" (cheapest fit) or a concrete model id from GET /v1/models"
                  },
                  "messages": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    }
                  },
                  "max_tokens": {
                    "type": "number",
                    "description": "Capped at 4096 (billing/x402-inference.js DEFAULT_MAX_OUTPUT_TOKENS); ask for less and the quote is priced for less"
                  },
                  "stream": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "chat.completion object with usage and payment receipt (tx hash)."
          },
          "402": {
            "description": "x402 v2 PaymentRequired: base64 in the PAYMENT-REQUIRED header and the same JSON in the body, priced for this exact request."
          }
        },
        "description": "Cheap LLM inference for agent loops: one OpenAI-compatible chat completion per paid call. Send model \"auto\" (cheapest fit) or a model id from GET /v1/models. Price is quoted for this exact request: minimum $0.001, usage-priced per token above that. Streaming supported. Unknown model names get a 402 carrying suggested_model with its own accepts[] (suggestion only, never substituted).",
        "tags": [
          "llm",
          "inference",
          "chat-completions"
        ]
      }
    },
    "/api/billing/x402/topup": {
      "post": {
        "operationId": "x402CreditTopup",
        "summary": "Buy prepaid inference credits with one x402 payment; the paying wallet is the account. Minimum top-up $1.00 (max $1000); below $1 is rejected.",
        "x-payment-info": {
          "protocols": [
            {
              "x402": {}
            }
          ],
          "price": {
            "mode": "dynamic",
            "currency": "USD",
            "min": "1.00",
            "max": "1000.00"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "amountUsd"
                ],
                "properties": {
                  "amountUsd": {
                    "type": "number",
                    "minimum": 1,
                    "maximum": 1000
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Credits added; balance and tx hash returned."
          },
          "402": {
            "description": "x402 v2 PaymentRequired challenge."
          }
        }
      }
    },
    "/api/billing/x402/tts": {
      "post": {
        "operationId": "payPerCallTts",
        "summary": "Text-to-speech WAV clip, paid per call with x402 (USDC on Base). Hebrew gets automatic nikud. Minimum charge $0.01 per call; character-based price above it.",
        "x-payment-info": {
          "protocols": [
            {
              "x402": {}
            }
          ],
          "price": {
            "mode": "dynamic",
            "currency": "USD",
            "min": "0.01",
            "max": "0.05"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "text"
                ],
                "properties": {
                  "text": {
                    "type": "string",
                    "maxLength": 4000
                  },
                  "sampleRate": {
                    "type": "number"
                  },
                  "nikud": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "audio/wav bytes."
          },
          "402": {
            "description": "x402 v2 PaymentRequired challenge priced for this text."
          }
        }
      }
    },
    "/v1/chat/completions": {
      "post": {
        "operationId": "chatCompletionApiKey",
        "summary": "OpenAI-compatible chat completion — pay per call in USDC with x402 and no key, or bill an API key's credit balance.",
        "description": "Two ways in, one URL. With `Authorization: Bearer <SYNAP_API_KEY>` the call debits that key's credit ledger (fund it via POST /api/billing/x402/topup; the free tier needs a key too). With NO Authorization header at all the call answers HTTP 402 with x402 v2 payment requirements (base64 in the PAYMENT-REQUIRED header, the same JSON in the body) and serves the completion when repeated with a PAYMENT-SIGNATURE header. Keyless minimum charge $0.001 per call; a key is debited for the tokens used. A wrong or expired key is an authentication error, not a price.",
        "security": [
          {
            "bearerAuth": []
          },
          {}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "model",
                  "messages"
                ],
                "properties": {
                  "model": {
                    "type": "string",
                    "description": "A concrete model id from GET /v1/models"
                  },
                  "messages": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    }
                  },
                  "max_tokens": {
                    "type": "number"
                  },
                  "temperature": {
                    "type": "number"
                  },
                  "stream": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "chat.completion object with usage; balance debited from the API key credit ledger."
          },
          "401": {
            "description": "An Authorization header was sent and it is not a valid Synap key."
          },
          "402": {
            "description": "x402 v2 PaymentRequired (keyless caller): pay it and repeat the request."
          }
        },
        "x-payment-info": {
          "protocols": [
            {
              "x402": {}
            }
          ],
          "price": {
            "mode": "dynamic",
            "currency": "USD",
            "min": "0.001",
            "max": "0.05"
          },
          "keyless": true,
          "canonicalResource": "https://synap402.com/api/billing/x402/chat/completions",
          "note": "Send no Authorization header and this URL answers the x402 402 challenge and accepts the payment in place (one resource identity: the challenge names canonicalResource). Send Authorization: Bearer <key> and it debits that key's credit balance instead."
        }
      }
    },
    "/.well-known/x402": {
      "get": {
        "operationId": "x402Discovery",
        "summary": "x402 discovery document: every paid resource with the live payment requirements its own door quotes. Also served at /.well-known/x402.json.",
        "security": [],
        "responses": {
          "200": {
            "description": "application/json"
          }
        }
      }
    },
    "/x402/discovery/resources": {
      "get": {
        "operationId": "x402BazaarList",
        "summary": "x402 Bazaar discovery list (specs/x402-specification-v2 §8.1 shape). Also at /.well-known/x402/discovery/resources.",
        "security": [],
        "responses": {
          "200": {
            "description": "application/json"
          }
        }
      }
    },
    "/api/billing/x402/models/gpt-oss-20b/chat/completions": {
      "post": {
        "operationId": "payPerCall_gpt_oss_20b",
        "summary": "LLM chat completions on OpenAI gpt-oss-20b (fast, cheap general model, 128K context). OpenAI-compatible, pay per call in USDC on Base via x402, no account, no API key. From $0.001 per call.",
        "x-payment-info": {
          "protocols": [
            {
              "x402": {}
            }
          ],
          "price": {
            "mode": "dynamic",
            "currency": "USD",
            "min": "0.001",
            "max": "0.05"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "messages"
                ],
                "properties": {
                  "model": {
                    "type": "string",
                    "description": "Optional; this door serves \"gpt-oss-20b\" only"
                  },
                  "messages": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    }
                  },
                  "max_tokens": {
                    "type": "number",
                    "description": "Capped at 4096 (billing/x402-inference.js DEFAULT_MAX_OUTPUT_TOKENS); ask for less and the quote is priced for less"
                  },
                  "stream": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "chat.completion object with usage and payment receipt (tx hash)."
          },
          "402": {
            "description": "x402 v2 PaymentRequired: base64 in the PAYMENT-REQUIRED header and the same JSON in the body, priced for this exact request."
          }
        },
        "description": "One OpenAI-compatible chat completion on model \"gpt-oss-20b\" only; the model field may be omitted. Price is quoted for this exact request: minimum $0.001, usage-priced per token above that (GET /v1/models). Streaming supported.",
        "tags": [
          "llm",
          "inference",
          "chat-completions"
        ]
      }
    },
    "/api/billing/x402/models/gemma-4-26b-a4b-it/chat/completions": {
      "post": {
        "operationId": "payPerCall_gemma_4_26b_a4b_it",
        "summary": "LLM chat completions on Google Gemma 4 26B A4B Instruct (fast general model, 128K context). OpenAI-compatible, pay per call in USDC on Base via x402, no account, no API key. From $0.001 per call.",
        "x-payment-info": {
          "protocols": [
            {
              "x402": {}
            }
          ],
          "price": {
            "mode": "dynamic",
            "currency": "USD",
            "min": "0.001",
            "max": "0.05"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "messages"
                ],
                "properties": {
                  "model": {
                    "type": "string",
                    "description": "Optional; this door serves \"gemma-4-26b-a4b-it\" only"
                  },
                  "messages": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    }
                  },
                  "max_tokens": {
                    "type": "number",
                    "description": "Capped at 4096 (billing/x402-inference.js DEFAULT_MAX_OUTPUT_TOKENS); ask for less and the quote is priced for less"
                  },
                  "stream": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "chat.completion object with usage and payment receipt (tx hash)."
          },
          "402": {
            "description": "x402 v2 PaymentRequired: base64 in the PAYMENT-REQUIRED header and the same JSON in the body, priced for this exact request."
          }
        },
        "description": "One OpenAI-compatible chat completion on model \"gemma-4-26b-a4b-it\" only; the model field may be omitted. Price is quoted for this exact request: minimum $0.001, usage-priced per token above that (GET /v1/models). Streaming supported.",
        "tags": [
          "llm",
          "inference",
          "chat-completions"
        ]
      }
    },
    "/api/billing/x402/models/qwen3-30b-a3b/chat/completions": {
      "post": {
        "operationId": "payPerCall_qwen3_30b_a3b",
        "summary": "LLM chat completions on Qwen3 30B A3B Instruct 2507 (general, high-throughput, 96K context). OpenAI-compatible, pay per call in USDC on Base via x402, no account, no API key. From $0.001 per call.",
        "x-payment-info": {
          "protocols": [
            {
              "x402": {}
            }
          ],
          "price": {
            "mode": "dynamic",
            "currency": "USD",
            "min": "0.001",
            "max": "0.05"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "messages"
                ],
                "properties": {
                  "model": {
                    "type": "string",
                    "description": "Optional; this door serves \"qwen/qwen3-30b-a3b\" only"
                  },
                  "messages": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    }
                  },
                  "max_tokens": {
                    "type": "number",
                    "description": "Capped at 4096 (billing/x402-inference.js DEFAULT_MAX_OUTPUT_TOKENS); ask for less and the quote is priced for less"
                  },
                  "stream": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "chat.completion object with usage and payment receipt (tx hash)."
          },
          "402": {
            "description": "x402 v2 PaymentRequired: base64 in the PAYMENT-REQUIRED header and the same JSON in the body, priced for this exact request."
          }
        },
        "description": "One OpenAI-compatible chat completion on model \"qwen/qwen3-30b-a3b\" only; the model field may be omitted. Price is quoted for this exact request: minimum $0.001, usage-priced per token above that (GET /v1/models). Streaming supported.",
        "tags": [
          "llm",
          "inference",
          "chat-completions"
        ]
      }
    },
    "/api/billing/x402/models/qwen3-coder-30b/chat/completions": {
      "post": {
        "operationId": "payPerCall_qwen3_coder_30b",
        "summary": "LLM chat completions on Qwen3 Coder 30B A3B Instruct (code generation and coding agents, 96K context). OpenAI-compatible, pay per call in USDC on Base via x402, no account, no API key. From $0.001 per call.",
        "x-payment-info": {
          "protocols": [
            {
              "x402": {}
            }
          ],
          "price": {
            "mode": "dynamic",
            "currency": "USD",
            "min": "0.001",
            "max": "0.05"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "messages"
                ],
                "properties": {
                  "model": {
                    "type": "string",
                    "description": "Optional; this door serves \"qwen3-coder-30b\" only"
                  },
                  "messages": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    }
                  },
                  "max_tokens": {
                    "type": "number",
                    "description": "Capped at 4096 (billing/x402-inference.js DEFAULT_MAX_OUTPUT_TOKENS); ask for less and the quote is priced for less"
                  },
                  "stream": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "chat.completion object with usage and payment receipt (tx hash)."
          },
          "402": {
            "description": "x402 v2 PaymentRequired: base64 in the PAYMENT-REQUIRED header and the same JSON in the body, priced for this exact request."
          }
        },
        "description": "One OpenAI-compatible chat completion on model \"qwen3-coder-30b\" only; the model field may be omitted. Price is quoted for this exact request: minimum $0.001, usage-priced per token above that (GET /v1/models). Streaming supported.",
        "tags": [
          "llm",
          "inference",
          "chat-completions"
        ]
      }
    },
    "/api/billing/x402/models/qwen3-vl-30b-a3b-instruct/chat/completions": {
      "post": {
        "operationId": "payPerCall_qwen3_vl_30b_a3b_instruct",
        "summary": "LLM chat completions on Qwen3 VL 30B A3B Instruct (vision: images in, text out, 64K context). OpenAI-compatible, pay per call in USDC on Base via x402, no account, no API key. From $0.001 per call.",
        "x-payment-info": {
          "protocols": [
            {
              "x402": {}
            }
          ],
          "price": {
            "mode": "dynamic",
            "currency": "USD",
            "min": "0.001",
            "max": "0.05"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "messages"
                ],
                "properties": {
                  "model": {
                    "type": "string",
                    "description": "Optional; this door serves \"qwen/qwen3-vl-30b-a3b-instruct\" only"
                  },
                  "messages": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    }
                  },
                  "max_tokens": {
                    "type": "number",
                    "description": "Capped at 4096 (billing/x402-inference.js DEFAULT_MAX_OUTPUT_TOKENS); ask for less and the quote is priced for less"
                  },
                  "stream": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "chat.completion object with usage and payment receipt (tx hash)."
          },
          "402": {
            "description": "x402 v2 PaymentRequired: base64 in the PAYMENT-REQUIRED header and the same JSON in the body, priced for this exact request."
          }
        },
        "description": "One OpenAI-compatible chat completion on model \"qwen/qwen3-vl-30b-a3b-instruct\" only; the model field may be omitted. Price is quoted for this exact request: minimum $0.001, usage-priced per token above that (GET /v1/models). Streaming supported.",
        "tags": [
          "llm",
          "inference",
          "chat-completions"
        ]
      }
    },
    "/api/billing/x402/tasks/extract-json": {
      "post": {
        "operationId": "payPerCallExtractJson",
        "summary": "Extract structured JSON from text that validates against your JSON Schema (server-side validation, one repair retry). Pay per call in USDC via x402, no account, no API key. From $0.001 per call.",
        "description": "Synap402 - JSON extraction: send text and a JSON Schema, get data validated against that schema server-side (one automatic repair retry). Output still invalid = 422 and nothing is charged. Open models on dedicated GPUs. Pay per call in USDC on any network in the payment challenge; no account, no API key.",
        "x-payment-info": {
          "protocols": [
            {
              "x402": {}
            }
          ],
          "price": {
            "mode": "dynamic",
            "currency": "USD",
            "min": "0.001",
            "max": "0.05"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "text",
                  "schema"
                ],
                "properties": {
                  "text": {
                    "type": "string",
                    "maxLength": 100000,
                    "description": "Source text to extract from (untrusted data)."
                  },
                  "schema": {
                    "type": "object",
                    "description": "JSON Schema the result must validate against (<= 16 KB, local $ref only)."
                  },
                  "instructions": {
                    "type": "string",
                    "maxLength": 2000,
                    "description": "Optional extra guidance."
                  },
                  "max_tokens": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 2048,
                    "default": 768,
                    "description": "Output cap; raise for large records."
                  }
                }
              },
              "example": {
                "text": "Invoice INV-2041 from Acme Corp, total $1,250.00, due 2026-12-01.",
                "schema": {
                  "type": "object",
                  "required": [
                    "invoice_number",
                    "vendor",
                    "total"
                  ],
                  "properties": {
                    "invoice_number": {
                      "type": "string"
                    },
                    "vendor": {
                      "type": "string"
                    },
                    "total": {
                      "type": "number"
                    },
                    "due_date": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The task result, with usage and the payment receipt (PAYMENT-RESPONSE header).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "model",
                    "usage"
                  ],
                  "properties": {
                    "data": {
                      "description": "The extracted value, valid against the schema you sent."
                    },
                    "model": {
                      "type": "string"
                    },
                    "usage": {
                      "$ref": "#/components/schemas/TaskUsage"
                    },
                    "payment": {
                      "$ref": "#/components/schemas/TaskPayment"
                    }
                  }
                },
                "example": {
                  "data": {
                    "invoice_number": "INV-2041",
                    "vendor": "Acme Corp",
                    "total": 1250,
                    "due_date": "2026-12-01"
                  },
                  "model": "qwen3-coder-30b",
                  "usage": {
                    "prompt_tokens": 210,
                    "completion_tokens": 38,
                    "total_tokens": 248
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input (including a URL that is not a public http/https address). Refused before payment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskError"
                }
              }
            }
          },
          "402": {
            "description": "x402 v2 PaymentRequired: base64 in the PAYMENT-REQUIRED header and the same JSON in the body, priced for this exact input."
          },
          "409": {
            "description": "This payment authorization was already used (or is in use by a request in progress).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskError"
                }
              }
            }
          },
          "413": {
            "description": "Input too large, or the quote would exceed the per-call ceiling. Refused before payment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskError"
                }
              }
            }
          },
          "422": {
            "description": "The output did not validate against your schema after one repair retry; error.errors lists why. Nothing was charged.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskError"
                }
              }
            }
          },
          "503": {
            "description": "No node is serving this task right now. Nothing was charged.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskError"
                }
              }
            }
          }
        },
        "tags": [
          "llm",
          "tasks",
          "extract-json"
        ]
      }
    },
    "/api/billing/x402/tasks/summarize-url": {
      "post": {
        "operationId": "payPerCallSummarizeUrl",
        "summary": "Summarize a web page: send a URL, we fetch it server-side and return a faithful summary and the page title. Pay per call in USDC via x402, no account, no API key. From $0.001 per call.",
        "description": "Synap402 - summarize a web page: send a URL, we fetch it server-side (public http/https, HTML or plain text, 2 MB, 10 s) and return a faithful summary plus the page title. Fetch fails = no charge. Open models on dedicated GPUs. Pay per call in USDC on any network in the payment challenge; no account, no API key.",
        "x-payment-info": {
          "protocols": [
            {
              "x402": {}
            }
          ],
          "price": {
            "mode": "dynamic",
            "currency": "USD",
            "min": "0.001",
            "max": "0.05"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "description": "Public http(s) URL, ports 80/443. Page text is treated as data."
                  },
                  "max_words": {
                    "type": "integer",
                    "minimum": 20,
                    "maximum": 1000,
                    "default": 200,
                    "description": "Summary length cap."
                  },
                  "focus": {
                    "type": "string",
                    "maxLength": 500,
                    "description": "Optional: what to focus on."
                  }
                }
              },
              "example": {
                "url": "https://example.com",
                "max_words": 120
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The task result, with usage and the payment receipt (PAYMENT-RESPONSE header).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "summary",
                    "title",
                    "url",
                    "model",
                    "usage"
                  ],
                  "properties": {
                    "summary": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string",
                      "description": "The URL summarised, after redirects."
                    },
                    "truncated": {
                      "type": "boolean",
                      "description": "true when only the first part of a long page was summarised."
                    },
                    "model": {
                      "type": "string"
                    },
                    "usage": {
                      "$ref": "#/components/schemas/TaskUsage"
                    },
                    "payment": {
                      "$ref": "#/components/schemas/TaskPayment"
                    }
                  }
                },
                "example": {
                  "summary": "A placeholder page reserved for documentation examples. - The domain may be used in docs without permission.",
                  "title": "Example Domain",
                  "url": "https://example.com/",
                  "truncated": false,
                  "model": "gemma-4-26b-a4b-it",
                  "usage": {
                    "prompt_tokens": 160,
                    "completion_tokens": 45,
                    "total_tokens": 205
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input (including a URL that is not a public http/https address). Refused before payment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskError"
                }
              }
            }
          },
          "402": {
            "description": "x402 v2 PaymentRequired: base64 in the PAYMENT-REQUIRED header and the same JSON in the body, priced for this exact input."
          },
          "409": {
            "description": "This payment authorization was already used (or is in use by a request in progress).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskError"
                }
              }
            }
          },
          "413": {
            "description": "Input too large, or the quote would exceed the per-call ceiling. Refused before payment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskError"
                }
              }
            }
          },
          "415": {
            "description": "The URL did not return HTML or plain text. Nothing was charged.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskError"
                }
              }
            }
          },
          "422": {
            "description": "The page has no readable text. Nothing was charged.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskError"
                }
              }
            }
          },
          "502": {
            "description": "The page could not be fetched (or the model failed). Nothing was charged.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskError"
                }
              }
            }
          },
          "503": {
            "description": "No node is serving this task right now. Nothing was charged.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskError"
                }
              }
            }
          }
        },
        "tags": [
          "llm",
          "tasks",
          "summarize-url"
        ]
      }
    },
    "/api/billing/x402/tasks/review-code": {
      "post": {
        "operationId": "payPerCallReviewCode",
        "summary": "Code review of a unified diff or source code: a summary plus JSON issues with severity, file, line, message and suggested fix. Pay per call in USDC via x402, no account, no API key. From $0.001 per call.",
        "description": "Synap402 - code review: send a unified diff or source code, get a summary and a JSON list of issues (severity, file, line, message, suggestion) - bugs, security, edge cases, no style nits. Invalid model output = no charge. Open models on dedicated GPUs. Pay per call in USDC on any network in the payment challenge; no account, no API key.",
        "x-payment-info": {
          "protocols": [
            {
              "x402": {}
            }
          ],
          "price": {
            "mode": "dynamic",
            "currency": "USD",
            "min": "0.001",
            "max": "0.05"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "diff": {
                    "type": "string",
                    "maxLength": 100000,
                    "description": "A unified diff (send diff OR code)."
                  },
                  "code": {
                    "type": "string",
                    "maxLength": 100000,
                    "description": "Source code (send diff OR code)."
                  },
                  "language": {
                    "type": "string",
                    "maxLength": 40
                  },
                  "focus": {
                    "type": "string",
                    "maxLength": 500,
                    "description": "Optional: e.g. \"security\"."
                  },
                  "max_tokens": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 2048,
                    "default": 1536
                  }
                },
                "anyOf": [
                  {
                    "required": [
                      "diff"
                    ]
                  },
                  {
                    "required": [
                      "code"
                    ]
                  }
                ]
              },
              "example": {
                "diff": "--- a/app.py\n+++ b/app.py\n@@ -1,2 +1,2 @@\n def get_user(db, uid):\n-    return db.query(\"SELECT * FROM users WHERE id = %s\", (uid,))\n+    return db.query(f\"SELECT * FROM users WHERE id = {uid}\")\n",
                "language": "python",
                "max_tokens": 512
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The task result, with usage and the payment receipt (PAYMENT-RESPONSE header).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "summary",
                    "issues",
                    "model",
                    "usage"
                  ],
                  "properties": {
                    "summary": {
                      "type": "string"
                    },
                    "issues": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "severity",
                          "message"
                        ],
                        "properties": {
                          "severity": {
                            "type": "string",
                            "enum": [
                              "critical",
                              "high",
                              "medium",
                              "low",
                              "info"
                            ]
                          },
                          "file": {
                            "type": "string"
                          },
                          "line": {
                            "type": "integer"
                          },
                          "message": {
                            "type": "string"
                          },
                          "suggestion": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "model": {
                      "type": "string"
                    },
                    "usage": {
                      "$ref": "#/components/schemas/TaskUsage"
                    },
                    "payment": {
                      "$ref": "#/components/schemas/TaskPayment"
                    }
                  }
                },
                "example": {
                  "summary": "Replaces a parameterised query with an f-string: SQL injection. Request changes.",
                  "issues": [
                    {
                      "severity": "critical",
                      "file": "app.py",
                      "line": 2,
                      "message": "uid is interpolated into SQL: injection.",
                      "suggestion": "Keep the parameterised query: db.query(\"... WHERE id = %s\", (uid,))."
                    }
                  ],
                  "model": "qwen3-coder-30b",
                  "usage": {
                    "prompt_tokens": 260,
                    "completion_tokens": 90,
                    "total_tokens": 350
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input (including a URL that is not a public http/https address). Refused before payment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskError"
                }
              }
            }
          },
          "402": {
            "description": "x402 v2 PaymentRequired: base64 in the PAYMENT-REQUIRED header and the same JSON in the body, priced for this exact input."
          },
          "409": {
            "description": "This payment authorization was already used (or is in use by a request in progress).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskError"
                }
              }
            }
          },
          "413": {
            "description": "Input too large, or the quote would exceed the per-call ceiling. Refused before payment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskError"
                }
              }
            }
          },
          "502": {
            "description": "The model did not return a well-formed review after one repair retry. Nothing was charged.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskError"
                }
              }
            }
          },
          "503": {
            "description": "No node is serving this task right now. Nothing was charged.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskError"
                }
              }
            }
          }
        },
        "tags": [
          "llm",
          "tasks",
          "review-code"
        ]
      }
    },
    "/api/billing/x402/tasks/describe-image": {
      "post": {
        "operationId": "payPerCallDescribeImage",
        "summary": "Describe an image (vision, OCR of visible text): send image_url or image_base64 and an optional question. Qwen3-VL. Pay per call in USDC via x402, no account, no API key. From $0.001 per call.",
        "description": "Synap402 - describe an image: send image_url (fetched server-side, public URLs only) or image_base64 (PNG, JPEG, GIF, WebP, 4 MB) and an optional question; get a precise description with visible text transcribed. Qwen3-VL on dedicated GPUs. Fetch fails = no charge. Pay per call in USDC; no account, no API key.",
        "x-payment-info": {
          "protocols": [
            {
              "x402": {}
            }
          ],
          "price": {
            "mode": "dynamic",
            "currency": "USD",
            "min": "0.001",
            "max": "0.05"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "image_url": {
                    "type": "string",
                    "format": "uri",
                    "description": "Public http(s) image URL (send image_url OR image_base64)."
                  },
                  "image_base64": {
                    "type": "string",
                    "description": "Raw base64 or data:image/...;base64,... (PNG/JPEG/GIF/WebP, 4 MB)."
                  },
                  "question": {
                    "type": "string",
                    "maxLength": 1000,
                    "description": "Optional: what to look for."
                  },
                  "max_tokens": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 1024,
                    "default": 768
                  }
                },
                "anyOf": [
                  {
                    "required": [
                      "image_url"
                    ]
                  },
                  {
                    "required": [
                      "image_base64"
                    ]
                  }
                ]
              },
              "example": {
                "image_url": "https://upload.wikimedia.org/wikipedia/commons/4/47/PNG_transparency_demonstration_1.png",
                "question": "What is in this image?"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The task result, with usage and the payment receipt (PAYMENT-RESPONSE header).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "description",
                    "model",
                    "usage"
                  ],
                  "properties": {
                    "description": {
                      "type": "string"
                    },
                    "model": {
                      "type": "string"
                    },
                    "usage": {
                      "$ref": "#/components/schemas/TaskUsage"
                    },
                    "payment": {
                      "$ref": "#/components/schemas/TaskPayment"
                    }
                  }
                },
                "example": {
                  "description": "Two dice rendered in 3D on a checkerboard background showing transparency...",
                  "model": "qwen/qwen3-vl-30b-a3b-instruct",
                  "usage": {
                    "prompt_tokens": 1210,
                    "completion_tokens": 60,
                    "total_tokens": 1270
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input (including a URL that is not a public http/https address). Refused before payment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskError"
                }
              }
            }
          },
          "402": {
            "description": "x402 v2 PaymentRequired: base64 in the PAYMENT-REQUIRED header and the same JSON in the body, priced for this exact input."
          },
          "409": {
            "description": "This payment authorization was already used (or is in use by a request in progress).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskError"
                }
              }
            }
          },
          "413": {
            "description": "Input too large, or the quote would exceed the per-call ceiling. Refused before payment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskError"
                }
              }
            }
          },
          "415": {
            "description": "Not a PNG, JPEG, GIF or WebP image. Nothing was charged.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskError"
                }
              }
            }
          },
          "502": {
            "description": "The image could not be fetched (or the model failed). Nothing was charged.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskError"
                }
              }
            }
          },
          "503": {
            "description": "No node is serving this task right now. Nothing was charged.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskError"
                }
              }
            }
          }
        },
        "tags": [
          "llm",
          "tasks",
          "describe-image"
        ]
      }
    },
    "/api/billing/x402/tasks/code-patch": {
      "post": {
        "operationId": "payPerCallCodePatch",
        "summary": "Create a bounded code patch: send a change request and source files, receive a validated unified diff, explanation, and tests. Pay per call in USDC via x402.",
        "description": "Synap402 - code patch: send a bounded change request and the source files it may edit; get a server-validated JSON result containing a unified diff, explanation, and tests. The patch may name only supplied files. Invalid model output = no charge. Pay per call in USDC via x402; no account or API key.",
        "x-payment-info": {
          "protocols": [
            {
              "x402": {}
            }
          ],
          "price": {
            "mode": "dynamic",
            "currency": "USD",
            "min": "0.001",
            "max": "0.05"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "request",
                  "files"
                ],
                "properties": {
                  "request": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 4000,
                    "description": "The exact change to make."
                  },
                  "files": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 20,
                    "items": {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "path",
                        "content"
                      ],
                      "properties": {
                        "path": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 300
                        },
                        "content": {
                          "type": "string",
                          "maxLength": 100000
                        }
                      }
                    }
                  },
                  "language": {
                    "type": "string",
                    "maxLength": 40
                  },
                  "test_command": {
                    "type": "string",
                    "maxLength": 500
                  },
                  "max_tokens": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 2048,
                    "default": 1536
                  }
                }
              },
              "example": {
                "request": "Return HTTP 400 when name is blank.",
                "language": "javascript",
                "files": [
                  {
                    "path": "src/handler.js",
                    "content": "export function handler(name) { return { status: 200, body: name }; }\n"
                  }
                ],
                "test_command": "npm test",
                "max_tokens": 1024
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The task result, with usage and the payment receipt (PAYMENT-RESPONSE header).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "patch",
                    "explanation",
                    "tests",
                    "model",
                    "usage",
                    "payment"
                  ],
                  "properties": {
                    "patch": {
                      "type": "string",
                      "description": "Unified diff naming only files supplied in the request."
                    },
                    "explanation": {
                      "type": "string"
                    },
                    "tests": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "model": {
                      "type": "string"
                    },
                    "usage": {
                      "$ref": "#/components/schemas/TaskUsage"
                    },
                    "payment": {
                      "$ref": "#/components/schemas/TaskPayment"
                    }
                  }
                },
                "example": {
                  "patch": "--- a/src/handler.js\n+++ b/src/handler.js\n@@ -1 +1,4 @@\n-export function handler(name) { return { status: 200, body: name }; }\n+export function handler(name) {\n+  if (!name || !name.trim()) return { status: 400, body: \"name is required\" };\n+  return { status: 200, body: name };\n+}\n",
                  "explanation": "Rejects missing or whitespace-only names before producing the success response.",
                  "tests": [
                    "npm test",
                    "Add cases for an empty string and whitespace-only input."
                  ],
                  "model": "qwen3-coder-30b",
                  "usage": {
                    "prompt_tokens": 190,
                    "completion_tokens": 130,
                    "total_tokens": 320,
                    "calls": 1
                  },
                  "payment": {
                    "paidUsd": 0.001,
                    "quotedUsd": 0.001,
                    "transaction": "0xexample",
                    "network": "eip155:8453",
                    "payerAddress": "0x0000000000000000000000000000000000000000"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input (including a URL that is not a public http/https address). Refused before payment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskError"
                }
              }
            }
          },
          "402": {
            "description": "x402 v2 PaymentRequired: base64 in the PAYMENT-REQUIRED header and the same JSON in the body, priced for this exact input."
          },
          "409": {
            "description": "This payment authorization was already used (or is in use by a request in progress).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskError"
                }
              }
            }
          },
          "413": {
            "description": "Input too large, or the quote would exceed the per-call ceiling. Refused before payment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskError"
                }
              }
            }
          },
          "422": {
            "description": "The generated patch did not pass the strict output contract after one repair retry. Nothing was charged.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskError"
                }
              }
            }
          },
          "503": {
            "description": "No node is serving this task right now. Nothing was charged.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskError"
                }
              }
            }
          }
        },
        "tags": [
          "llm",
          "tasks",
          "code-patch"
        ]
      }
    },
    "/api/billing/x402/tasks/structured-extraction": {
      "post": {
        "operationId": "payPerCallStructuredExtraction",
        "summary": "Extract structured data from text under a caller-supplied JSON Schema, with server-side validation. Pay per call in USDC via x402.",
        "description": "Synap402 - structured extraction: send source text and a strict JSON Schema; get data validated against that schema server-side. The request contract rejects unknown fields, and invalid model output is repaired once or returned uncharged. Pay per call in USDC via x402; no account or API key.",
        "x-payment-info": {
          "protocols": [
            {
              "x402": {}
            }
          ],
          "price": {
            "mode": "dynamic",
            "currency": "USD",
            "min": "0.001",
            "max": "0.05"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "text",
                  "schema"
                ],
                "properties": {
                  "text": {
                    "type": "string",
                    "maxLength": 100000,
                    "description": "Source text to extract from (untrusted data)."
                  },
                  "schema": {
                    "type": "object",
                    "description": "JSON Schema the result must validate against (<= 16 KB, local $ref only)."
                  },
                  "instructions": {
                    "type": "string",
                    "maxLength": 2000,
                    "description": "Optional extra guidance."
                  },
                  "max_tokens": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 2048,
                    "default": 768,
                    "description": "Output cap; raise for large records."
                  }
                },
                "additionalProperties": false
              },
              "example": {
                "text": "Invoice INV-2041 from Acme Corp, total $1,250.00, due 2026-12-01.",
                "schema": {
                  "type": "object",
                  "required": [
                    "invoice_number",
                    "vendor",
                    "total"
                  ],
                  "properties": {
                    "invoice_number": {
                      "type": "string"
                    },
                    "vendor": {
                      "type": "string"
                    },
                    "total": {
                      "type": "number"
                    },
                    "due_date": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The task result, with usage and the payment receipt (PAYMENT-RESPONSE header).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "data",
                    "model",
                    "usage",
                    "payment"
                  ],
                  "properties": {
                    "data": {
                      "description": "The extracted value, valid against the schema sent in the request."
                    },
                    "model": {
                      "type": "string"
                    },
                    "usage": {
                      "$ref": "#/components/schemas/TaskUsage"
                    },
                    "payment": {
                      "$ref": "#/components/schemas/TaskPayment"
                    }
                  }
                },
                "example": {
                  "data": {
                    "invoice_number": "INV-2041",
                    "vendor": "Acme Corp",
                    "total": 1250,
                    "due_date": "2026-12-01"
                  },
                  "model": "qwen3-coder-30b",
                  "usage": {
                    "prompt_tokens": 210,
                    "completion_tokens": 38,
                    "total_tokens": 248,
                    "calls": 1
                  },
                  "payment": {
                    "paidUsd": 0.001,
                    "quotedUsd": 0.001,
                    "transaction": "0xexample",
                    "network": "eip155:8453",
                    "payerAddress": "0x0000000000000000000000000000000000000000"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input (including a URL that is not a public http/https address). Refused before payment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskError"
                }
              }
            }
          },
          "402": {
            "description": "x402 v2 PaymentRequired: base64 in the PAYMENT-REQUIRED header and the same JSON in the body, priced for this exact input."
          },
          "409": {
            "description": "This payment authorization was already used (or is in use by a request in progress).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskError"
                }
              }
            }
          },
          "413": {
            "description": "Input too large, or the quote would exceed the per-call ceiling. Refused before payment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskError"
                }
              }
            }
          },
          "422": {
            "description": "The output did not validate against the supplied schema after one repair retry. Nothing was charged.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskError"
                }
              }
            }
          },
          "503": {
            "description": "No node is serving this task right now. Nothing was charged.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskError"
                }
              }
            }
          }
        },
        "tags": [
          "llm",
          "tasks",
          "structured-extraction"
        ]
      }
    },
    "/api/billing/x402/tasks/vision-inspection": {
      "post": {
        "operationId": "payPerCallVisionInspection",
        "summary": "Inspect an image and receive schema-validated objects, visible text, summary, and assessment. Pay per call in USDC via x402.",
        "description": "Synap402 - vision inspection: send a public image URL or base64 image and receive server-validated JSON with summary, objects, visible text, and a quality/category assessment. Unknown input fields and malformed model output are rejected; task failure is not charged. Pay per call in USDC via x402.",
        "x-payment-info": {
          "protocols": [
            {
              "x402": {}
            }
          ],
          "price": {
            "mode": "dynamic",
            "currency": "USD",
            "min": "0.001",
            "max": "0.05"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "image_url": {
                    "type": "string",
                    "format": "uri",
                    "description": "Public http(s) image URL (send image_url OR image_base64)."
                  },
                  "image_base64": {
                    "type": "string",
                    "description": "Raw base64 or data:image/...;base64,... (PNG/JPEG/GIF/WebP, 4 MB)."
                  },
                  "question": {
                    "type": "string",
                    "maxLength": 1000,
                    "description": "Optional: what to look for."
                  },
                  "max_tokens": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 1024,
                    "default": 768
                  }
                },
                "additionalProperties": false,
                "anyOf": [
                  {
                    "required": [
                      "image_url"
                    ]
                  },
                  {
                    "required": [
                      "image_base64"
                    ]
                  }
                ]
              },
              "example": {
                "image_url": "https://upload.wikimedia.org/wikipedia/commons/4/47/PNG_transparency_demonstration_1.png",
                "question": "Inspect the objects and visible text.",
                "max_tokens": 1024
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The task result, with usage and the payment receipt (PAYMENT-RESPONSE header).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "summary",
                    "objects",
                    "visible_text",
                    "assessment",
                    "model",
                    "usage",
                    "payment"
                  ],
                  "properties": {
                    "summary": {
                      "type": "string"
                    },
                    "objects": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": false,
                        "required": [
                          "label",
                          "details"
                        ],
                        "properties": {
                          "label": {
                            "type": "string"
                          },
                          "details": {
                            "type": "string"
                          },
                          "location": {
                            "type": [
                              "string",
                              "null"
                            ]
                          }
                        }
                      }
                    },
                    "visible_text": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "assessment": {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "category",
                        "quality",
                        "warnings"
                      ],
                      "properties": {
                        "category": {
                          "type": "string",
                          "enum": [
                            "photo",
                            "screenshot",
                            "document",
                            "diagram",
                            "chart",
                            "other"
                          ]
                        },
                        "quality": {
                          "type": "string",
                          "enum": [
                            "clear",
                            "partly_clear",
                            "poor"
                          ]
                        },
                        "warnings": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "model": {
                      "type": "string"
                    },
                    "usage": {
                      "$ref": "#/components/schemas/TaskUsage"
                    },
                    "payment": {
                      "$ref": "#/components/schemas/TaskPayment"
                    }
                  }
                },
                "example": {
                  "summary": "Two rendered dice appear on a checkerboard transparency background.",
                  "objects": [
                    {
                      "label": "die",
                      "details": "A red translucent six-sided die.",
                      "location": "left"
                    },
                    {
                      "label": "die",
                      "details": "A white six-sided die.",
                      "location": "right"
                    }
                  ],
                  "visible_text": [],
                  "assessment": {
                    "category": "other",
                    "quality": "clear",
                    "warnings": []
                  },
                  "model": "qwen/qwen3-vl-30b-a3b-instruct",
                  "usage": {
                    "prompt_tokens": 1210,
                    "completion_tokens": 120,
                    "total_tokens": 1330,
                    "calls": 1
                  },
                  "payment": {
                    "paidUsd": 0.001,
                    "quotedUsd": 0.001,
                    "transaction": "0xexample",
                    "network": "eip155:8453",
                    "payerAddress": "0x0000000000000000000000000000000000000000"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input (including a URL that is not a public http/https address). Refused before payment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskError"
                }
              }
            }
          },
          "402": {
            "description": "x402 v2 PaymentRequired: base64 in the PAYMENT-REQUIRED header and the same JSON in the body, priced for this exact input."
          },
          "409": {
            "description": "This payment authorization was already used (or is in use by a request in progress).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskError"
                }
              }
            }
          },
          "413": {
            "description": "Input too large, or the quote would exceed the per-call ceiling. Refused before payment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskError"
                }
              }
            }
          },
          "415": {
            "description": "Not a PNG, JPEG, GIF or WebP image. Nothing was charged.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskError"
                }
              }
            }
          },
          "422": {
            "description": "The generated inspection did not pass the strict output contract after one repair retry. Nothing was charged.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskError"
                }
              }
            }
          },
          "502": {
            "description": "The image could not be fetched (or the model failed). Nothing was charged.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskError"
                }
              }
            }
          },
          "503": {
            "description": "No node is serving this task right now. Nothing was charged.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskError"
                }
              }
            }
          }
        },
        "tags": [
          "llm",
          "tasks",
          "vision-inspection"
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Synap API key (Authorization: Bearer <key>)"
      }
    },
    "schemas": {
      "TaskUsage": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "prompt_tokens",
          "completion_tokens",
          "total_tokens",
          "calls"
        ],
        "properties": {
          "prompt_tokens": {
            "type": "integer"
          },
          "completion_tokens": {
            "type": "integer"
          },
          "total_tokens": {
            "type": "integer"
          },
          "calls": {
            "type": "integer",
            "description": "Model calls made (2 when a repair retry ran)."
          }
        }
      },
      "TaskPayment": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "paidUsd",
          "quotedUsd",
          "transaction",
          "network",
          "payerAddress"
        ],
        "description": "USDC paid and the settlement transaction; any unused part stays credited to the paying wallet.",
        "properties": {
          "paidUsd": {
            "type": "number"
          },
          "quotedUsd": {
            "type": "number"
          },
          "creditsGranted": {
            "type": "integer"
          },
          "creditsCharged": {
            "type": "integer"
          },
          "creditsRemaining": {
            "type": "integer"
          },
          "transaction": {
            "type": "string"
          },
          "network": {
            "type": "string"
          },
          "payerAddress": {
            "type": "string"
          },
          "note": {
            "type": "string"
          }
        }
      },
      "TaskError": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "message": {
                "type": "string"
              },
              "code": {
                "type": "string"
              },
              "type": {
                "type": "string"
              }
            }
          },
          "payment": {
            "type": "object",
            "properties": {
              "charged": {
                "type": "boolean",
                "description": "false: the payment was verified but never settled."
              }
            }
          }
        }
      }
    }
  }
}
