openapi: 3.0.1
info:
  title: Nscale Serverless Inference Chat Completions API
  description: OpenAI-compatible serverless inference API for Nscale. Provides chat completions, text completions, embeddings, image generation, and model discovery against open models (Llama, Qwen, DeepSeek, GPT OSS, Mistral, Flux) served on Nscale GPU infrastructure. Authenticate with a Bearer API key issued from the Nscale console.
  termsOfService: https://www.nscale.com/legal/terms-of-service
  contact:
    name: Nscale Support
    url: https://docs.nscale.com
  version: '1.0'
servers:
- url: https://inference.api.nscale.com/v1
  description: Serverless Inference API
security:
- bearerAuth: []
tags:
- name: Completions
  description: OpenAI-compatible legacy text completions.
paths:
  /completions:
    post:
      operationId: createCompletion
      tags:
      - Completions
      summary: Create a completion
      description: Generates a completion response for the provided model and prompt.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompletionRequest'
      responses:
        '200':
          description: A text completion.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompletionResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    CompletionResponse:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          example: text_completion
        created:
          type: integer
        model:
          type: string
        choices:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
              text:
                type: string
              finish_reason:
                type: string
        usage:
          $ref: '#/components/schemas/Usage'
    Usage:
      type: object
      properties:
        prompt_tokens:
          type: integer
        completion_tokens:
          type: integer
        total_tokens:
          type: integer
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            type:
              type: string
            code:
              type: string
    CompletionRequest:
      type: object
      required:
      - model
      - prompt
      properties:
        model:
          type: string
        prompt:
          oneOf:
          - type: string
          - type: array
            items:
              type: string
        max_tokens:
          type: integer
        temperature:
          type: number
          format: float
        top_p:
          type: number
          format: float
        stream:
          type: boolean
          default: false
        stop:
          oneOf:
          - type: string
          - type: array
            items:
              type: string
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Too many requests; back off and retry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Nscale API key issued from the console, sent as `Authorization: Bearer $NSCALE_API_KEY`.'