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

# Create a chat completion

> OpenAI-compatible Chat Completions endpoint. Supports streaming via stream: true, which returns a Server-Sent Events stream of chat.completion.chunk objects.



## OpenAPI

````yaml POST /chat/completions
openapi: 3.1.0
info:
  title: Valar API
  version: '2026-02-18'
  description: >-
    Valar exposes Responses and Chat Completions endpoints that match the OpenAI
    shape. This reference documents the fields Valar supports today.
servers:
  - url: https://api.valarhq.ai/v1
security:
  - BearerAuth: []
tags:
  - name: Models API
    description: Discover which models you can call.
  - name: Responses API
    description: Responses endpoints that follow the OpenAI interface.
  - name: Chat Completions API
    description: Chat Completions endpoints that follow the OpenAI interface.
  - name: Batches API
    description: Submit request batches and track their progress.
paths:
  /chat/completions:
    post:
      tags:
        - Chat Completions API
      summary: Create a chat completion
      description: >-
        A Chat Completions endpoint that follows the OpenAI interface. Pass
        stream: true to stream the reply back as Server-Sent Events made up of
        chat.completion.chunk objects.
      operationId: createChatCompletion
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateChatCompletionRequest'
            example:
              model: zai-org/GLM-5.2-FP8
              messages:
                - role: system
                  content: You are a concise assistant.
                - role: user
                  content: Summarize retrieval-augmented generation in 3 bullets.
              max_completion_tokens: 300
      responses:
        '200':
          description: >-
            The chat completion. By default this is one JSON object; with
            stream: true it becomes a Server-Sent Events stream of
            chat.completion.chunk objects closed by a final data: [DONE] line.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionResponse'
            text/event-stream:
              schema:
                $ref: '#/components/schemas/ChatCompletionChunk'
        '400':
          description: >-
            Your request was malformed or asked for something Valar does not
            support.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: We could not authenticate the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '408':
          description: The request timed out before the result was ready.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Something went wrong on Valar's side.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      schema:
        type: string
        maxLength: 255
      description: >-
        Lets you retry safely. Valar records a reservation under the combination
        of organization, API key, and Idempotency-Key, so sending the same value
        again hands back the stored response rather than running inference a
        second time. Values can be up to 255 characters. See [Idempotent
        Requests](/idempotency) for the complete rules.
  schemas:
    CreateChatCompletionRequest:
      type: object
      required:
        - model
        - messages
      properties:
        model:
          type: string
        messages:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/ChatCompletionMessage'
        temperature:
          oneOf:
            - type: number
              minimum: 0
              maximum: 2
            - type: 'null'
        top_p:
          oneOf:
            - type: number
              minimum: 0
              maximum: 1
            - type: 'null'
        max_completion_tokens:
          oneOf:
            - type: integer
              minimum: 1
            - type: 'null'
        response_format:
          oneOf:
            - $ref: '#/components/schemas/ChatResponseFormatText'
            - $ref: '#/components/schemas/ChatResponseFormatJsonSchema'
        reasoning_effort:
          oneOf:
            - type: string
              enum:
                - none
                - minimal
                - low
                - medium
                - high
                - xhigh
            - type: 'null'
        'n':
          type: integer
          enum:
            - 1
          description: Must be 1; requesting multiple choices is not supported yet.
        modalities:
          type: array
          minItems: 1
          maxItems: 1
          items:
            type: string
            enum:
              - text
        stream:
          type: boolean
          description: >-
            Set this to true to receive the answer as a Server-Sent Events
            stream of chat.completion.chunk objects rather than one JSON
            payload.
        stream_options:
          type: object
          description: Settings that only take effect while streaming (stream is true).
          properties:
            include_usage:
              type: boolean
              description: >-
                Set this to true to receive one final chunk carrying token usage
                for the whole request, sent just ahead of the [DONE] terminator.
          additionalProperties: false
        store:
          type: boolean
          enum:
            - true
          description: Must be true; no other value is accepted.
        user:
          type: string
          maxLength: 256
        metadata:
          $ref: '#/components/schemas/RequestMetadata'
      additionalProperties: true
    ChatCompletionResponse:
      type: object
      required:
        - id
        - object
        - created
        - model
        - choices
      properties:
        id:
          type: string
        object:
          type: string
          enum:
            - chat.completion
        created:
          type: integer
        model:
          type: string
        choices:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/ChatCompletionChoice'
        usage:
          $ref: '#/components/schemas/ChatCompletionUsage'
      additionalProperties: true
    ChatCompletionChunk:
      type: object
      description: >-
        A single Server-Sent Events chunk produced while stream is true. The
        full streamed reply arrives as a series of these chat.completion.chunk
        objects, each delivered on its own SSE data: line, with a closing data:
        [DONE] line at the end.
      required:
        - id
        - object
        - created
        - model
        - choices
      properties:
        id:
          type: string
        object:
          type: string
          enum:
            - chat.completion.chunk
        created:
          type: integer
        model:
          type: string
        choices:
          type: array
          items:
            $ref: '#/components/schemas/ChatCompletionChunkChoice'
        usage:
          $ref: '#/components/schemas/ChatCompletionUsage'
      additionalProperties: false
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorObject'
      additionalProperties: false
    ChatCompletionMessage:
      type: object
      required:
        - role
      properties:
        role:
          type: string
          enum:
            - system
            - user
            - assistant
            - tool
            - function
            - developer
        content:
          oneOf:
            - type: string
            - type: 'null'
            - type: array
              items:
                oneOf:
                  - $ref: '#/components/schemas/ChatTextContentPart'
                  - $ref: '#/components/schemas/ChatImageContentPart'
        name:
          type: string
        tool_calls:
          type: array
          items:
            type: object
            additionalProperties: true
        tool_call_id:
          type: string
        function_call:
          type: object
          additionalProperties: true
      additionalProperties: false
    ChatResponseFormatText:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - text
      additionalProperties: false
    ChatResponseFormatJsonSchema:
      type: object
      required:
        - type
        - json_schema
      properties:
        type:
          type: string
          enum:
            - json_schema
        json_schema:
          type: object
          required:
            - name
          properties:
            name:
              type: string
            description:
              type: string
            schema:
              type: object
              additionalProperties: true
            strict:
              type: boolean
          additionalProperties: false
      additionalProperties: false
    RequestMetadata:
      type: object
      description: >-
        Optional string-valued metadata. Use completion_window to influence
        scheduling, and completion_webhook together with webhook_token to wire
        up a webhook that fires on completion.
      properties:
        completion_window:
          type: string
          description: >-
            The [completion window](/inference-modes#completion-windows), or
            latency tier, you want for this request. `asap` is the on-demand
            **Now** tier; `standard` is the lower-cost default; `flex` is the
            lowest-cost tier for background bulk work and **requires
            `background=true`**. Check the [Pricing](/pricing) page to see which
            windows each model supports. If you leave it out, Valar picks
            `standard` when the model supports it and falls back to `asap`
            otherwise; `flex` is never selected automatically. See [default
            behavior](/inference-modes#default-behavior).
          enum:
            - asap
            - standard
            - flex
        completion_webhook:
          type: string
          format: uri
        webhook_token:
          type: string
      additionalProperties:
        type: string
    ChatCompletionChoice:
      type: object
      required:
        - index
        - message
        - logprobs
        - finish_reason
      properties:
        index:
          type: integer
        message:
          $ref: '#/components/schemas/ChatCompletionResponseMessage'
        logprobs:
          type: 'null'
        finish_reason:
          type: string
          enum:
            - stop
            - length
            - tool_calls
            - content_filter
            - function_call
      additionalProperties: false
    ChatCompletionUsage:
      type: object
      required:
        - prompt_tokens
        - completion_tokens
        - total_tokens
      properties:
        prompt_tokens:
          type: integer
        completion_tokens:
          type: integer
        total_tokens:
          type: integer
        prompt_tokens_details:
          type: object
          additionalProperties: true
        completion_tokens_details:
          type: object
          additionalProperties: true
      additionalProperties: false
    ChatCompletionChunkChoice:
      type: object
      required:
        - index
        - delta
      properties:
        index:
          type: integer
        delta:
          $ref: '#/components/schemas/ChatCompletionChunkDelta'
        logprobs:
          type: 'null'
        finish_reason:
          type:
            - string
            - 'null'
          enum:
            - stop
            - tool_calls
            - null
      additionalProperties: false
    ErrorObject:
      type: object
      required:
        - message
        - type
      properties:
        message:
          type: string
        type:
          type: string
        param:
          oneOf:
            - type: string
            - type: 'null'
        code:
          oneOf:
            - type: string
            - type: integer
            - type: 'null'
      additionalProperties: true
    ChatTextContentPart:
      type: object
      required:
        - type
        - text
      properties:
        type:
          type: string
          enum:
            - text
        text:
          type: string
      additionalProperties: false
    ChatImageContentPart:
      type: object
      description: >-
        An image content part. You can only send image input to multimodal
        models; check the Models page to see which ones qualify.
      required:
        - type
        - image_url
      properties:
        type:
          type: string
          enum:
            - image_url
        image_url:
          type: object
          required:
            - url
          properties:
            url:
              type: string
              description: Either a publicly reachable http(s) URL or a base64 data URI.
            detail:
              type: string
              enum:
                - auto
                - low
                - high
          additionalProperties: false
      additionalProperties: false
    ChatCompletionResponseMessage:
      type: object
      required:
        - role
        - content
      properties:
        role:
          type: string
          enum:
            - assistant
        content:
          oneOf:
            - type: string
            - type: 'null'
        reasoning_content:
          oneOf:
            - type: string
            - type: 'null'
        refusal:
          oneOf:
            - type: string
            - type: 'null'
      additionalProperties: true
    ChatCompletionChunkDelta:
      type: object
      properties:
        role:
          type: string
        content:
          type: string
        reasoning_content:
          type: string
        refusal:
          type: string
        tool_calls:
          type: array
          items:
            $ref: '#/components/schemas/ChatCompletionChunkToolCall'
      additionalProperties: false
    ChatCompletionChunkToolCall:
      type: object
      properties:
        index:
          type: integer
        id:
          type: string
        type:
          type: string
        function:
          $ref: '#/components/schemas/ChatCompletionChunkToolCallFunction'
        custom:
          $ref: '#/components/schemas/ChatCompletionChunkToolCallFunction'
      additionalProperties: false
    ChatCompletionChunkToolCallFunction:
      type: object
      properties:
        name:
          type: string
        arguments:
          type: string
        input:
          type: string
      additionalProperties: false
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key

````