openapi: 3.1.0
info:
  title: BlazeInfer Inference API
  version: "1.0"
  description: |
    BlazeInfer is an OpenAI-compatible inference API that serves self-hosted
    open-weight models on E2E Networks GPUs.

    This specification describes the Chat Completions and Models endpoints.

    Authentication: send your key as `Authorization: Bearer blz_...`. The word
    `Bearer` needs a capital B. The Anthropic-style `x-api-key` header is not
    accepted.

    Errors are JSON in the OpenAI shape. A `429` from a credit rule can also be
    plain text. Inference responses carry an `X-Request-Id` header; a
    client-sent `X-Request-Id` is echoed back.

    Guides and the full model catalog: https://blazeinfer.ai/docs
servers:
  - url: https://blaze.e2enetworks.net/v1
    description: BlazeInfer production API
security:
  - bearerAuth: []
tags:
  - name: Chat
  - name: Models
paths:
  /chat/completions:
    post:
      tags: [Chat]
      summary: Create a chat completion
      description: |
        Sends a conversation and returns one assistant message. Supports
        streaming (`stream: true`). The `finish_reason` arrives in its own chunk
        with an empty `delta`. BlazeInfer adds a final usage chunk, with an empty
        `choices` list, when the request has no `stream_options`; if you send
        `stream_options`, set `include_usage: true` yourself. Every stream ends
        with `data: [DONE]`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ChatCompletionRequest"
      responses:
        "200":
          description: The generated chat completion, or an SSE stream when `stream` is true.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChatCompletion"
            text/event-stream:
              schema:
                type: string
        "400":
          $ref: "#/components/responses/ClientError"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "503":
          $ref: "#/components/responses/Unavailable"
  /models:
    get:
      tags: [Models]
      summary: List models
      description: |
        Lists the models available to the key, in the OpenAI list shape, sorted
        by ID. Only `id`, `object`, `created` and `owned_by` are returned, and
        canonical IDs only (aliases are not listed). A listed model can still be
        unavailable; calls to it return `404` or `503`. Use the docs catalog for
        context lengths and capabilities.
      responses:
        "200":
          description: A list of models.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ModelList"
        "401":
          $ref: "#/components/responses/Unauthorized"
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: "BlazeInfer API key, for example `blz_...`. Send it as `Authorization: Bearer <key>`."
  headers:
    X-Request-Id:
      description: |
        The request ID. Quote it in support requests. If you send your own
        `X-Request-Id`, it is echoed back.
      schema:
        type: string
  responses:
    Unauthorized:
      description: |
        The key is missing, invalid, expired, revoked or blocked. A key sent only
        in `x-api-key`, a lowercase `bearer`, or an empty Bearer counts as
        missing (`api key required`).
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          examples:
            missing:
              summary: "No key, or not sent as `Authorization: Bearer`"
              value:
                error:
                  message: api key required
                  type: invalid_request_error
            invalid:
              summary: Unknown, expired, revoked or blocked key
              value:
                error:
                  message: invalid api key
                  type: invalid_request_error
    ClientError:
      description: |
        The model rejected the request, for example bad JSON, a missing
        `messages` field, a prompt that is too long, or tools sent to a model
        that does not accept them. The original message is replaced with a
        generic one.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error:
              message: The upstream provider rejected the request.
              type: invalid_request
              code: 400
    NotFound:
      description: |
        The model ID is unknown, or the model is not available.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error:
              message: The requested model is not currently available.
              type: not_found
              code: 404
    TooManyRequests:
      description: |
        No credit left, or a temporary overload. The body can be JSON or plain
        text. Check your credit before you retry.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
        text/plain:
          schema:
            type: string
    Unavailable:
      description: |
        The model is temporarily unavailable. Retry with backoff, or use another
        model. Also returned when the key cannot be checked.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error:
              message: Upstream provider error.
              type: server_error
              code: 503
  schemas:
    Error:
      type: object
      required: [error]
      properties:
        error:
          type: object
          required: [message, type]
          properties:
            message:
              type: string
            type:
              type: string
            code:
              type: integer
              description: The HTTP status. Present on model errors only.
    ChatMessage:
      type: object
      required: [role]
      properties:
        role:
          type: string
          enum: [system, user, assistant, tool]
        content:
          description: A string, or an array of content parts (for example text and image parts).
        reasoning_content:
          type: [string, "null"]
          description: Reasoning text on some reasoning models (response only).
        reasoning:
          type: [string, "null"]
          description: Reasoning text on other reasoning models (response only).
        name:
          type: string
        tool_call_id:
          type: string
        tool_calls:
          type: array
          items:
            type: object
      additionalProperties: true
    ChatCompletionRequest:
      type: object
      required: [model, messages]
      properties:
        model:
          type: string
          description: A full model ID or an alias. See the docs model catalog.
          example: google/gemma-4-31b-it
        messages:
          type: array
          items:
            $ref: "#/components/schemas/ChatMessage"
        max_tokens:
          type: integer
          description: |
            Cap on the reply. On reasoning models it includes the reasoning
            tokens, so leave room for them.
        temperature:
          type: number
        top_p:
          type: number
        n:
          type: integer
          description: Number of choices to return.
        stream:
          type: boolean
          default: false
        stream_options:
          type: object
          description: |
            Leave it out to get a final usage chunk. If you send it, set
            `include_usage: true`.
          properties:
            include_usage:
              type: boolean
        stop:
          description: |
            Stop sequences. On reasoning models a stop sequence can also match
            inside the reasoning, which leaves `content` empty.
          oneOf:
            - type: string
            - type: array
              items:
                type: string
        seed:
          type: integer
          description: Best-effort determinism.
        logprobs:
          type: boolean
          description: Return token log probabilities.
        tools:
          type: array
          items:
            type: object
        tool_choice:
          description: "`auto`, `none`, `required`, or an object that names one function."
          oneOf:
            - type: string
              enum: [auto, none, required]
            - type: object
        response_format:
          type: object
          description: '`{"type": "json_object"}` or `{"type": "json_schema", "json_schema": {...}}`.'
      additionalProperties: true
    ChatCompletion:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          example: chat.completion
        created:
          type: integer
        model:
          type: string
        choices:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
              message:
                $ref: "#/components/schemas/ChatMessage"
              finish_reason:
                type: [string, "null"]
        usage:
          $ref: "#/components/schemas/Usage"
    Usage:
      type: object
      properties:
        prompt_tokens:
          type: integer
        completion_tokens:
          type: integer
        total_tokens:
          type: integer
        prompt_tokens_details:
          type: [object, "null"]
          description: Can be `null` on some models.
          properties:
            cached_tokens:
              type: [integer, "null"]
    ModelList:
      type: object
      properties:
        object:
          type: string
          example: list
        data:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              object:
                type: string
                example: model
              created:
                type: integer
              owned_by:
                type: string
