openapi: 3.1.0
info:
  title: Cerebras Inference Chat Completions API
  version: 1.0.0
  description: 'Generate conversational responses using a structured message format with roles (system, user, assistant, developer, tool). Best for chatbots, assistants, and multi-turn conversations.

    '
servers:
- url: https://api.cerebras.ai
  description: Cerebras Inference API
security:
- BearerAuth: []
tags:
- name: Completions
paths:
  /v1/completions:
    post:
      operationId: completions_v1_completions_post
      parameters:
      - in: header
        name: X-Amz-Cf-Id
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Amz-Cf-Id
      - in: header
        name: CF-RAY
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Cf-Ray
      - in: header
        name: X-delay-time
        required: false
        schema:
          anyOf:
          - type: number
          - type: 'null'
          title: X-Delay-Time
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompletionRequest'
          application/msgpack:
            schema:
              $ref: '#/components/schemas/CompletionRequest'
          application/vnd.msgpack:
            schema:
              $ref: '#/components/schemas/CompletionRequest'
          application/x-msgpack:
            schema:
              $ref: '#/components/schemas/CompletionRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCompletionResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
      - HTTPBearer: []
      summary: Completions
      tags:
      - Completions
components:
  schemas:
    CreateCompletionResponse:
      anyOf:
      - $ref: '#/components/schemas/CompletionResponse'
      - $ref: '#/components/schemas/ErrorChunkResponse'
      title: CreateCompletionResponse
    CompletionResponse:
      additionalProperties: false
      examples:
      - choices:
        - finish_reason: stop
          index: 0
          text: "Generative AI is a subfield of artificial intelligence that focuses on generating new, original content, such as images, music, text, or videos. These models are trained on large datasets and learn to recognize patterns, relationships, and structures within the data, allowing them to generate new content that is similar in style, tone, or characteristics to the training data. \n \n Generative AI models can be categorized into two main types: Generative Adversarial Networks (GANs) and Variational Autoencoders (VAEs). GANs consist of two neural networks: a generator and a discriminator. The generator creates new content, while the discriminator evaluates the generated content and tells the generator whether it's realistic or not. VAEs are neural networks that learn to compress and reconstruct data. \n \n Generative AI has numerous applications across various industries, including art and design, content generation, data augmentation, and recommendation systems. Some examples of Generative AI in action include Deep Dream Generator, Amper Music, and DALL-E. \n \n In summary, Generative AI is a powerful technology that enables the creation of new, original content using machine learning models. It has the potential to revolutionize various industries and create new opportunities for artists, designers, and content creators."
        created: 1721088719
        id: response_1721
        model: llama3.1-8b
        object: text_completion
        system_fingerprint: '88719'
        time_info:
          completion_time: 0.44
          prompt_time: 0.02
          queue_time: 0.0
          total_time: 0.46
        usage:
          completion_tokens: 1020
          prompt_tokens: 40
          total_tokens: 1060
      properties:
        choices:
          items:
            $ref: '#/components/schemas/CompletionChoice'
          minItems: 1
          title: Choices
          type: array
        created:
          title: Created
          type: integer
        id:
          title: Id
          type: string
        model:
          title: Model
          type: string
        object:
          const: text_completion
          title: Object
          type: string
        system_fingerprint:
          title: System Fingerprint
          type: string
        time_info:
          anyOf:
          - $ref: '#/components/schemas/TimeInfo'
          - type: 'null'
        usage:
          anyOf:
          - $ref: '#/components/schemas/Usage'
          - type: 'null'
      required:
      - id
      - choices
      - created
      - model
      - system_fingerprint
      - object
      title: CompletionResponse
      type: object
    PromptTokensDetails:
      additionalProperties: false
      examples:
      - cached_tokens: 1020
      properties:
        cached_tokens:
          default: 0
          title: Cached Tokens
          type: integer
      title: PromptTokensDetails
      type: object
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
      - loc
      - msg
      - type
      title: ValidationError
      type: object
    Usage:
      additionalProperties: false
      examples:
      - completion_tokens: 1020
        prompt_tokens: 40
        prompt_tokens_details:
          cached_tokens: 1020
        total_tokens: 1060
      properties:
        completion_tokens:
          default: 0
          title: Completion Tokens
          type: integer
        completion_tokens_details:
          anyOf:
          - $ref: '#/components/schemas/CompletionTokensDetails'
          - type: 'null'
        image_tokens:
          anyOf:
          - type: integer
          - type: 'null'
          title: Image Tokens
        prompt_tokens:
          default: 0
          title: Prompt Tokens
          type: integer
        prompt_tokens_details:
          anyOf:
          - $ref: '#/components/schemas/PromptTokensDetails'
          - type: 'null'
        total_tokens:
          default: 0
          title: Total Tokens
          type: integer
      title: Usage
      type: object
    CompletionChoice:
      additionalProperties: false
      properties:
        finish_reason:
          anyOf:
          - enum:
            - stop
            - length
            - content_filter
            - tool_calls
            type: string
          - type: 'null'
          title: Finish Reason
        index:
          title: Index
          type: integer
        logprobs:
          anyOf:
          - $ref: '#/components/schemas/CompletionLogProbs'
          - type: 'null'
        text:
          anyOf:
          - type: string
          - type: 'null'
          title: Text
        tokens:
          anyOf:
          - items:
              type: integer
            type: array
          - type: 'null'
          title: Tokens
      required:
      - index
      title: CompletionChoice
      type: object
    ErrorChunkContent:
      additionalProperties: false
      properties:
        code:
          anyOf:
          - type: string
          - type: 'null'
          default: ''
          title: Code
        id:
          anyOf:
          - type: string
          - type: 'null'
          default: ''
          title: Id
        message:
          anyOf:
          - type: string
          - type: 'null'
          default: ''
          title: Message
        param:
          anyOf:
          - type: string
          - type: 'null'
          default: ''
          title: Param
        type:
          anyOf:
          - type: string
          - type: 'null'
          default: ''
          title: Type
      title: ErrorChunkContent
      type: object
    CompletionLogProbs:
      additionalProperties: false
      properties:
        text_offset:
          anyOf:
          - items:
              type: integer
            type: array
          - type: 'null'
          title: Text Offset
        token_logprobs:
          anyOf:
          - items:
              type: number
            type: array
          - type: 'null'
          title: Token Logprobs
        tokens:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Tokens
        top_logprobs:
          anyOf:
          - items:
              additionalProperties:
                type: number
              type: object
            type: array
          - type: 'null'
          title: Top Logprobs
      title: CompletionLogProbs
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    StreamOptions:
      additionalProperties: false
      description: Options for streaming.
      properties:
        include_usage:
          anyOf:
          - type: boolean
          - type: 'null'
          default: null
          title: Include Usage
      title: StreamOptions
      type: object
    ReasoningFormat:
      enum:
      - none
      - parsed
      - text_parsed
      - raw
      - hidden
      title: ReasoningFormat
      type: string
    CompletionRequest:
      additionalProperties: false
      description: Request for completions endpoint
      examples:
      - model: llama3.1-70b
        prompt: 'Micheael Jordan is born in '
        stream: true
      properties:
        best_of:
          anyOf:
          - maximum: 20
            minimum: 0
            type: integer
          - type: 'null'
          default: 1
          description: Generates `best_of` completions server-side and returns the "best" (the one with the highest log probability per token). Results cannot be streamed. When used with `n`, `best_of` controls the number of candidate completions and `n` specifies how many to return – `best_of` must be greater than `n`. **Note:** Because this parameter generates many completions, it can quickly consume your token quota. Use carefully and ensure that you have reasonable settings for `max_tokens` and `stop`
          title: Best Of
        echo:
          anyOf:
          - type: boolean
          - type: 'null'
          default: false
          description: Echo back the prompt in addition to the completion
          title: Echo
        frequency_penalty:
          anyOf:
          - maximum: 2
            minimum: -2
            type: number
          - type: 'null'
          default: 0.0
          description: Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim.
          title: Frequency Penalty
        grammar_root:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          description: The grammar root used for structured output generation.
          title: Grammar Root
        logit_bias:
          anyOf:
          - additionalProperties:
              type: number
            type: object
          - type: 'null'
          default: null
          description: "Modify the likelihood of specified tokens appearing in the completion.\n \n Accepts a JSON object that maps tokens (specified by their token ID in the tokenizer) to an associated bias value from -100 to 100. Mathematically, the bias is added to the logits generated by the model prior to sampling. The exact effect will vary per model, but values between -1 and 1 should decrease or increase likelihood of selection; values like -100 or 100 should result in a ban or exclusive selection of the relevant token."
          title: Logit Bias
        logprobs:
          anyOf:
          - maximum: 20
            minimum: 0
            type: integer
          - type: 'null'
          default: null
          description: Include the log probabilities on the logprobs most likely output tokens, as well the chosen tokens. For example, if logprobs is 5, the API will return a list of the 5 most likely tokens. The API will always return the logprob of the sampled token, so there may be up to logprobs+1 elements in the response.
          title: Logprobs
        max_tokens:
          anyOf:
          - minimum: -1
            type: integer
          - type: 'null'
          default: null
          description: 'The maximum number of tokens that can be generated in the chat completion. The total length of input tokens and generated tokens is limited by the model''s context length. '
          title: Max Tokens
        min_tokens:
          anyOf:
          - minimum: -1
            type: integer
          - type: 'null'
          default: null
          description: The minimum number of tokens to generate for a completion. If not specified or set to 0, the model will generate as many tokens as it deems necessary. Setting to -1 sets to max sequence length.
          title: Min Tokens
        model:
          title: Model
          type: string
        n:
          anyOf:
          - minimum: 1
            type: integer
          - type: 'null'
          default: 1
          description: How many chat completion choices to generate for each input message. Note that you will be charged based on the number of generated tokens across all of the choices. Keep n as 1 to minimize costs.
          title: N
        presence_penalty:
          anyOf:
          - maximum: 2.0
            minimum: -2.0
            type: number
          - type: 'null'
          default: 0.0
          description: Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics.
          title: Presence Penalty
        prompt:
          anyOf:
          - type: string
          - items:
              type: string
            type: array
          - items:
              minimum: 0
              type: integer
            type: array
          - items:
              items:
                minimum: 0
                type: integer
              type: array
            type: array
          description: The prompt(s) to generate completions for, encoded as a string, array of strings, array of tokens, or array of token arrays.
          title: Prompt
        prompt_cache_key:
          anyOf:
          - maxLength: 1024
            type: string
          - type: 'null'
          default: null
          description: An optional opaque string. The requests with the same prompt cache key would highly likely share the same prompt prefixes. Examples would be IDs of chat conversations, IDs of users, the hashes of system prompts, etc.
          title: Prompt Cache Key
        reasoning_format:
          anyOf:
          - $ref: '#/components/schemas/ReasoningFormat'
          - type: 'null'
          default: null
          deprecated: true
          description: Determines how reasoning is returned in the response. If set to `parsed`, the reasoning will be returned in the `reasoning` field of the response message as a string. If set to `raw`, the reasoning will be returned in the `content` field of the response message with special tokens. If set to `hidden`, the reasoning will not be returned in the response.
        return_raw_tokens:
          anyOf:
          - type: boolean
          - type: 'null'
          default: false
          description: Return raw tokens instead of text
          title: Return Raw Tokens
        seed:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          description: If specified, our system will make a best effort to sample deterministically, such that repeated requests with the same `seed` and parameters should return the same result. Determinism is not guaranteed.
          title: Seed
        stop:
          anyOf:
          - type: string
          - items:
              type: string
            maxItems: 4
            type: array
          - type: 'null'
          default: null
          description: Up to 4 sequences where the API will stop generating further tokens. The returned text will not contain the stop sequence.
          title: Stop
        stream:
          anyOf:
          - type: boolean
          - type: 'null'
          default: false
          title: Stream
        stream_options:
          anyOf:
          - $ref: '#/components/schemas/StreamOptions'
          - type: 'null'
          default: null
        suffix:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          description: The suffix that comes after a completion of inserted text. (OpenAI feature, not supported)
          title: Suffix
        temperature:
          anyOf:
          - maximum: 2.0
            minimum: 0
            type: number
          - type: 'null'
          default: 1.0
          description: What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both.
          title: Temperature
        top_p:
          anyOf:
          - maximum: 1
            minimum: 0
            type: number
          - type: 'null'
          default: 1.0
          description: An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or `temperature` but not both.
          title: Top P
        user:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          description: 'A unique identifier representing your end-user, which can help Cerebras to monitor and detect abuse. '
          title: User
      required:
      - model
      - prompt
      title: CompletionRequest
      type: object
    TimeInfo:
      additionalProperties: false
      description: 'Time information for different phases of request processing.


        All times are measured in seconds.'
      examples:
      - completion_time: 0.44
        prompt_time: 0.02
        queue_time: 0.0
        total_time: 0.46
      properties:
        completion_time:
          anyOf:
          - minimum: 0.0
            type: number
          - type: 'null'
          title: Completion Time
        created:
          anyOf:
          - minimum: 0.0
            type: number
          - type: 'null'
          title: Created
        prompt_time:
          anyOf:
          - minimum: 0.0
            type: number
          - type: 'null'
          title: Prompt Time
        queue_time:
          anyOf:
          - minimum: 0.0
            type: number
          - type: 'null'
          title: Queue Time
        total_time:
          anyOf:
          - minimum: 0.0
            type: number
          - type: 'null'
          title: Total Time
      title: TimeInfo
      type: object
    CompletionTokensDetails:
      additionalProperties: false
      examples:
      - accepted_prediction_tokens: 900
        rejected_prediction_tokens: 100
      properties:
        accepted_prediction_tokens:
          anyOf:
          - type: integer
          - type: 'null'
          title: Accepted Prediction Tokens
        reasoning_tokens:
          anyOf:
          - type: integer
          - type: 'null'
          title: Reasoning Tokens
        rejected_prediction_tokens:
          anyOf:
          - type: integer
          - type: 'null'
          title: Rejected Prediction Tokens
      title: CompletionTokensDetails
      type: object
    ErrorChunkResponse:
      additionalProperties: false
      properties:
        error:
          $ref: '#/components/schemas/ErrorChunkContent'
        status_code:
          title: Status Code
          type: integer
      required:
      - status_code
      - error
      title: ErrorChunkResponse
      type: object
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'API key for authentication. Obtain your key from the Cerebras Cloud console and pass it as `Authorization: Bearer YOUR_API_KEY`.

        '