{
 "openapi": "3.1.0",
 "info": {
  "title": "TopxAI API",
  "version": "2026-11-12",
  "summary": "One OpenAI- and Anthropic-compatible endpoint for Claude, GPT, Grok, GLM, Kimi, DeepSeek and Jev.",
  "description": "TopxAI relays requests to the model providers at fixed USD prices on prepaid credit. The request body is forwarded unchanged and the response is returned unchanged, except where a request in another format has to be converted for the model (for example /v1/messages to a model other than Claude), on /v1/messages to claude-fable-5-2, where temperature, top_p and top_k are removed, on /v1/responses, where the echoes of the request and members the upstream adds are rewritten, and on /v1/chat/completions, where provider_specific_fields, a member some upstream capacity adds, is removed; parameters not listed here pass through to the provider. A request without a system prompt that reaches the GPT provider's Responses API (gpt-6.1-sol and gpt-6.1-terra on every endpoint, gpt-6-astra on /v1/responses) is sent the instructions \"You are a helpful assistant.\", so the provider does not add its own longer prompt; a request with its own system prompt or instructions is forwarded as sent. Base URL for OpenAI-style SDKs: https://api.topxai.xyz/v1. Base URL for the Anthropic SDK: https://api.topxai.xyz. Prompts, completions and files are relayed in memory and never stored. Prices: https://api.topxai.xyz/pricing and https://api.topxai.xyz/api/pricing.",
  "termsOfService": "https://api.topxai.xyz/user-agreement",
  "contact": {
   "name": "TopxAI support",
   "email": "support@topxai.xyz",
   "url": "https://api.topxai.xyz/docs"
  },
  "x-logo": {
   "url": "https://api.topxai.xyz/favicon.svg"
  },
  "license": {
   "name": "Terms of use",
   "url": "https://api.topxai.xyz/user-agreement"
  }
 },
 "externalDocs": {
  "description": "Documentation",
  "url": "https://api.topxai.xyz/docs"
 },
 "servers": [
  {
   "url": "https://api.topxai.xyz",
   "description": "Production"
  }
 ],
 "security": [
  {
   "bearerAuth": []
  }
 ],
 "tags": [
  {
   "name": "OpenAI-compatible",
   "description": "Chat Completions, Responses, Images, Video and the model list, with Authorization: Bearer <key>."
  },
  {
   "name": "Anthropic-compatible",
   "description": "The Messages API for every text model except Jev, with x-api-key or Authorization: Bearer."
  },
  {
   "name": "TypeSafe",
   "description": "System One: typed questions about a state, answered with probabilities."
  },
  {
   "name": "Public",
   "description": "No key needed."
  }
 ],
 "paths": {
  "/v1/chat/completions": {
   "post": {
    "tags": [
     "OpenAI-compatible"
    ],
    "operationId": "createChatCompletion",
    "summary": "Chat Completions",
    "description": "OpenAI Chat Completions for every text model except Jev. Streaming with stream: true returns server-sent events.",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/ChatCompletionRequest"
       },
       "example": {
        "model": "claude-sonnet-5-5",
        "messages": [
         {
          "role": "user",
          "content": "Say hello in one sentence."
         }
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "The provider's chat completion, unchanged apart from provider_specific_fields, which some upstream capacity adds and the relay removes; usage carries the token counts the charge was settled from.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ChatCompletionResponse"
        }
       },
       "text/event-stream": {
        "schema": {
         "type": "string"
        }
       }
      }
     },
     "400": {
      "description": "The body failed validation; the message says which field.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "401": {
      "description": "The key is missing or invalid.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "402": {
      "description": "The balance is empty.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "403": {
      "description": "The model is not sold here, is not on this key's route, or is excluded by the key's model limits.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Rate limited; Retry-After gives the wait in seconds.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "503": {
      "description": "No line can serve the model right now, or the provider is overloaded; retry.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/v1/responses": {
   "post": {
    "tags": [
     "OpenAI-compatible"
    ],
    "operationId": "createResponse",
    "summary": "Responses",
    "description": "OpenAI Responses API for gpt-6-astra, gpt-6.1-sol, gpt-6.1-terra, grok-4.7, GLM-5.3-Flash-Abliterated, kimi-k3.1-pro, deepseek-flash-Abliterated and deepseek-flash-fast. Codex CLI uses this endpoint. The last four are private deployments: send the full conversation in input, since persistent conversation workflows on them have not been verified.",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/ResponsesRequest"
       },
       "example": {
        "model": "gpt-6.1-sol",
        "input": "Say hello in one sentence."
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "The provider's response object. instructions, metadata, safety_identifier and prompt_cache_key show the values the request sent, and members no Responses API defines that the upstream adds are removed, in the body and in every stream event.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "additionalProperties": true
        }
       },
       "text/event-stream": {
        "schema": {
         "type": "string"
        }
       }
      }
     },
     "400": {
      "description": "The body failed validation; the message says which field.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "401": {
      "description": "The key is missing or invalid.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "402": {
      "description": "The balance is empty.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "403": {
      "description": "The model is not sold here, is not on this key's route, or is excluded by the key's model limits.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Rate limited; Retry-After gives the wait in seconds.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "503": {
      "description": "No line can serve the model right now, or the provider is overloaded; retry.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/v1/messages": {
   "post": {
    "tags": [
     "Anthropic-compatible"
    ],
    "operationId": "createMessage",
    "summary": "Messages",
    "description": "Anthropic Messages API for every text model except Jev. Claude models get the request in Anthropic's own format, cache_control included, and prompt caching bills at the cache-read and cache-write prices; the relay sets a missing max_tokens to the model's output limit and drops service_tier, inference_geo and speed. The other models get a conversion and answer in the Messages format: gpt-6.1-sol and gpt-6.1-terra through the Responses API, the rest through Chat Completions. Send the key as x-api-key (the Anthropic SDK does) or as a Bearer token. Without max_tokens, the DeepSeek models get their output limit, 131072 on deepseek-flash-Abliterated and 262144 on deepseek-flash-fast (cut to what the context window leaves after the prompt), and the other converted models are sent no cap. The Chat Completions conversion keeps cache_control on text, image and document blocks only, and the Responses conversion drops it. On the Chat Completions models a tool_result keeps its text on the tool message and its images move to the following user message, and a tool_result holding a document is a 400; thinking blocks in the history are dropped on gpt-6.1-sol and gpt-6.1-terra, and redacted_thinking blocks on every converted model; stop_sequences on grok-4.7 is a 400; GLM-5.3-Abliterated takes text only: each image or document block reaches it as the note \"[Attachment omitted: this model accepts text only.]\", as on Chat Completions.",
    "security": [
     {
      "anthropicKey": []
     },
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "name": "anthropic-version",
      "in": "header",
      "required": false,
      "description": "Optional. Claude gets this value, or 2023-06-01 when it is absent; the converted requests do not carry it.",
      "schema": {
       "type": "string",
       "example": "2023-06-01"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/MessagesRequest"
       },
       "example": {
        "model": "claude-sonnet-5-5",
        "max_tokens": 256,
        "messages": [
         {
          "role": "user",
          "content": "Say hello in one sentence."
         }
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "The answer as a Messages object: Claude's unchanged, the other models' converted from Chat Completions or Responses.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "additionalProperties": true
        }
       },
       "text/event-stream": {
        "schema": {
         "type": "string"
        }
       }
      }
     },
     "400": {
      "description": "The body failed validation; the message says which field.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "401": {
      "description": "The key is missing or invalid.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "402": {
      "description": "The balance is empty.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "403": {
      "description": "The model is not sold here, is not on this key's route, or is excluded by the key's model limits.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Rate limited; Retry-After gives the wait in seconds.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "503": {
      "description": "No line can serve the model right now, or the provider is overloaded; retry.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/v1/images/generations": {
   "post": {
    "tags": [
     "OpenAI-compatible"
    ],
    "operationId": "createImage",
    "summary": "Image generation",
    "description": "OpenAI Images for gpt-image-2.6-sunburst and gpt-image-2.6-flare. Billed per image by the longest edge of the delivered image: $0.03 at the 1K tier (up to 1024), $0.05 at the 2K tier (up to 2048), $0.20 at the 4K tier (above 2048). n multiplies the fee and may be 1 to 128.",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/ImageRequest"
       },
       "example": {
        "model": "gpt-image-2.6-flare",
        "prompt": "A lighthouse at dawn, watercolour",
        "size": "1024x1024",
        "n": 1
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "The provider's image response: data[] with url or b64_json.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "additionalProperties": true
        }
       }
      }
     },
     "400": {
      "description": "The body failed validation; the message says which field.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "401": {
      "description": "The key is missing or invalid.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "402": {
      "description": "The balance is empty.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "403": {
      "description": "The model is not sold here, is not on this key's route, or is excluded by the key's model limits.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Rate limited; Retry-After gives the wait in seconds.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "503": {
      "description": "No line can serve the model right now, or the provider is overloaded; retry.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/v1/images/edits": {
   "post": {
    "tags": [
     "OpenAI-compatible"
    ],
    "operationId": "editImage",
    "summary": "Image edit",
    "description": "OpenAI image edits (multipart form) for the GPT Image 2.6 models; priced like generation by the size tier.",
    "requestBody": {
     "required": true,
     "content": {
      "multipart/form-data": {
       "schema": {
        "type": "object",
        "required": [
         "model",
         "image",
         "prompt"
        ],
        "properties": {
         "model": {
          "type": "string",
          "enum": [
           "gpt-image-2.6-sunburst",
           "gpt-image-2.6-flare"
          ]
         },
         "image": {
          "type": "string",
          "format": "binary"
         },
         "prompt": {
          "type": "string"
         },
         "size": {
          "type": "string",
          "example": "1024x1024"
         },
         "n": {
          "type": "integer",
          "minimum": 1,
          "maximum": 128
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "The provider's image response.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "additionalProperties": true
        }
       }
      }
     },
     "400": {
      "description": "The body failed validation; the message says which field.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "401": {
      "description": "The key is missing or invalid.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "402": {
      "description": "The balance is empty.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "403": {
      "description": "The model is not sold here, is not on this key's route, or is excluded by the key's model limits.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Rate limited; Retry-After gives the wait in seconds.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "503": {
      "description": "No line can serve the model right now, or the provider is overloaded; retry.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/v1/videos/generations": {
   "post": {
    "tags": [
     "OpenAI-compatible"
    ],
    "operationId": "createVideo",
    "summary": "Video generation",
    "description": "Submit a grok-imagine-video-1.5 job. Billed per requested second at the moment the provider accepts the job: $0.05 at 480p, $0.10 at 720p, $0.20 at 1080p. A failed job is refunded on the first poll that sees the failure.",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/VideoRequest"
       },
       "example": {
        "model": "grok-imagine-video-1.5",
        "prompt": "A paper boat drifting down a rain gutter",
        "duration": 8,
        "resolution": "720p"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "The accepted job: request_id and model.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "request_id": {
           "type": "string"
          },
          "model": {
           "type": "string"
          }
         },
         "additionalProperties": true
        }
       }
      }
     },
     "400": {
      "description": "The body failed validation; the message says which field.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "401": {
      "description": "The key is missing or invalid.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "402": {
      "description": "The balance is empty.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "403": {
      "description": "The model is not sold here, is not on this key's route, or is excluded by the key's model limits.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Rate limited; Retry-After gives the wait in seconds.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "503": {
      "description": "No line can serve the model right now, or the provider is overloaded; retry.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/v1/videos/{request_id}": {
   "get": {
    "tags": [
     "OpenAI-compatible"
    ],
    "operationId": "getVideo",
    "summary": "Video job status",
    "description": "The provider's status document. pending, queued, processing, running and in_progress mean keep polling; done, failed and expired are final. Any key of the same account can poll.",
    "parameters": [
     {
      "name": "request_id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "The status document.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "additionalProperties": true
        }
       }
      }
     },
     "404": {
      "description": "Unknown id, or another account's job.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "401": {
      "description": "The key is missing or invalid.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/v1/videos/{request_id}/content": {
   "get": {
    "tags": [
     "OpenAI-compatible"
    ],
    "operationId": "getVideoContent",
    "summary": "Video file",
    "description": "The finished video.",
    "parameters": [
     {
      "name": "request_id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "The video bytes.",
      "content": {
       "video/mp4": {
        "schema": {
         "type": "string",
         "format": "binary"
        }
       }
      }
     },
     "404": {
      "description": "Unknown id, another account's job, or not finished.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "401": {
      "description": "The key is missing or invalid.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/v1/systemone": {
   "post": {
    "tags": [
     "TypeSafe"
    ],
    "operationId": "systemOne",
    "summary": "System One (Jev)",
    "description": "TypeSafe's System One: typed questions about a state, answered with probabilities (or, for Box, the edges of a box in an image) instead of text. Model jev-1.14.0; jev-latest and jev-preview are accepted and answered by jev-1.14.0. $0.055 per 1M input tokens, image tokens included, output free; a request the standby line answers, only when the main line fails, bills $0.058. /v1/system_one is accepted as a second spelling. The body must carry model, state and a non-empty questions object; state and questions together are at most 1 MiB, the whole body at most 32 MiB, and assets at most 1,024 images with reference strings of at most 1,024 bytes each and 64 KiB together. Images (PNG or JPEG) are listed once in assets under a reference string and placed by writing that reference in the state, an instruction or a criterion; send them base64-encoded in the JSON body or as file parts of a multipart/form-data body whose first part, named request, holds the JSON. Images and Box questions are an experimental TypeSafe feature: the relay adds the TypeSafe-Danger-Zone-Images header the provider requires, so it is optional here.",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/SystemOneRequest"
       },
       "example": {
        "model": "jev-1.14.0",
        "state": "I have asked three times now. Can I please just talk to a real person?",
        "questions": {
         "is_human_escalation": {
          "type": "noul",
          "instructions": "Is the customer asking for a human agent?"
         }
        }
       }
      },
      "multipart/form-data": {
       "schema": {
        "type": "object",
        "required": [
         "request"
        ],
        "properties": {
         "request": {
          "$ref": "#/components/schemas/SystemOneRequest",
          "description": "The JSON body; must be the first part. Each asset names its file part in part."
         }
        },
        "additionalProperties": {
         "type": "string",
         "format": "binary",
         "description": "One image file part (image/png, image/jpeg or application/octet-stream) per asset, under the name its asset gives in part."
        }
       },
       "encoding": {
        "request": {
         "contentType": "application/json"
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "TypeSafe's answers, unchanged, with usage. usage.input_tokens includes the tokens of every image (about ceil(width/28) x ceil(height/28) x 2 per use).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SystemOneResponse"
        },
        "example": {
         "model": "jev-1.14.0",
         "answers": {
          "is_human_escalation": {
           "type": "noul",
           "noul": 0.99
          }
         },
         "usage": {
          "input_tokens": 43,
          "output_tokens": 20
         }
        }
       }
      }
     },
     "422": {
      "description": "TypeSafe's validation detail, as written. Nothing is charged.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SystemOneProviderError"
        }
       }
      }
     },
     "400": {
      "description": "The body failed the relay's checks (Error), or TypeSafe rejected it: an image it cannot read or outside its size limits, an asset nobody references, a request over the context length (SystemOneProviderError). Nothing is charged.",
      "content": {
       "application/json": {
        "schema": {
         "oneOf": [
          {
           "$ref": "#/components/schemas/Error"
          },
          {
           "$ref": "#/components/schemas/SystemOneProviderError"
          }
         ]
        }
       }
      }
     },
     "413": {
      "description": "The body is over 32 MiB (Error), or TypeSafe found an image or all images together over its size limits (SystemOneProviderError). Nothing is charged.",
      "content": {
       "application/json": {
        "schema": {
         "oneOf": [
          {
           "$ref": "#/components/schemas/Error"
          },
          {
           "$ref": "#/components/schemas/SystemOneProviderError"
          }
         ]
        }
       }
      }
     },
     "401": {
      "description": "The key is missing or invalid.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "402": {
      "description": "The balance is empty.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "403": {
      "description": "The model is not sold here, is not on this key's route, or is excluded by the key's model limits.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Rate limited; Retry-After gives the wait in seconds.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "503": {
      "description": "No line can serve the model right now, or the provider is overloaded; retry.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    },
    "parameters": [
     {
      "name": "TypeSafe-Danger-Zone-Images",
      "in": "header",
      "required": false,
      "description": "TypeSafe's opt-in for images and Box questions. Optional on TopxAI: the relay sends it whenever the request carries assets or a Box question.",
      "schema": {
       "type": "string",
       "enum": [
        "true"
       ]
      }
     }
    ]
   }
  },
  "/v1/models": {
   "get": {
    "tags": [
     "OpenAI-compatible"
    ],
    "operationId": "listModels",
    "summary": "Models this key can call",
    "description": "The OpenAI model list, filtered to the models the key's route serves.",
    "responses": {
     "200": {
      "description": "The list.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "object": {
           "type": "string",
           "const": "list"
          },
          "data": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "id": {
              "type": "string"
             },
             "object": {
              "type": "string"
             },
             "owned_by": {
              "type": "string"
             }
            }
           }
          }
         }
        }
       }
      }
     },
     "401": {
      "description": "The key is missing or invalid.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/api/pricing": {
   "get": {
    "tags": [
     "Public"
    ],
    "operationId": "getPricing",
    "security": [],
    "summary": "The price table",
    "description": "Every model with its route prices in USD (per 1M tokens, per image by size, per second by resolution), the routes it is enabled on, the endpoints that serve it, the provider's list price for comparison and the route an Auto-route key would pick. The same data as https://api.topxai.xyz/pricing.",
    "responses": {
     "200": {
      "description": "The catalogue.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "success": {
           "type": "boolean"
          },
          "data": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/PricingModel"
           }
          }
         }
        }
       }
      }
     },
     "429": {
      "description": "Rate limited; retry after the Retry-After seconds.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  }
 },
 "components": {
  "securitySchemes": {
   "bearerAuth": {
    "type": "http",
    "scheme": "bearer",
    "description": "A TopxAI API key (sk-...) as Authorization: Bearer <key>. Keys are created at https://api.topxai.xyz/keys."
   },
   "anthropicKey": {
    "type": "apiKey",
    "in": "header",
    "name": "x-api-key",
    "description": "The same TopxAI key, the way the Anthropic SDK sends it."
   }
  },
  "schemas": {
   "Error": {
    "type": "object",
    "properties": {
     "error": {
      "type": "object",
      "properties": {
       "message": {
        "type": "string",
        "description": "Ends with a request id to quote to support@topxai.xyz."
       },
       "type": {
        "type": "string"
       },
       "code": {
        "type": [
         "string",
         "integer",
         "null"
        ]
       }
      }
     }
    }
   },
   "TextModel": {
    "type": "string",
    "description": "A catalogue text model.",
    "enum": [
     "claude-fable-5-2",
     "claude-sonnet-5-5",
     "claude-opus-5-5",
     "gpt-6-astra",
     "gpt-6.1-sol",
     "gpt-6.1-terra",
     "grok-4.7",
     "GLM-5.3-Abliterated",
     "GLM-5.3-Flash-Abliterated",
     "kimi-k3.1-pro",
     "deepseek-flash-Abliterated",
     "deepseek-flash-fast"
    ]
   },
   "ChatMessage": {
    "type": "object",
    "required": [
     "role",
     "content"
    ],
    "properties": {
     "role": {
      "type": "string",
      "enum": [
       "system",
       "developer",
       "user",
       "assistant",
       "tool"
      ]
     },
     "content": {
      "oneOf": [
       {
        "type": "string"
       },
       {
        "type": "array",
        "items": {
         "type": "object",
         "additionalProperties": true
        }
       }
      ],
      "description": "Text, or content parts (text, image_url) as the provider defines them."
     },
     "name": {
      "type": "string"
     },
     "tool_calls": {
      "type": "array",
      "items": {
       "type": "object",
       "additionalProperties": true
      }
     },
     "tool_call_id": {
      "type": "string"
     }
    },
    "additionalProperties": true
   },
   "ChatCompletionRequest": {
    "type": "object",
    "required": [
     "model",
     "messages"
    ],
    "properties": {
     "model": {
      "$ref": "#/components/schemas/TextModel"
     },
     "messages": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ChatMessage"
      }
     },
     "stream": {
      "type": "boolean",
      "default": false
     },
     "max_tokens": {
      "type": "integer"
     },
     "max_completion_tokens": {
      "type": "integer"
     },
     "temperature": {
      "type": "number"
     },
     "top_p": {
      "type": "number"
     },
     "tools": {
      "type": "array",
      "items": {
       "type": "object",
       "additionalProperties": true
      }
     },
     "tool_choice": {},
     "response_format": {
      "type": "object",
      "additionalProperties": true
     },
     "reasoning_effort": {
      "type": "string"
     },
     "stop": {},
     "user": {
      "type": "string"
     }
    },
    "additionalProperties": true,
    "description": "OpenAI's Chat Completions body; fields not listed pass through to the provider."
   },
   "ChatCompletionResponse": {
    "type": "object",
    "properties": {
     "id": {
      "type": "string"
     },
     "object": {
      "type": "string"
     },
     "created": {
      "type": "integer"
     },
     "model": {
      "type": "string"
     },
     "choices": {
      "type": "array",
      "items": {
       "type": "object",
       "additionalProperties": true
      }
     },
     "usage": {
      "$ref": "#/components/schemas/Usage"
     }
    },
    "additionalProperties": true
   },
   "Usage": {
    "type": "object",
    "properties": {
     "prompt_tokens": {
      "type": "integer"
     },
     "completion_tokens": {
      "type": "integer"
     },
     "total_tokens": {
      "type": "integer"
     },
     "prompt_tokens_details": {
      "type": "object",
      "properties": {
       "cached_tokens": {
        "type": "integer"
       }
      },
      "additionalProperties": true
     }
    },
    "additionalProperties": true
   },
   "ResponsesRequest": {
    "type": "object",
    "required": [
     "model",
     "input"
    ],
    "properties": {
     "model": {
      "type": "string",
      "enum": [
       "gpt-6-astra",
       "gpt-6.1-sol",
       "gpt-6.1-terra",
       "grok-4.7",
       "GLM-5.3-Flash-Abliterated",
       "kimi-k3.1-pro",
       "deepseek-flash-Abliterated",
       "deepseek-flash-fast"
      ]
     },
     "input": {
      "oneOf": [
       {
        "type": "string"
       },
       {
        "type": "array",
        "items": {
         "type": "object",
         "additionalProperties": true
        }
       }
      ]
     },
     "instructions": {
      "type": "string",
      "description": "The system prompt. When it is missing or blank, input has no system or developer item and no stored prompt is named, gpt-6-astra, gpt-6.1-sol and gpt-6.1-terra are sent \"You are a helpful assistant.\" so the provider does not add its own longer prompt; the answer still echoes the value the request sent."
     },
     "stream": {
      "type": "boolean"
     },
     "tools": {
      "type": "array",
      "items": {
       "type": "object",
       "additionalProperties": true
      }
     },
     "reasoning": {
      "type": "object",
      "additionalProperties": true
     },
     "max_output_tokens": {
      "type": "integer"
     }
    },
    "additionalProperties": true
   },
   "MessagesRequest": {
    "type": "object",
    "required": [
     "model",
     "messages"
    ],
    "properties": {
     "model": {
      "$ref": "#/components/schemas/TextModel"
     },
     "max_tokens": {
      "type": "integer",
      "description": "Without it, Claude and DeepSeek get the model's output limit and the other models are sent no cap."
     },
     "messages": {
      "type": "array",
      "items": {
       "type": "object",
       "required": [
        "role",
        "content"
       ],
       "properties": {
        "role": {
         "type": "string",
         "enum": [
          "user",
          "assistant"
         ]
        },
        "content": {}
       },
       "additionalProperties": true
      }
     },
     "system": {
      "description": "A system prompt as a string or content blocks. TopxAI adds none of its own, except that a gpt-6.1-sol or gpt-6.1-terra request without one is sent the instructions \"You are a helpful assistant.\" so the provider does not add its own longer prompt.",
      "oneOf": [
       {
        "type": "string"
       },
       {
        "type": "array",
        "items": {
         "type": "object",
         "additionalProperties": true
        }
       }
      ]
     },
     "stream": {
      "type": "boolean"
     },
     "tools": {
      "type": "array",
      "items": {
       "type": "object",
       "additionalProperties": true
      }
     },
     "temperature": {
      "type": "number"
     },
     "thinking": {
      "type": "object",
      "additionalProperties": true
     }
    },
    "additionalProperties": true
   },
   "ImageRequest": {
    "type": "object",
    "required": [
     "model",
     "prompt"
    ],
    "properties": {
     "model": {
      "type": "string",
      "enum": [
       "gpt-image-2.6-sunburst",
       "gpt-image-2.6-flare"
      ]
     },
     "prompt": {
      "type": "string"
     },
     "size": {
      "type": "string",
      "description": "WIDTHxHEIGHT with a plain x; omitted or auto is pinned to 1024x1024. The longest edge picks the 1K, 2K or 4K tier. The supplier can deliver another size; the delivered size is what is billed.",
      "example": "1024x1024"
     },
     "n": {
      "type": "integer",
      "minimum": 1,
      "maximum": 128,
      "default": 1
     },
     "quality": {
      "type": "string",
      "description": "Validated, does not change the fee."
     },
     "stream": {
      "type": "boolean"
     }
    },
    "additionalProperties": true
   },
   "VideoRequest": {
    "type": "object",
    "required": [
     "model",
     "prompt"
    ],
    "properties": {
     "model": {
      "type": "string",
      "const": "grok-imagine-video-1.5"
     },
     "prompt": {
      "type": "string"
     },
     "duration": {
      "type": "integer",
      "minimum": 1,
      "maximum": 15,
      "default": 8,
      "description": "Seconds of video; the fee is duration times the per-second price."
     },
     "resolution": {
      "type": "string",
      "enum": [
       "480p",
       "720p",
       "1080p"
      ],
      "default": "480p"
     },
     "image": {
      "description": "Image-to-video input, as xAI defines it."
     },
     "reference_images": {
      "type": "array",
      "items": {}
     },
     "aspect_ratio": {
      "type": "string"
     },
     "generate_audio": {
      "type": "boolean"
     }
    },
    "additionalProperties": true
   },
   "SystemOneQuestion": {
    "type": "object",
    "required": [
     "type",
     "instructions"
    ],
    "properties": {
     "type": {
      "type": "string",
      "enum": [
       "noul",
       "choice",
       "score",
       "box"
      ],
      "description": "noul (probability of yes), choice (one option of criteria, with a probability per option), score (a value across ordered criteria levels) or box (where the target is in an image: top, bottom, left and right as fractions of the image)."
     },
     "instructions": {
      "description": "The question, or for box what to find and in which image. A string, or an object or array that holds the question and data it refers to; may contain image references.",
      "oneOf": [
       {
        "type": "string"
       },
       {
        "type": "object"
       },
       {
        "type": "array"
       }
      ]
     },
     "criteria": {
      "description": "noul: optional {true, false} definitions. choice: object of option name to description (or null), at most 255 options. score: ordered array of 2 to 10 level descriptions. box: none. Descriptions may contain image references.",
      "oneOf": [
       {
        "type": "object"
       },
       {
        "type": "array"
       }
      ]
     }
    },
    "additionalProperties": true
   },
   "SystemOneRequest": {
    "type": "object",
    "required": [
     "model",
     "state",
     "questions"
    ],
    "properties": {
     "model": {
      "type": "string",
      "enum": [
       "jev-1.14.0",
       "jev-latest",
       "jev-preview"
      ]
     },
     "state": {
      "description": "What the questions are about: a string, or structured JSON such as a record or a chat log; image references may appear in it. Default limits: 64k tokens per request and 32k per question, the state included.",
      "oneOf": [
       {
        "type": "string"
       },
       {
        "type": "object"
       },
       {
        "type": "array"
       }
      ]
     },
     "questions": {
      "type": "object",
      "minProperties": 1,
      "additionalProperties": {
       "$ref": "#/components/schemas/SystemOneQuestion"
      }
     },
     "assets": {
      "type": "object",
      "description": "Images keyed by reference string. Every reference must appear in the state, an instruction or a criterion; each appearance adds the image again.",
      "additionalProperties": {
       "$ref": "#/components/schemas/SystemOneAsset"
      }
     }
    },
    "additionalProperties": true
   },
   "SystemOneAsset": {
    "type": "object",
    "properties": {
     "type": {
      "type": "string",
      "enum": [
       "image"
      ]
     },
     "format": {
      "type": "string",
      "enum": [
       "png",
       "jpg",
       "jpeg"
      ],
      "description": "Required with data_base64."
     },
     "data_base64": {
      "type": "string",
      "description": "The image file, standard base64 with padding, no data: prefix. PNG or JPEG, 280 to 1568 pixels on each side as measured on 2026-10-16 (TypeSafe documents 256)."
     },
     "part": {
      "type": "string",
      "description": "In a multipart body, the name of the file part holding the image."
     }
    },
    "additionalProperties": false
   },
   "SystemOneResponse": {
    "type": "object",
    "properties": {
     "model": {
      "type": "string"
     },
     "answers": {
      "type": "object",
      "additionalProperties": {
       "type": "object",
       "additionalProperties": true
      }
     },
     "usage": {
      "type": "object",
      "properties": {
       "input_tokens": {
        "type": "integer"
       },
       "output_tokens": {
        "type": "integer"
       }
      }
     }
    },
    "additionalProperties": true
   },
   "SystemOneProviderError": {
    "type": "object",
    "description": "TypeSafe's own error body, passed through as written (the channel key and upstream hosts removed).",
    "properties": {
     "detail": {
      "description": "An object with error_type and message, or a list of field errors.",
      "oneOf": [
       {
        "type": "object"
       },
       {
        "type": "array"
       }
      ]
     }
    },
    "additionalProperties": true
   },
   "RoutePrice": {
    "type": "object",
    "properties": {
     "unit": {
      "type": "string",
      "enum": [
       "per_million_tokens",
       "per_image",
       "per_second",
       "per_request"
      ]
     },
     "input": {
      "type": "number"
     },
     "output": {
      "type": "number"
     },
     "cache_read": {
      "type": "number"
     },
     "cache_write": {
      "type": "number"
     },
     "cache_write_1h": {
      "type": "number"
     },
     "long_context": {
      "type": "object",
      "properties": {
       "min_input_tokens": {
        "type": "integer"
       },
       "input": {
        "type": "number"
       },
       "output": {
        "type": "number"
       }
      },
      "additionalProperties": true
     },
     "backup": {
      "type": "object",
      "description": "The tariff, USD per 1M tokens, billed for a request the backup deployment answers, which happens only when the main deployment fails before answering. Every lane of such a request bills at these rates; an omitted cache or media lane falls back to this tariff's input (or output) rate. Present only on models that keep a backup deployment.",
      "required": [
       "input",
       "output"
      ],
      "properties": {
       "input": {
        "type": "number"
       },
       "output": {
        "type": "number"
       },
       "cache_read": {
        "type": "number"
       },
       "cache_write": {
        "type": "number"
       },
       "cache_write_1h": {
        "type": "number"
       },
       "image_input": {
        "type": "number"
       },
       "image_output": {
        "type": "number"
       },
       "audio_input": {
        "type": "number"
       },
       "audio_output": {
        "type": "number"
       }
      },
      "additionalProperties": true
     },
     "sizes": {
      "type": "object",
      "additionalProperties": {
       "type": "number"
      }
     },
     "resolutions": {
      "type": "object",
      "additionalProperties": {
       "type": "number"
      }
     },
     "unit_price": {
      "type": "number"
     }
    },
    "additionalProperties": true
   },
   "PricingModel": {
    "type": "object",
    "properties": {
     "model_name": {
      "type": "string"
     },
     "description": {
      "type": "string"
     },
     "notice": {
      "type": "string"
     },
     "enable_groups": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "supported_endpoint_types": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "route_prices": {
      "type": "object",
      "additionalProperties": {
       "$ref": "#/components/schemas/RoutePrice"
      }
     },
     "reference_price": {
      "$ref": "#/components/schemas/RoutePrice"
     },
     "reference_price_source": {
      "type": "object",
      "properties": {
       "kind": {
        "type": "string"
       },
       "name": {
        "type": "string"
       },
       "url": {
        "type": "string"
       },
       "verified_at": {
        "type": "string"
       },
       "model": {
        "type": "string"
       }
      }
     },
     "auto_route": {
      "type": "string"
     },
     "context_window": {
      "type": "integer",
      "description": "Input context window in tokens; omitted when unknown or not applicable."
     },
     "max_output": {
      "type": "integer",
      "description": "Maximum output tokens; omitted when unknown or not applicable."
     }
    },
    "additionalProperties": true
   }
  }
 }
}