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`.
'