> ## Documentation Index
> Fetch the complete documentation index at: https://docs.primalabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a chat completion

> Given a list of messages, returns a model-generated reply. Set `stream: true`
to receive server-sent events. Fully OpenAI-compatible — the OpenAI Python and
Node SDKs work unmodified against this endpoint.




## OpenAPI

````yaml /api-reference/inference/openapi.yaml post /chat/completions
openapi: 3.1.0
info:
  title: PrimaLabs Inference API
  version: 1.0.0
  description: >
    Serverless LLM inference on PrimaLabs. The API is OpenAI-compatible: point
    any

    OpenAI SDK at the base URL below and pass a PrimaLabs API key as the bearer

    token. Anthropic (`/messages`) and OpenAI Responses (`/responses`) formats
    are

    also accepted as passthroughs.


    This is a **curated** spec covering the endpoints we serve; it is maintained
    by

    hand. The current model list is published at

    https://docs.primalabs.ai/inference/models.
servers:
  - url: https://api.primalabs.ai/v1
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Chat
    description: OpenAI-compatible chat completions — the primary endpoint.
  - name: Completions
    description: Legacy text completions.
  - name: Models
    description: The models your key can call, with context, pricing and capabilities.
  - name: Account
    description: Your account's balance.
  - name: Passthrough
    description: Anthropic and OpenAI Responses formats, forwarded as-is.
paths:
  /chat/completions:
    post:
      tags:
        - Chat
      summary: Create a chat completion
      description: >
        Given a list of messages, returns a model-generated reply. Set `stream:
        true`

        to receive server-sent events. Fully OpenAI-compatible — the OpenAI
        Python and

        Node SDKs work unmodified against this endpoint.
      operationId: createChatCompletion
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
            examples:
              basic:
                summary: A basic request
                value:
                  model: primalabs-ai/DeepSeek-V4.1-Flash-1017
                  messages:
                    - role: user
                      content: Hello
              thinking_off:
                summary: Thinking off
                value:
                  model: primalabs-ai/DeepSeek-V4.1-Flash-1017
                  messages:
                    - role: user
                      content: What is 17*23?
                  reasoning_effort: none
              tools:
                summary: Tool calling
                value:
                  model: primalabs-ai/DeepSeek-V4.1-Flash-1017
                  messages:
                    - role: user
                      content: What's the weather in Paris?
                  tools:
                    - type: function
                      function:
                        name: get_weather
                        description: Current weather for a city.
                        parameters:
                          type: object
                          properties:
                            city:
                              type: string
                          required:
                            - city
                  tool_choice: auto
              image:
                summary: Image input
                value:
                  model: primalabs-ai/Nemotron-3.5-Super-VL-NVFP4
                  messages:
                    - role: user
                      content:
                        - type: text
                          text: What color is this image?
                        - type: image_url
                          image_url:
                            url: >-
                              data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAIAAACQkWg2AAAAFklEQVR42mP4z8BAEmIY1TCqYfhqAACQ+f8B8u7oVwAAAABJRU5ErkJggg==
      responses:
        '200':
          description: A chat completion, or an SSE stream when `stream` is true.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletion'
            text/event-stream:
              schema:
                type: string
                description: >
                  Server-sent events, one `data: {...}` line per
                  `chat.completion.chunk`,

                  ending with `data: [DONE]`. Each chunk carries a `delta` in
                  place of

                  `message`.
              example: >
                data:
                {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1760460000,"model":"primalabs-ai/DeepSeek-V4.1-Flash-1017","choices":[{"index":0,"delta":{"role":"assistant","content":"Hello"},"finish_reason":null}]}


                data:
                {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1760460000,"model":"primalabs-ai/DeepSeek-V4.1-Flash-1017","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}


                data: [DONE]
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/BalanceExhausted'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/Unavailable'
components:
  schemas:
    ChatCompletionRequest:
      type: object
      required:
        - model
        - messages
      properties:
        model:
          type: string
          description: A model ID from the published catalog.
          example: primalabs-ai/DeepSeek-V4.1-Flash-1017
        messages:
          type: array
          description: The conversation so far.
          items:
            $ref: '#/components/schemas/ChatMessage'
        stream:
          type: boolean
          default: false
          description: Stream partial deltas as server-sent events.
        max_tokens:
          type: integer
          description: >
            Maximum tokens to generate, reasoning tokens included. A model's
            limit is

            `max_output_tokens` in [List
            models](/api-reference/inference/models/list-models).
        reasoning_effort:
          type: string
          enum:
            - none
            - minimal
            - low
            - medium
            - high
            - xhigh
            - max
          description: >
            How much the model thinks before it answers; `none` turns thinking
            off.

            Thinking is on by default. Each model accepts only some of these
            values and

            returns `400` for the rest: see `reasoning_effort_accepted` in

            [List models](/api-reference/inference/models/list-models) and

            [Effort levels](/inference/models#effort-levels).
        tools:
          type: array
          description: >-
            Functions the model may call. Supported on every model in the
            catalog.
          items:
            $ref: '#/components/schemas/Tool'
        tool_choice:
          description: >
            `auto` (the default when `tools` is set), `none`, `required`, or

            `{"type": "function", "function": {"name": "..."}}` to force one
            function.
          oneOf:
            - type: string
              enum:
                - auto
                - none
                - required
            - type: object
              required:
                - type
                - function
              properties:
                type:
                  type: string
                  enum:
                    - function
                function:
                  type: object
                  required:
                    - name
                  properties:
                    name:
                      type: string
        response_format:
          type: object
          description: >
            `{"type": "json_schema", "json_schema": {"name": "...", "schema":
            {...}}}` returns

            JSON that matches the schema, on models where
            `supports_response_schema` is

            `true` in [List
            models](/api-reference/inference/models/list-models).
          properties:
            type:
              type: string
              enum:
                - text
                - json_schema
            json_schema:
              type: object
              properties:
                name:
                  type: string
                schema:
                  type: object
                strict:
                  type: boolean
        cache_salt:
          type: string
          description: >
            Keeps this request's cached prompt prefixes apart from requests with
            a

            different salt, within your account. See

            [Prompt caching](/inference/prompt-caching).
          example: customer-1234
        temperature:
          type: number
          minimum: 0
          maximum: 2
          description: |
            Some models run fixed values or accept only a few: see
            [Sampling parameters](/inference/models#sampling-parameters).
        top_p:
          type: number
          description: |
            Some models run a fixed value: see
            [Sampling parameters](/inference/models#sampling-parameters).
        stop:
          description: |
            Sequences where the model stops. With thinking on, a stop sequence
            can end some models' answers empty: see
            [Known limitations](/inference/models#known-limitations).
          oneOf:
            - type: string
            - type: array
              items:
                type: string
        frequency_penalty:
          type: number
          default: 0
        presence_penalty:
          type: number
          default: 0
      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/AssistantMessage'
              finish_reason:
                type: string
                example: stop
        usage:
          $ref: '#/components/schemas/Usage'
    ChatMessage:
      type: object
      required:
        - role
      properties:
        role:
          type: string
          enum:
            - system
            - user
            - assistant
            - tool
        content:
          description: >
            A string, or a list of content parts to send images or audio (see

            [Images, audio and video](/inference/media-input)). May be null on
            an

            assistant message that only calls tools.
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/ContentPart'
            - type: 'null'
        tool_calls:
          type: array
          description: On an assistant message, the functions it called.
          items:
            $ref: '#/components/schemas/ToolCall'
        tool_call_id:
          type: string
          description: On a `tool` message, the `id` of the call this is the result of.
      additionalProperties: true
    Tool:
      type: object
      required:
        - type
        - function
      properties:
        type:
          type: string
          enum:
            - function
        function:
          type: object
          required:
            - name
          properties:
            name:
              type: string
            description:
              type: string
            parameters:
              type: object
              description: A JSON Schema for the function's arguments.
    AssistantMessage:
      type: object
      properties:
        role:
          type: string
          enum:
            - assistant
        content:
          type:
            - string
            - 'null'
          description: The answer. Null when the model only called tools.
        reasoning_content:
          type:
            - string
            - 'null'
          description: The model's thinking, when thinking is on.
        tool_calls:
          type: array
          items:
            $ref: '#/components/schemas/ToolCall'
    Usage:
      type: object
      properties:
        prompt_tokens:
          type: integer
        completion_tokens:
          type: integer
          description: Output tokens, reasoning tokens included.
        total_tokens:
          type: integer
        completion_tokens_details:
          type: object
          properties:
            reasoning_tokens:
              type: integer
              description: >
                The part of `completion_tokens` the model spent thinking. Billed
                at the

                output rate like the rest of `completion_tokens`.
        prompt_tokens_details:
          type: object
          properties:
            cached_tokens:
              type: integer
              description: >
                Input tokens served from the prompt cache, billed at the cached
                rate. See

                [Prompt caching](/inference/prompt-caching).
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            type:
              type: string
            param:
              type:
                - string
                - 'null'
            code:
              type: string
    ContentPart:
      oneOf:
        - type: object
          title: Text
          required:
            - type
            - text
          properties:
            type:
              type: string
              enum:
                - text
            text:
              type: string
        - type: object
          title: Image
          required:
            - type
            - image_url
          properties:
            type:
              type: string
              enum:
                - image_url
            image_url:
              type: object
              required:
                - url
              properties:
                url:
                  type: string
                  description: A public `https` URL, or a `data:image/...;base64,` URL.
        - type: object
          title: Audio
          required:
            - type
            - input_audio
          properties:
            type:
              type: string
              enum:
                - input_audio
            input_audio:
              type: object
              required:
                - data
                - format
              properties:
                data:
                  type: string
                  description: The audio, base64-encoded.
                format:
                  type: string
                  enum:
                    - wav
                    - mp3
    ToolCall:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum:
            - function
        function:
          type: object
          properties:
            name:
              type: string
            arguments:
              type: string
              description: The arguments as a JSON string.
  responses:
    BadRequest:
      description: Malformed request (bad JSON, missing/invalid parameters).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              message: Authentication Error, Invalid proxy server token passed.
              type: token_not_found_in_db
              param: key
              code: '401'
    Forbidden:
      description: >
        The key cannot access this model. Unknown model IDs return this status
        too —

        check the `model` against the published catalog. A URL path the API does
        not serve

        (for example one built on a wrong base URL) is also refused with `403`,
        by the

        network edge and without a JSON body.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              message: >-
                key not allowed to access model. Tried to access
                primalabs-ai/does-not-exist
              type: key_model_access_denied
              param: model
              code: '403'
    BalanceExhausted:
      description: >
        Your balance has reached zero. Retrying will not help until you top up
        on the

        [dashboard](https://dashboard.primalabs.ai); check `GET /credits`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              message: >-
                ExceededBudget: User=<your user id> over budget. Spend=25.0,
                Budget=25.0
              type: budget_exceeded
              code: '422'
    RateLimited:
      description: >
        Rate limited. One of three layers tripped — per-IP, per-user fair share,
        or

        per-model admission. Back off and retry with jitter; honor `Retry-After`
        when present.

        The per-IP limit is enforced at the network edge and returns no JSON
        body.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServerError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unavailable:
      description: The model has no healthy capacity right now. Retry shortly.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Your PrimaLabs API key, sent as `Authorization: Bearer <key>`.'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.