> ## Documentation Index > Fetch the complete documentation index at: https://docs.obiguard.ai/llms.txt > Use this file to discover all available pages before exploring further. # Chat ## OpenAPI ````yaml post /chat/completions openapi: 3.0.0 info: title: Obiguard API description: >- The Obiguard REST API. Please see https://docs.obiguard.ai/docs/api-reference for more details. version: 1.0.0 termsOfService: https://obiguard.ai/terms servers: - url: https://gateway.obiguard.ai/v1 security: [] tags: - name: Audio description: Turn audio into text or text into audio. - name: Chat description: >- Given a list of messages comprising a conversation, the model will return a response. - name: Completions description: >- Given a prompt, the model will return one or more predicted completions, and can also return the probabilities of alternative tokens at each position. - name: Embeddings description: >- Get a vector representation of a given input that can be easily consumed by machine learning models and algorithms. - name: Fine-tuning description: Manage fine-tuning jobs to tailor a model to your specific training data. - name: Files description: >- Files are used to upload documents that can be used with features like Assistants and Fine-tuning. - name: Images description: Given a prompt and/or an input image, the model will generate a new image. paths: /chat/completions: post: tags: - Chat summary: Chat operationId: createChatCompletion requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateChatCompletionRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/CreateChatCompletionResponse' security: - Obiguard-API-Key: [] servers: - url: https://gateway.obiguard.ai/v1 x-code-samples: - lang: cURL label: Default source: | curl https://gateway.obiguard.ai/v1/chat/completions \ -H "Content-Type: application/json" \ -H "x-obiguard-api-key: $OBIGUARD_API_KEY" \ -d '{ "model": "gpt-4o", "messages": [ { "role": "system", "content": "You are a helpful assistant." }, { "role": "user", "content": "Hello!" } ] }' - lang: python label: Default source: | from obiguard import Obiguard client = Obiguard( obiguard_api_key="vk-obg***", # Your Obiguard virtual key ) response = client.chat.completions.create( model="gpt-4o", messages=[ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Hello!"} ] ) print(response.choices[0].message) components: schemas: CreateChatCompletionRequest: type: object properties: messages: description: >- A list of messages comprising the conversation so far. [Example Python code](https://cookbook.openai.com/examples/how_to_format_inputs_to_chatgpt_models). type: array minItems: 1 items: $ref: '#/components/schemas/ChatCompletionRequestMessage' model: description: >- ID of the model to use. See the [model endpoint compatibility](https://platform.openai.com/docs/models/model-endpoint-compatibility) table for details on which models work with the Chat API. example: gpt-4-turbo anyOf: - type: string - type: string enum: - gpt-4o - gpt-4o-2024-05-13 - gpt-4-turbo - gpt-4-turbo-2024-04-09 - gpt-4-0125-preview - gpt-4-turbo-preview - gpt-4-1106-preview - gpt-4-vision-preview - gpt-4 - gpt-4-0314 - gpt-4-0613 - gpt-4-32k - gpt-4-32k-0314 - gpt-4-32k-0613 - gpt-3.5-turbo - gpt-3.5-turbo-16k - gpt-3.5-turbo-0301 - gpt-3.5-turbo-0613 - gpt-3.5-turbo-1106 - gpt-3.5-turbo-0125 - gpt-3.5-turbo-16k-0613 x-oaiTypeLabel: string frequency_penalty: type: number default: 0 minimum: -2 maximum: 2 nullable: true 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. [See more information about frequency and presence penalties.](https://platform.openai.com/docs/guides/text-generation/parameter-details) logit_bias: type: object x-oaiTypeLabel: map default: null nullable: true additionalProperties: type: integer description: > Modify the likelihood of specified tokens appearing in the completion. 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. logprobs: description: >- Whether to return log probabilities of the output tokens or not. If true, returns the log probabilities of each output token returned in the `content` of `message`. type: boolean default: false nullable: true top_logprobs: description: >- An integer between 0 and 20 specifying the number of most likely tokens to return at each token position, each with an associated log probability. `logprobs` must be set to `true` if this parameter is used. type: integer minimum: 0 maximum: 20 nullable: true max_tokens: description: > The maximum number of [tokens](https://platform.openai.com/tokenizer?view=bpe) 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. [Example Python code](https://cookbook.openai.com/examples/how_to_count_tokens_with_tiktoken) for counting tokens. type: integer nullable: true 'n': type: integer minimum: 1 maximum: 128 default: 1 example: 1 nullable: true 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. presence_penalty: type: number default: 0 minimum: -2 maximum: 2 nullable: true 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. [See more information about frequency and presence penalties.](https://platform.openai.com/docs/guides/text-generation/parameter-details) response_format: type: object description: > An object specifying the format that the model must output. Setting to `{ "type": "json_schema", "json_schema": {...} }`enables Structured Outputs which ensures the model will match your supplied JSON schema. Works across all the providers that support this functionality. [OpenAI & Azure OpenAI](/integrations/llms/openai/structured-outputs), [Gemini & Vertex AI](/integrations/llms/vertex-ai/controlled-generations). Setting to `{ "type": "json_object" }` enables the older JSON mode, which ensures the message the model generates is valid JSON. Using `json_schema` is preferred for models that support it. oneOf: - $ref: '#/components/schemas/ResponseFormatText' - $ref: '#/components/schemas/ResponseFormatJsonSchema' - $ref: '#/components/schemas/ResponseFormatJsonObject' seed: type: integer minimum: -9223372036854776000 maximum: 9223372036854776000 nullable: true description: > This feature is in Beta. 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, and you should refer to the `system_fingerprint` response parameter to monitor changes in the backend. x-code-samples: beta: true stop: description: | Up to 4 sequences where the API will stop generating further tokens. default: null oneOf: - type: string nullable: true - type: array minItems: 1 maxItems: 4 items: type: string stream: description: > If set, partial message deltas will be sent, like in ChatGPT. Tokens will be sent as data-only [server-sent events](https://developer.mozilla.org/en-UShttps://platform.openai.com/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format) as they become available, with the stream terminated by a `data: [DONE]` message. [Example Python code](https://cookbook.openai.com/examples/how_to_stream_completions). type: boolean nullable: true default: false stream_options: $ref: '#/components/schemas/ChatCompletionStreamOptions' thinking: type: object nullable: true description: > View the thinking/reasoning tokens as part of your response. Thinking models produce a long internal chain of thought before generating a response. Supported only for specific Claude models on Anthropic, Google Vertex AI, and AWS Bedrock. Requires setting `strict_openai_compliance = false` in your API call. properties: type: type: string enum: - enabled - disabled description: Enables or disables the thinking mode capability. default: disabled budget_tokens: type: integer description: > The maximum number of tokens to allocate for the thinking process. A higher token budget allows for more thorough reasoning but may increase overall response time. minimum: 1 example: 2030 required: - type example: type: enabled budget_tokens: 2030 temperature: type: number minimum: 0 maximum: 2 default: 1 example: 1 nullable: true 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. top_p: type: number minimum: 0 maximum: 1 default: 1 example: 1 nullable: true 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. tools: type: array description: > A list of tools the model may call. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for. A max of 128 functions are supported. items: $ref: '#/components/schemas/ChatCompletionTool' tool_choice: $ref: '#/components/schemas/ChatCompletionToolChoiceOption' parallel_tool_calls: $ref: '#/components/schemas/ParallelToolCalls' user: type: string example: user-1234 description: > A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices/end-user-ids). function_call: deprecated: true description: > Deprecated in favor of `tool_choice`. Controls which (if any) function is called by the model. `none` means the model will not call a function and instead generates a message. `auto` means the model can pick between generating a message or calling a function. Specifying a particular function via `{"name": "my_function"}` forces the model to call that function. `none` is the default when no functions are present. `auto` is the default if functions are present. oneOf: - type: string description: > `none` means the model will not call a function and instead generates a message. `auto` means the model can pick between generating a message or calling a function. enum: - none - auto - $ref: '#/components/schemas/ChatCompletionFunctionCallOption' x-oaiExpandable: true functions: deprecated: true description: | Deprecated in favor of `tools`. A list of functions the model may generate JSON inputs for. type: array minItems: 1 maxItems: 128 items: $ref: '#/components/schemas/ChatCompletionFunctions' required: - model - messages CreateChatCompletionResponse: type: object description: >- Represents a chat completion response returned by model, based on the provided input. properties: id: type: string description: A unique identifier for the chat completion. choices: type: array description: >- A list of chat completion choices. Can be more than one if `n` is greater than 1. items: type: object required: - finish_reason - index - message - logprobs properties: finish_reason: type: string description: > The reason the model stopped generating tokens. This will be `stop` if the model hit a natural stop point or a provided stop sequence, `length` if the maximum number of tokens specified in the request was reached, `content_filter` if content was omitted due to a flag from our content filters, `tool_calls` if the model called a tool, or `function_call` (deprecated) if the model called a function. enum: - stop - length - tool_calls - content_filter - function_call index: type: integer description: The index of the choice in the list of choices. message: $ref: '#/components/schemas/ChatCompletionResponseMessage' logprobs: description: Log probability information for the choice. type: object nullable: true properties: content: description: >- A list of message content tokens with log probability information. type: array items: $ref: '#/components/schemas/ChatCompletionTokenLogprob' nullable: true required: - content created: type: integer description: >- The Unix timestamp (in seconds) of when the chat completion was created. model: type: string description: The model used for the chat completion. system_fingerprint: type: string description: > This fingerprint represents the backend configuration that the model runs with. Can be used in conjunction with the `seed` request parameter to understand when backend changes have been made that might impact determinism. object: type: string description: The object type, which is always `chat.completion`. enum: - chat.completion usage: $ref: '#/components/schemas/CompletionUsage' required: - choices - created - id - model - object ChatCompletionRequestMessage: oneOf: - $ref: '#/components/schemas/ChatCompletionRequestSystemMessage' - $ref: '#/components/schemas/ChatCompletionRequestDeveloperMessage' - $ref: '#/components/schemas/ChatCompletionRequestUserMessage' - $ref: '#/components/schemas/ChatCompletionRequestAssistantMessage' - $ref: '#/components/schemas/ChatCompletionRequestToolMessage' - $ref: '#/components/schemas/ChatCompletionRequestFunctionMessage' x-oaiExpandable: true ResponseFormatText: type: object title: Text description: | Default response format. Used to generate text responses. properties: type: type: string description: The type of response format being defined. Always `text`. enum: - text required: - type ResponseFormatJsonSchema: type: object title: JSON schema description: > JSON Schema response format. Used to generate structured JSON responses. Learn more about [Structured Outputs](/integrations/llms/openai/structured-outputs). properties: type: type: string description: The type of response format being defined. Always `json_schema`. enum: - json_schema json_schema: type: object title: JSON schema description: | Structured Outputs configuration options, including a JSON Schema. properties: description: type: string description: | A description of what the response format is for, used by the model to determine how to respond in the format. name: type: string description: > The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. schema: $ref: '#/components/schemas/ResponseFormatJsonSchemaSchema' strict: type: boolean nullable: true default: false description: > Whether to enable strict schema adherence when generating the output. If set to true, the model will always follow the exact schema defined in the `schema` field. Only a subset of JSON Schema is supported when `strict` is `true`. required: - name required: - type - json_schema ResponseFormatJsonObject: type: object title: JSON object description: > JSON object response format. An older method of generating JSON responses. Using `json_schema` is recommended for models that support it. Note that the model will not generate JSON without a system or user message instructing it to do so. properties: type: type: string description: The type of response format being defined. Always `json_object`. enum: - json_object required: - type ChatCompletionStreamOptions: description: > Options for streaming response. Only set this when you set `stream: true`. type: object nullable: true default: null properties: include_usage: type: boolean description: > If set, an additional chunk will be streamed before the `data: [DONE]` message. The `usage` field on this chunk shows the token usage statistics for the entire request, and the `choices` field will always be an empty array. All other chunks will also include a `usage` field, but with a null value. ChatCompletionTool: type: object properties: type: type: string enum: - function description: The type of the tool. Currently, only `function` is supported. function: $ref: '#/components/schemas/FunctionObject' required: - type - function ChatCompletionToolChoiceOption: description: > Controls which (if any) tool is called by the model. `none` means the model will not call any tool and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools. Specifying a particular tool via `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. `none` is the default when no tools are present. `auto` is the default if tools are present. oneOf: - type: string description: > `none` means the model will not call any tool and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools. enum: - none - auto - required - $ref: '#/components/schemas/ChatCompletionNamedToolChoice' x-oaiExpandable: true ParallelToolCalls: description: >- Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling/parallel-function-calling) during tool use. type: boolean default: true ChatCompletionFunctionCallOption: type: object description: > Specifying a particular function via `{"name": "my_function"}` forces the model to call that function. properties: name: type: string description: The name of the function to call. required: - name ChatCompletionFunctions: type: object deprecated: true properties: description: type: string description: >- A description of what the function does, used by the model to choose when and how to call the function. name: type: string description: >- The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. parameters: $ref: '#/components/schemas/FunctionParameters' required: - name ChatCompletionResponseMessage: type: object description: A chat completion message generated by the model. properties: content: type: string description: The contents of the message. nullable: true tool_calls: $ref: '#/components/schemas/ChatCompletionMessageToolCalls' role: type: string enum: - assistant description: The role of the author of this message. function_call: type: object deprecated: true description: >- Deprecated and replaced by `tool_calls`. The name and arguments of a function that should be called, as generated by the model. properties: arguments: type: string description: >- The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function. name: type: string description: The name of the function to call. required: - name - arguments content_blocks: nullable: true type: array description: >- The content blocks of the message. This is only present for certain providers with strict-open-ai-compliance flag set to false items: $ref: '#/components/schemas/ChatCompletionMessageContentBlock' type: object required: - role - content ChatCompletionTokenLogprob: type: object properties: token: description: The token. type: string logprob: description: >- The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value `-9999.0` is used to signify that the token is very unlikely. type: number bytes: description: >- A list of integers representing the UTF-8 bytes representation of the token. Useful in instances where characters are represented by multiple tokens and their byte representations must be combined to generate the correct text representation. Can be `null` if there is no bytes representation for the token. type: array items: type: integer nullable: true top_logprobs: description: >- List of the most likely tokens and their log probability, at this token position. In rare cases, there may be fewer than the number of requested `top_logprobs` returned. type: array items: type: object properties: token: description: The token. type: string logprob: description: >- The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value `-9999.0` is used to signify that the token is very unlikely. type: number bytes: description: >- A list of integers representing the UTF-8 bytes representation of the token. Useful in instances where characters are represented by multiple tokens and their byte representations must be combined to generate the correct text representation. Can be `null` if there is no bytes representation for the token. type: array items: type: integer nullable: true required: - token - logprob - bytes required: - token - logprob - bytes - top_logprobs CompletionUsage: type: object description: Usage statistics for the completion request. properties: completion_tokens: type: integer description: Number of tokens in the generated completion. prompt_tokens: type: integer description: Number of tokens in the prompt. total_tokens: type: integer description: Total number of tokens used in the request (prompt + completion). required: - prompt_tokens - completion_tokens - total_tokens ChatCompletionRequestSystemMessage: type: object title: System message properties: content: description: The contents of the system message. type: string role: type: string enum: - system description: The role of the messages author, in this case `system`. name: type: string description: >- An optional name for the participant. Provides the model information to differentiate between participants of the same role. required: - content - role ChatCompletionRequestDeveloperMessage: type: object title: Developer message description: >- New role by OpenAI for select models. Must be explicitly used for models that support it. When used with incompatible models or providers, Obiguard automatically converts it to a system role. properties: content: description: The contents of the Developer message. type: string role: type: string enum: - developer description: The role of the messages author, in this case `Developer`. name: type: string description: >- An optional name for the participant. Provides the model information to differentiate between participants of the same role. required: - content - role ChatCompletionRequestUserMessage: type: object title: User message properties: content: description: | The contents of the user message. oneOf: - type: string description: The text contents of the message. title: Text content - type: array description: >- An array of content parts with a defined type, each can be of type `text` or `image_url` when passing in images. You can pass multiple images by adding multiple `image_url` content parts. Image input is only supported when using the `gpt-4-visual-preview` model. title: Array of content parts items: $ref: '#/components/schemas/ChatCompletionRequestMessageContentPart' minItems: 1 x-oaiExpandable: true role: type: string enum: - user description: The role of the messages author, in this case `user`. name: type: string description: >- An optional name for the participant. Provides the model information to differentiate between participants of the same role. required: - content - role ChatCompletionRequestAssistantMessage: type: object title: Assistant message properties: content: nullable: true type: string description: > The contents of the assistant message. Required unless `tool_calls` or `function_call` is specified. role: type: string enum: - assistant description: The role of the messages author, in this case `assistant`. name: type: string description: >- An optional name for the participant. Provides the model information to differentiate between participants of the same role. tool_calls: $ref: '#/components/schemas/ChatCompletionMessageToolCalls' function_call: type: object deprecated: true description: >- Deprecated and replaced by `tool_calls`. The name and arguments of a function that should be called, as generated by the model. nullable: true properties: arguments: type: string description: >- The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function. name: type: string description: The name of the function to call. required: - arguments - name required: - role ChatCompletionRequestToolMessage: type: object title: Tool message properties: role: type: string enum: - tool description: The role of the messages author, in this case `tool`. content: type: string description: The contents of the tool message. tool_call_id: type: string description: Tool call that this message is responding to. required: - role - content - tool_call_id ChatCompletionRequestFunctionMessage: type: object title: Function message deprecated: true properties: role: type: string enum: - function description: The role of the messages author, in this case `function`. content: nullable: true type: string description: The contents of the function message. name: type: string description: The name of the function to call. required: - role - content - name ResponseFormatJsonSchemaSchema: type: object title: JSON schema description: | The schema for the response format, described as a JSON Schema object. Learn how to build JSON schemas [here](https://json-schema.org/). additionalProperties: true FunctionObject: type: object properties: description: type: string description: >- A description of what the function does, used by the model to choose when and how to call the function. name: type: string description: >- The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. parameters: $ref: '#/components/schemas/FunctionParameters' required: - name ChatCompletionNamedToolChoice: type: object description: >- Specifies a tool the model should use. Use to force the model to call a specific function. properties: type: type: string enum: - function description: The type of the tool. Currently, only `function` is supported. function: type: object properties: name: type: string description: The name of the function to call. required: - name required: - type - function FunctionParameters: type: object description: >- The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. Omitting `parameters` defines a function with an empty parameter list. additionalProperties: true ChatCompletionMessageToolCalls: type: array description: The tool calls generated by the model, such as function calls. items: $ref: '#/components/schemas/ChatCompletionMessageToolCall' ChatCompletionMessageContentBlock: type: object description: A block of content in a chat completion message. oneOf: - $ref: '#/components/schemas/ChatCompletionRequestMessageContentPartText' - $ref: '#/components/schemas/ChatCompletionMessageContentPartThinking' - $ref: >- #/components/schemas/ChatCompletionMessageContentPartRedactedThinking ChatCompletionRequestMessageContentPart: oneOf: - $ref: '#/components/schemas/ChatCompletionRequestMessageContentPartText' - $ref: '#/components/schemas/ChatCompletionRequestMessageContentPartImage' x-oaiExpandable: true ChatCompletionMessageToolCall: type: object properties: id: type: string description: The ID of the tool call. type: type: string enum: - function description: The type of the tool. Currently, only `function` is supported. function: type: object description: The function that the model called. properties: name: type: string description: The name of the function to call. arguments: type: string description: >- The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function. required: - name - arguments required: - id - type - function ChatCompletionRequestMessageContentPartText: type: object title: Text content part properties: type: type: string enum: - text description: The type of the content part. text: type: string description: The text content. required: - type - text ChatCompletionMessageContentPartThinking: type: object title: Thinking content part properties: type: type: string enum: - thinking description: The type of the content part. thinking: type: string description: The thinking content. required: - type - thinking ChatCompletionMessageContentPartRedactedThinking: type: object title: Redacted thinking content part properties: type: type: string enum: - redacted_thinking description: The type of the content part. data: type: string description: The redacted thinking content. required: - type - data ChatCompletionRequestMessageContentPartImage: type: object title: Image content part properties: type: type: string enum: - image_url description: The type of the content part. image_url: type: object properties: url: type: string description: Either a URL of the image or the base64 encoded image data. format: uri detail: type: string description: >- Specifies the detail level of the image. Learn more in the [Vision guide](https://platform.openai.com/docs/guides/vision/low-or-high-fidelity-image-understanding). enum: - auto - low - high default: auto required: - url required: - type - image_url securitySchemes: Obiguard-API-Key: type: apiKey in: header name: x-obiguard-api-key ````