topxea-com Open AI Compatible API

openapi: 3.2.0
info:
  title: TopxAI Open AI Compatible API
  version: '2026-10-25'
  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/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 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://ai.topxea.com/v1. Base URL for the Anthropic SDK: https://ai.topxea.com. Prompts, completions and files are relayed in memory and never stored. Prices: https://ai.topxea.com/pricing and https://ai.topxea.com/api/pricing.'
  termsOfService: https://ai.topxea.com/user-agreement
  contact:
    name: TopxAI support
    email: support@topxea.com
    url: https://ai.topxea.com/docs
  x-logo:
    url: https://ai.topxea.com/favicon.svg
  license:
    name: Terms of use
    url: https://ai.topxea.com/user-agreement
servers:
- url: https://ai.topxea.com
  description: Production
security:
- bearerAuth: []
tags:
- name: OpenAI-compatible
  description: 'Chat Completions, Responses, Images, Video and the model list, with Authorization: Bearer .'
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, grok-4.7, kimi-k3.1-pro and deepseek-flash-Abliterated. Codex CLI uses this endpoint; persistent conversation workflows on kimi-k3.1-pro and deepseek-flash-Abliterated 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/images/generations:
    post:
      tags:
      - OpenAI-compatible
      operationId: createImage
      summary: Image generation
      description: 'OpenAI Images for gpt-image-2.5-sunburst and gpt-image-2.5-flare. Billed per image: $0.03 at the 1K tier, $0.05 at the 2K tier, chosen from the pixel count of size (WIDTHxHEIGHT). 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.5-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.5 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.5-sunburst
                  - gpt-image-2.5-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/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'
components:
  schemas:
    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
    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
    TextModel:
      type: string
      description: A catalogue text model.
      enum:
      - claude-fable-5-1
      - claude-sonnet-5-5
      - claude-opus-5-5
      - gpt-6-astra
      - gpt-6.1-sol
      - grok-4.7
      - GLM-5.3-Abliterated
      - kimi-k3.1-pro
      - deepseek-flash-Abliterated
    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
    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.
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              description: Ends with a request id to quote to support@topxea.com.
            type:
              type: string
            code:
              type:
              - string
              - integer
              - 'null'
    ResponsesRequest:
      type: object
      required:
      - model
      - input
      properties:
        model:
          type: string
          enum:
          - gpt-6-astra
          - gpt-6.1-sol
          - grok-4.7
          - kimi-k3.1-pro
          - deepseek-flash-Abliterated
        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 and gpt-6.1-sol 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
    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
    ImageRequest:
      type: object
      required:
      - model
      - prompt
      properties:
        model:
          type: string
          enum:
          - gpt-image-2.5-sunburst
          - gpt-image-2.5-flare
        prompt:
          type: string
        size:
          type: string
          description: WIDTHxHEIGHT with a plain x; omitted or auto is pinned to 1024x1024. The pixel count picks the 1K or 2K tier.
          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
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'A TopxAI API key (sk-...) as Authorization: Bearer <key>. Keys are created at https://ai.topxea.com/keys.'
    anthropicKey:
      type: apiKey
      in: header
      name: x-api-key
      description: The same TopxAI key, the way the Anthropic SDK sends it.
externalDocs:
  description: Documentation
  url: https://ai.topxea.com/docs