{ "openapi": "3.0.3", "info": { "title": "Perplexity Gateway API (OpenAI-compatible)", "description": "OpenAI Chat Completions-compatible access to models across providers, plus the model catalog. Schema structure follows the OpenAI Chat Completions wire format (derived from the MIT-licensed OpenAI OpenAPI specification); all documentation text is Perplexity's own.", "version": "2.3.0" }, "servers": [ { "url": "https://api.perplexity.ai" } ], "paths": { "/router/v1/chat/completions": { "post": { "summary": "Create Chat Completion", "operationId": "gateway_create_chat_completion", "description": "Send a conversation to any Gateway model using the OpenAI Chat Completions schema. Set `stream: true` to receive server-sent events; add `stream_options: {\"include_usage\": true}` to get token usage in the final chunk.", "security": [ { "HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateChatCompletionRequest" } } } }, "responses": { "200": { "description": "Successful response. JSON for non-streaming requests; a `text/event-stream` of chat completion chunks terminated by `data: [DONE]` when `stream` is true.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateChatCompletionResponse" } }, "text/event-stream": { "schema": { "$ref": "#/components/schemas/CreateChatCompletionStreamResponse" } } } }, "400": { "description": "Invalid request — malformed body, unsupported parameter, or a model that is not available on the Gateway.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded or the upstream model is overloaded. Retry after the `Retry-After` interval.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/router/v1/models": { "get": { "summary": "List Models", "operationId": "gateway_list_models", "description": "List the models available through the Gateway, sorted by id. Each model includes its base token prices in `pricing` (USD per 1M tokens).", "security": [ { "HTTPBearer": [] } ], "responses": { "200": { "description": "The list of available models with base token prices.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelList" } } } } } } }, "/router/v1/models/{model}": { "get": { "summary": "Retrieve Model", "operationId": "gateway_retrieve_model", "description": "Retrieve one model by id, including its base token prices. Model ids contain a `/` (for example `perplexity/kimi-k3`); pass the full id in the path.", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "model", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The model id, e.g. `perplexity/kimi-k3`." } ], "responses": { "200": { "description": "The model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Model" } } } }, "404": { "description": "No model with this id is available on the Gateway.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "schemas": { "ChatCompletionAllowedTools": { "type": "object", "title": "Allowed tools", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ] }, "tools": { "type": "array", "items": { "type": "object", "x-oaiExpandable": false, "additionalProperties": true } } }, "required": [ "mode", "tools" ] }, "ChatCompletionAllowedToolsChoice": { "type": "object", "title": "Allowed tools", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ], "x-stainless-const": true }, "allowed_tools": { "$ref": "#/components/schemas/ChatCompletionAllowedTools" } }, "required": [ "type", "allowed_tools" ] }, "ChatCompletionFunctionCallOption": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] }, "ChatCompletionFunctions": { "type": "object", "deprecated": true, "properties": { "name": { "type": "string" }, "parameters": { "$ref": "#/components/schemas/FunctionParameters" } }, "required": [ "name" ] }, "ChatCompletionMessageCustomToolCall": { "type": "object", "title": "Custom tool call", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ], "x-stainless-const": true }, "custom": { "type": "object", "properties": { "name": { "type": "string" }, "input": { "type": "string" } }, "required": [ "name", "input" ] } }, "required": [ "id", "type", "custom" ] }, "ChatCompletionMessageToolCall": { "type": "object", "title": "Function tool call", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ], "x-stainless-const": true }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "arguments": { "type": "string" } }, "required": [ "name", "arguments" ] } }, "required": [ "id", "type", "function" ] }, "ChatCompletionMessageToolCallChunk": { "type": "object", "properties": { "index": { "type": "integer" }, "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ], "x-stainless-const": true }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "arguments": { "type": "string" } } } }, "required": [ "index" ] }, "ChatCompletionMessageToolCalls": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/ChatCompletionMessageToolCall" }, { "$ref": "#/components/schemas/ChatCompletionMessageCustomToolCall" } ], "discriminator": { "propertyName": "type" } } }, "ChatCompletionModeration": { "type": "object", "properties": { "input": { "oneOf": [ { "$ref": "#/components/schemas/ChatCompletionModerationResults" }, { "$ref": "#/components/schemas/ChatCompletionModerationError" } ], "discriminator": { "propertyName": "type" } }, "output": { "oneOf": [ { "$ref": "#/components/schemas/ChatCompletionModerationResults" }, { "$ref": "#/components/schemas/ChatCompletionModerationError" } ], "discriminator": { "propertyName": "type" } } }, "required": [ "input", "output" ] }, "ChatCompletionModerationError": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "error" ], "x-stainless-const": true }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "type", "code", "message" ] }, "ChatCompletionModerationResults": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "moderation_results" ], "x-stainless-const": true }, "model": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ModerationResultBody" } } }, "required": [ "type", "model", "results" ] }, "ChatCompletionNamedToolChoice": { "type": "object", "title": "Function tool choice", "properties": { "type": { "type": "string", "enum": [ "function" ], "x-stainless-const": true }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } }, "required": [ "type", "function" ] }, "ChatCompletionNamedToolChoiceCustom": { "type": "object", "title": "Custom tool choice", "properties": { "type": { "type": "string", "enum": [ "custom" ], "x-stainless-const": true }, "custom": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } }, "required": [ "type", "custom" ] }, "ChatCompletionRequestAssistantMessage": { "type": "object", "title": "Assistant message", "properties": { "content": { "oneOf": [ { "type": "string", "title": "Text content" }, { "type": "array", "title": "Array of content parts", "items": { "$ref": "#/components/schemas/ChatCompletionRequestAssistantMessageContentPart" }, "minItems": 1 } ], "nullable": true }, "refusal": { "type": "string", "nullable": true }, "role": { "type": "string", "enum": [ "assistant" ], "x-stainless-const": true }, "name": { "type": "string" }, "audio": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" } }, "nullable": true }, "tool_calls": { "$ref": "#/components/schemas/ChatCompletionMessageToolCalls" }, "function_call": { "type": "object", "deprecated": true, "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "nullable": true } }, "required": [ "role" ] }, "ChatCompletionRequestAssistantMessageContentPart": { "oneOf": [ { "$ref": "#/components/schemas/ChatCompletionRequestMessageContentPartText" }, { "$ref": "#/components/schemas/ChatCompletionRequestMessageContentPartRefusal" } ], "discriminator": { "propertyName": "type" } }, "ChatCompletionRequestDeveloperMessage": { "type": "object", "title": "Developer message", "properties": { "content": { "oneOf": [ { "type": "string", "title": "Text content" }, { "type": "array", "title": "Array of content parts", "items": { "$ref": "#/components/schemas/ChatCompletionRequestMessageContentPartText" }, "minItems": 1 } ] }, "role": { "type": "string", "enum": [ "developer" ], "x-stainless-const": true }, "name": { "type": "string" } }, "required": [ "content", "role" ] }, "ChatCompletionRequestFunctionMessage": { "type": "object", "title": "Function message", "deprecated": true, "properties": { "role": { "type": "string", "enum": [ "function" ], "x-stainless-const": true }, "content": { "type": "string", "nullable": true }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ] }, "ChatCompletionRequestMessage": { "oneOf": [ { "$ref": "#/components/schemas/ChatCompletionRequestDeveloperMessage" }, { "$ref": "#/components/schemas/ChatCompletionRequestSystemMessage" }, { "$ref": "#/components/schemas/ChatCompletionRequestUserMessage" }, { "$ref": "#/components/schemas/ChatCompletionRequestAssistantMessage" }, { "$ref": "#/components/schemas/ChatCompletionRequestToolMessage" }, { "$ref": "#/components/schemas/ChatCompletionRequestFunctionMessage" } ], "discriminator": { "propertyName": "role" } }, "ChatCompletionRequestMessageContentPartAudio": { "type": "object", "title": "Audio content part", "properties": { "type": { "type": "string", "enum": [ "input_audio" ], "x-stainless-const": true }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ] }, "prompt_cache_breakpoint": { "$ref": "#/components/schemas/PromptCacheBreakpointParam" } }, "required": [ "type", "input_audio" ] }, "ChatCompletionRequestMessageContentPartFile": { "type": "object", "title": "File content part", "properties": { "type": { "type": "string", "enum": [ "file" ], "x-stainless-const": true }, "file": { "type": "object", "properties": { "filename": { "type": "string" }, "file_data": { "type": "string" }, "file_id": { "type": "string" } } }, "prompt_cache_breakpoint": { "$ref": "#/components/schemas/PromptCacheBreakpointParam" } }, "required": [ "type", "file" ] }, "ChatCompletionRequestMessageContentPartImage": { "type": "object", "title": "Image content part", "properties": { "type": { "type": "string", "enum": [ "image_url" ], "x-stainless-const": true }, "image_url": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ], "default": "auto" } }, "required": [ "url" ] }, "prompt_cache_breakpoint": { "$ref": "#/components/schemas/PromptCacheBreakpointParam" } }, "required": [ "type", "image_url" ] }, "ChatCompletionRequestMessageContentPartRefusal": { "type": "object", "title": "Refusal content part", "properties": { "type": { "type": "string", "enum": [ "refusal" ], "x-stainless-const": true }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ] }, "ChatCompletionRequestMessageContentPartText": { "type": "object", "title": "Text content part", "properties": { "type": { "type": "string", "enum": [ "text" ], "x-stainless-const": true }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "$ref": "#/components/schemas/PromptCacheBreakpointParam" } }, "required": [ "type", "text" ] }, "ChatCompletionRequestSystemMessage": { "type": "object", "title": "System message", "properties": { "content": { "oneOf": [ { "type": "string", "title": "Text content" }, { "type": "array", "title": "Array of content parts", "items": { "$ref": "#/components/schemas/ChatCompletionRequestSystemMessageContentPart" }, "minItems": 1 } ] }, "role": { "type": "string", "enum": [ "system" ], "x-stainless-const": true }, "name": { "type": "string" } }, "required": [ "content", "role" ] }, "ChatCompletionRequestSystemMessageContentPart": { "oneOf": [ { "$ref": "#/components/schemas/ChatCompletionRequestMessageContentPartText" } ] }, "ChatCompletionRequestToolMessage": { "type": "object", "title": "Tool message", "properties": { "role": { "type": "string", "enum": [ "tool" ], "x-stainless-const": true }, "content": { "oneOf": [ { "type": "string", "title": "Text content" }, { "type": "array", "title": "Array of content parts", "items": { "$ref": "#/components/schemas/ChatCompletionRequestToolMessageContentPart" }, "minItems": 1 } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ] }, "ChatCompletionRequestToolMessageContentPart": { "oneOf": [ { "$ref": "#/components/schemas/ChatCompletionRequestMessageContentPartText" } ] }, "ChatCompletionRequestUserMessage": { "type": "object", "title": "User message", "properties": { "content": { "oneOf": [ { "type": "string", "title": "Text content" }, { "type": "array", "title": "Array of content parts", "items": { "$ref": "#/components/schemas/ChatCompletionRequestUserMessageContentPart" }, "minItems": 1 } ] }, "role": { "type": "string", "enum": [ "user" ], "x-stainless-const": true }, "name": { "type": "string" } }, "required": [ "content", "role" ] }, "ChatCompletionRequestUserMessageContentPart": { "oneOf": [ { "$ref": "#/components/schemas/ChatCompletionRequestMessageContentPartText" }, { "$ref": "#/components/schemas/ChatCompletionRequestMessageContentPartImage" }, { "$ref": "#/components/schemas/ChatCompletionRequestMessageContentPartAudio" }, { "$ref": "#/components/schemas/ChatCompletionRequestMessageContentPartFile" } ] }, "ChatCompletionResponseMessage": { "type": "object", "properties": { "content": { "type": "string", "nullable": true }, "refusal": { "type": "string", "nullable": true }, "tool_calls": { "$ref": "#/components/schemas/ChatCompletionMessageToolCalls" }, "annotations": { "type": "array", "items": { "type": "object", "required": [ "type", "url_citation" ], "properties": { "type": { "type": "string", "enum": [ "url_citation" ], "x-stainless-const": true }, "url_citation": { "type": "object", "required": [ "end_index", "start_index", "url", "title" ], "properties": { "end_index": { "type": "integer" }, "start_index": { "type": "integer" }, "url": { "type": "string", "format": "uri" }, "title": { "type": "string" } } } } } }, "role": { "type": "string", "enum": [ "assistant" ], "x-stainless-const": true }, "function_call": { "type": "object", "deprecated": true, "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "name", "arguments" ] }, "audio": { "type": "object", "required": [ "id", "expires_at", "data", "transcript" ], "properties": { "id": { "type": "string" }, "expires_at": { "type": "integer", "format": "unixtime" }, "data": { "type": "string" }, "transcript": { "type": "string" } }, "nullable": true } }, "required": [ "role", "content", "refusal" ] }, "ChatCompletionStreamOptions": { "type": "object", "default": null, "properties": { "include_usage": { "type": "boolean", "description": "When `true`, a final chunk before `data: [DONE]` reports token usage for the whole request." } }, "nullable": true }, "ChatCompletionStreamResponseDelta": { "type": "object", "properties": { "content": { "type": "string", "nullable": true }, "function_call": { "deprecated": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } } }, "tool_calls": { "type": "array", "items": { "$ref": "#/components/schemas/ChatCompletionMessageToolCallChunk" } }, "role": { "type": "string", "enum": [ "developer", "system", "user", "assistant", "tool" ] }, "refusal": { "type": "string", "nullable": true } } }, "ChatCompletionTokenLogprob": { "type": "object", "properties": { "token": { "type": "string" }, "logprob": { "type": "number" }, "bytes": { "type": "array", "items": { "type": "integer" }, "nullable": true }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "token": { "type": "string" }, "logprob": { "type": "number" }, "bytes": { "type": "array", "items": { "type": "integer" }, "nullable": true } }, "required": [ "token", "logprob", "bytes" ] } } }, "required": [ "token", "logprob", "bytes", "top_logprobs" ] }, "ChatCompletionTool": { "type": "object", "title": "Function tool", "properties": { "type": { "type": "string", "enum": [ "function" ], "x-stainless-const": true }, "function": { "$ref": "#/components/schemas/FunctionObject" } }, "required": [ "type", "function" ] }, "ChatCompletionToolChoiceOption": { "oneOf": [ { "type": "string", "title": "Tool choice mode", "enum": [ "none", "auto", "required" ] }, { "$ref": "#/components/schemas/ChatCompletionAllowedToolsChoice" }, { "$ref": "#/components/schemas/ChatCompletionNamedToolChoice" }, { "$ref": "#/components/schemas/ChatCompletionNamedToolChoiceCustom" } ] }, "CompletionUsage": { "type": "object", "properties": { "completion_tokens": { "type": "integer", "default": 0, "description": "Generated tokens, including reasoning tokens." }, "prompt_tokens": { "type": "integer", "default": 0, "description": "Input tokens for the request, including cache reads and writes." }, "total_tokens": { "type": "integer", "default": 0, "description": "Sum of `prompt_tokens` and `completion_tokens`." }, "completion_tokens_details": { "type": "object", "properties": { "accepted_prediction_tokens": { "type": "integer", "default": 0 }, "audio_tokens": { "type": "integer", "default": 0 }, "reasoning_tokens": { "type": "integer", "default": 0 }, "rejected_prediction_tokens": { "type": "integer", "default": 0 } } }, "prompt_tokens_details": { "type": "object", "properties": { "audio_tokens": { "type": "integer", "default": 0 }, "cached_tokens": { "type": "integer", "default": 0 }, "cache_write_tokens": { "type": "integer", "default": 0 } } } }, "required": [ "prompt_tokens", "completion_tokens", "total_tokens" ] }, "CreateChatCompletionRequest": { "allOf": [ { "$ref": "#/components/schemas/CreateModelResponseProperties" }, { "type": "object", "properties": { "messages": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/ChatCompletionRequestMessage" }, "description": "The conversation so far, as an array of message objects with `role` and `content`. The leading `system` or `developer` message is applied as the system prompt." }, "model": { "allOf": [ { "$ref": "#/components/schemas/ModelIdsShared" } ], "description": "The model that will process the request, as a `creator/model-name` id from the catalog — for example `perplexity/kimi-k3`. Any cataloged model works with this endpoint." }, "reasoning_effort": { "allOf": [ { "$ref": "#/components/schemas/ReasoningEffort" } ], "description": "How much reasoning the model performs before answering, on models that support it. When omitted, the provider's default for that model applies; defaults vary by provider and model." }, "max_completion_tokens": { "type": "integer", "nullable": true, "description": "Upper bound on generated tokens for this request, including reasoning tokens." }, "response_format": { "oneOf": [ { "$ref": "#/components/schemas/ResponseFormatText" }, { "$ref": "#/components/schemas/ResponseFormatJsonSchema" }, { "$ref": "#/components/schemas/ResponseFormatJsonObject" } ], "discriminator": { "propertyName": "type" }, "description": "Output format. Use type `json_schema` for structured output; schemas always run in strict mode." }, "stream": { "type": "boolean", "nullable": true, "default": false, "description": "When `true`, tokens are sent as server-sent events as they are generated, terminated by `data: [DONE]`." }, "stop": { "allOf": [ { "$ref": "#/components/schemas/StopConfiguration" } ], "description": "Up to 4 sequences at which generation stops." }, "max_tokens": { "type": "integer", "nullable": true, "deprecated": true, "description": "Legacy alias of `max_completion_tokens`." }, "stream_options": { "allOf": [ { "$ref": "#/components/schemas/ChatCompletionStreamOptions" } ], "description": "Streaming options. Only allowed when `stream` is `true`." }, "tools": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/ChatCompletionTool" }, { "$ref": "#/components/schemas/CustomToolChatCompletions" } ] }, "description": "Function tools the model may call. Every tool requires a `description`." }, "tool_choice": { "allOf": [ { "$ref": "#/components/schemas/ChatCompletionToolChoiceOption" } ], "description": "Controls whether the model may call a tool, and which one." }, "parallel_tool_calls": { "allOf": [ { "$ref": "#/components/schemas/ParallelToolCalls" } ], "description": "Whether the model may request more than one tool call in a single turn." } }, "required": [ "model", "messages" ] } ] }, "CreateChatCompletionResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the completion." }, "choices": { "type": "array", "items": { "type": "object", "required": [ "finish_reason", "index", "message", "logprobs" ], "properties": { "finish_reason": { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, "index": { "type": "integer" }, "message": { "$ref": "#/components/schemas/ChatCompletionResponseMessage" }, "logprobs": { "type": "object", "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/ChatCompletionTokenLogprob" }, "nullable": true }, "refusal": { "type": "array", "items": { "$ref": "#/components/schemas/ChatCompletionTokenLogprob" }, "nullable": true } }, "required": [ "content", "refusal" ], "nullable": true } } }, "description": "The completion. Contains exactly one choice." }, "created": { "type": "integer", "format": "unixtime", "description": "Unix timestamp of when the completion was created." }, "model": { "type": "string", "description": "The model id you requested. Billing always uses this model's published rates." }, "service_tier": { "allOf": [ { "$ref": "#/components/schemas/ServiceTier" } ], "description": "The processing tier that served the request." }, "system_fingerprint": { "type": "string", "deprecated": true }, "object": { "type": "string", "enum": [ "chat.completion" ], "x-stainless-const": true, "description": "Always `\"chat.completion\"`." }, "usage": { "allOf": [ { "$ref": "#/components/schemas/CompletionUsage" } ], "description": "Token accounting for the request." }, "moderation": { "anyOf": [ { "$ref": "#/components/schemas/ChatCompletionModeration" } ] } }, "required": [ "choices", "created", "id", "model", "object" ] }, "CreateChatCompletionStreamResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the completion; identical across all chunks of one response." }, "choices": { "type": "array", "items": { "type": "object", "required": [ "delta", "finish_reason", "index" ], "properties": { "delta": { "$ref": "#/components/schemas/ChatCompletionStreamResponseDelta" }, "logprobs": { "type": "object", "nullable": true, "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/ChatCompletionTokenLogprob" }, "nullable": true }, "refusal": { "type": "array", "items": { "$ref": "#/components/schemas/ChatCompletionTokenLogprob" }, "nullable": true } }, "required": [ "content", "refusal" ] }, "finish_reason": { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ], "nullable": true }, "index": { "type": "integer" } } }, "description": "Incremental output. Empty in the final usage chunk when `stream_options.include_usage` is set." }, "created": { "type": "integer", "format": "unixtime", "description": "Unix timestamp of when the completion was created; identical across all chunks." }, "model": { "type": "string", "description": "The model id you requested." }, "service_tier": { "$ref": "#/components/schemas/ServiceTier" }, "system_fingerprint": { "type": "string", "deprecated": true }, "object": { "type": "string", "enum": [ "chat.completion.chunk" ], "x-stainless-const": true, "description": "Always `\"chat.completion.chunk\"`." }, "usage": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/CompletionUsage" } ], "description": "Present only in the final chunk, and only when the request set `stream_options.include_usage`." }, "moderation": { "anyOf": [ { "$ref": "#/components/schemas/ChatCompletionModeration" } ] } }, "required": [ "choices", "created", "id", "model", "object" ] }, "CreateModelResponseProperties": { "allOf": [ { "$ref": "#/components/schemas/ModelResponseProperties" }, { "type": "object", "properties": {} } ] }, "CustomToolChatCompletions": { "type": "object", "title": "Custom tool", "properties": { "type": { "type": "string", "enum": [ "custom" ], "x-stainless-const": true }, "custom": { "type": "object", "title": "Custom tool properties", "properties": { "name": { "type": "string" }, "format": { "oneOf": [ { "type": "object", "title": "Text format", "properties": { "type": { "type": "string", "enum": [ "text" ], "x-stainless-const": true } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "title": "Grammar format", "properties": { "type": { "type": "string", "enum": [ "grammar" ], "x-stainless-const": true }, "grammar": { "type": "object", "title": "Grammar format", "properties": { "definition": { "type": "string" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ] } }, "required": [ "definition", "syntax" ] } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ] } }, "required": [ "type", "custom" ] }, "Error": { "type": "object", "properties": { "code": { "type": "string", "nullable": true, "description": "Always `null`." }, "message": { "type": "string", "description": "Human-readable description of the error." }, "param": { "type": "string", "nullable": true, "description": "The request parameter the error refers to, when applicable." }, "type": { "type": "string", "description": "Error category: `invalid_request_error` for 4xx, `rate_limit_error` for 429, `server_error` for 5xx." } }, "required": [ "type", "message", "param", "code" ] }, "ErrorResponse": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] }, "FunctionObject": { "type": "object", "properties": { "name": { "type": "string" }, "parameters": { "$ref": "#/components/schemas/FunctionParameters" }, "strict": { "type": "boolean", "default": false, "nullable": true } }, "required": [ "name" ] }, "FunctionParameters": { "type": "object", "additionalProperties": true }, "Metadata": { "type": "object", "additionalProperties": { "type": "string" }, "x-oaiTypeLabel": "map", "nullable": true }, "ModelIdsShared": { "type": "string", "description": "A `creator/model-name` id from the Gateway catalog.", "example": "perplexity/kimi-k3" }, "ModelResponseProperties": { "type": "object", "properties": { "metadata": { "allOf": [ { "$ref": "#/components/schemas/Metadata" } ], "description": "Accepted for SDK compatibility; not forwarded to the model." }, "temperature": { "type": "number", "minimum": 0, "maximum": 2, "default": 1, "example": 1, "nullable": true, "description": "Sampling temperature, 0 to 2. Higher values produce more varied output. Adjust this or `top_p`, not both." }, "top_p": { "type": "number", "minimum": 0, "maximum": 1, "default": 1, "example": 1, "nullable": true, "description": "Nucleus-sampling threshold, 0 to 1. Adjust this or `temperature`, not both." }, "user": { "type": "string", "example": "user-1234", "deprecated": true, "description": "Accepted for SDK compatibility; not forwarded to the model." }, "safety_identifier": { "type": "string", "maxLength": 64, "example": "safety-identifier-1234", "nullable": true, "description": "Accepted for SDK compatibility; not forwarded to the model." }, "prompt_cache_key": { "type": "string", "example": "prompt-cache-key-1234", "nullable": true, "description": "Stable key grouping related requests to improve prompt-cache hit rates." }, "service_tier": { "allOf": [ { "$ref": "#/components/schemas/ServiceTier" } ], "description": "Processing tier for the request. `flex` halves token rates on supported models; `auto` and `default` are equivalent." } } }, "ModerationConfigParam": { "properties": { "mode": { "$ref": "#/components/schemas/ModerationMode" } }, "type": "object", "required": [ "mode" ] }, "ModerationInputType": { "type": "string", "enum": [ "text", "image" ] }, "ModerationMode": { "type": "string", "enum": [ "score", "block" ] }, "ModerationParam": { "properties": { "model": { "type": "string" }, "policy": { "anyOf": [ { "$ref": "#/components/schemas/ModerationPolicyParam" } ] } }, "type": "object", "required": [ "model" ] }, "ModerationPolicyParam": { "properties": { "input": { "anyOf": [ { "$ref": "#/components/schemas/ModerationConfigParam" } ] }, "output": { "anyOf": [ { "$ref": "#/components/schemas/ModerationConfigParam" } ] } }, "type": "object" }, "ModerationResultBody": { "properties": { "type": { "type": "string", "enum": [ "moderation_result" ], "default": "moderation_result", "x-stainless-const": true }, "model": { "type": "string" }, "flagged": { "type": "boolean" }, "categories": { "additionalProperties": { "type": "boolean" }, "type": "object", "x-oaiTypeLabel": "map" }, "category_scores": { "additionalProperties": { "type": "number" }, "type": "object", "x-oaiTypeLabel": "map" }, "category_applied_input_types": { "additionalProperties": { "items": { "$ref": "#/components/schemas/ModerationInputType" }, "type": "array" }, "type": "object", "x-oaiTypeLabel": "map" } }, "type": "object", "required": [ "type", "model", "flagged", "categories", "category_scores", "category_applied_input_types" ], "title": "Moderation result" }, "ParallelToolCalls": { "type": "boolean", "default": true }, "PredictionContent": { "type": "object", "title": "Static Content", "required": [ "type", "content" ], "properties": { "type": { "type": "string", "enum": [ "content" ], "x-stainless-const": true }, "content": { "oneOf": [ { "type": "string", "title": "Text content" }, { "type": "array", "title": "Array of content parts", "items": { "$ref": "#/components/schemas/ChatCompletionRequestMessageContentPartText" }, "minItems": 1 } ] } } }, "PromptCacheBreakpointParam": { "properties": { "mode": { "type": "string", "enum": [ "explicit" ], "default": "explicit", "x-stainless-const": true } }, "type": "object", "required": [ "mode" ], "title": "Prompt cache breakpoint" }, "PromptCacheModeEnum": { "type": "string", "enum": [ "implicit", "explicit" ] }, "PromptCacheOptionsParam": { "properties": { "ttl": { "$ref": "#/components/schemas/PromptCacheTTLEnum" }, "mode": { "$ref": "#/components/schemas/PromptCacheModeEnum" } }, "type": "object", "title": "Prompt cache options" }, "PromptCacheTTLEnum": { "type": "string", "enum": [ "30m" ] }, "ReasoningEffort": { "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ], "nullable": true }, "ResponseFormatJsonObject": { "type": "object", "title": "JSON object", "properties": { "type": { "type": "string", "enum": [ "json_object" ], "x-stainless-const": true } }, "required": [ "type" ] }, "ResponseFormatJsonSchema": { "type": "object", "title": "JSON schema", "properties": { "type": { "type": "string", "enum": [ "json_schema" ], "x-stainless-const": true }, "json_schema": { "type": "object", "title": "JSON schema", "properties": { "name": { "type": "string" }, "schema": { "$ref": "#/components/schemas/ResponseFormatJsonSchemaSchema" }, "strict": { "type": "boolean", "default": false, "nullable": true } }, "required": [ "name" ] } }, "required": [ "type", "json_schema" ] }, "ResponseFormatJsonSchemaSchema": { "type": "object", "title": "JSON schema", "additionalProperties": true }, "ResponseFormatText": { "type": "object", "title": "Text", "properties": { "type": { "type": "string", "enum": [ "text" ], "x-stainless-const": true } }, "required": [ "type" ] }, "ResponseModalities": { "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] }, "nullable": true }, "ServiceTier": { "type": "string", "enum": [ "auto", "default", "flex", "scale", "priority" ], "default": "auto", "nullable": true }, "StopConfiguration": { "default": null, "nullable": true, "oneOf": [ { "type": "string", "default": "<|endoftext|>", "example": "\n", "nullable": true }, { "type": "array", "minItems": 1, "maxItems": 4, "items": { "type": "string", "example": "[\"\\n\"]" } } ] }, "Verbosity": { "type": "string", "enum": [ "low", "medium", "high" ], "default": "medium", "nullable": true }, "VoiceIdsOrCustomVoice": { "title": "Voice", "anyOf": [ { "$ref": "#/components/schemas/VoiceIdsShared" }, { "type": "object", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "example": "voice_1234" } } } ] }, "VoiceIdsShared": { "example": "ash", "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "alloy", "ash", "ballad", "coral", "echo", "sage", "shimmer", "verse", "marin", "cedar" ] } ] }, "WebSearchContextSize": { "type": "string", "enum": [ "low", "medium", "high" ], "default": "medium" }, "WebSearchLocation": { "type": "object", "title": "Web search location", "properties": { "country": { "type": "string" }, "region": { "type": "string" }, "city": { "type": "string" }, "timezone": { "type": "string" } } }, "Model": { "type": "object", "properties": { "id": { "type": "string", "description": "Public model slug, e.g. `perplexity/kimi-k3`.", "x-order": 1 }, "object": { "type": "string", "description": "Always `model`.", "x-order": 2 }, "created": { "type": "integer", "format": "int64", "x-order": 3 }, "owned_by": { "type": "string", "description": "Provider prefix of the slug, e.g. `perplexity`.", "x-order": 4 }, "pricing": { "$ref": "#/components/schemas/ModelPricing" } }, "required": [ "id", "object", "created", "owned_by", "pricing" ] }, "ModelList": { "type": "object", "properties": { "object": { "type": "string", "description": "Always `list`.", "x-order": 1 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Model" }, "x-order": 2 } }, "required": [ "object", "data" ] }, "ModelPricing": { "type": "object", "description": "Base token prices in USD per 1M tokens. Every field is a price; cache_read is the effective cached-input price.", "properties": { "input": { "type": "number", "format": "double", "x-order": 1 }, "output": { "type": "number", "format": "double", "x-order": 2 }, "cache_write": { "type": "number", "format": "double", "x-order": 3 }, "cache_read": { "type": "number", "format": "double", "x-order": 4 }, "unit": { "type": "string", "enum": [ "usd_per_1m_tokens" ], "x-order": 5 } }, "required": [ "input", "output", "unit" ] } }, "securitySchemes": { "HTTPBearer": { "type": "http", "scheme": "bearer", "description": "Your Perplexity API key." } } } }