> ## Documentation Index > Fetch the complete documentation index at: https://edenai-integrations-nanobot-kilocode.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Chat Completions > OpenAI-compatible chat completions endpoint (v3). ## OpenAPI ````yaml https://api.edenai.run/v3/docs/openapi.json post /v3/chat/completions openapi: 3.1.0 info: title: Eden AI API V3 version: 3.0.0 servers: - url: https://api.edenai.run description: Production server security: [] paths: /v3/chat/completions: post: tags: - Chat summary: Chat Completions description: OpenAI-compatible chat completions endpoint (v3). operationId: chat_completions_v3_chat_completions_post requestBody: content: application/json: schema: $ref: '#/components/schemas/LlmCompletionBody' required: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ChatCompletionResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - AuthBearer: [] components: schemas: LlmCompletionBody: properties: routing: anyOf: - $ref: '#/components/schemas/ProviderRoutingPreferences' - type: 'null' description: >- How to pick between the providers that serve the requested model. Applies only when `model` is a model name with no provider prefix (e.g. 'gpt-5.5'); ignored for a concrete 'provider/model' id, which already names its provider. This does not choose the model — for that see `router_candidates` with model='@edenai'. fallbacks: anyOf: - items: type: string type: array maxItems: 3 - type: 'null' title: Fallbacks description: >- List of fallback model IDs to try if the primary model fails. Models are tried in order. Example: ['anthropic/claude-3-opus', 'openai/gpt-4o'] session_id: anyOf: - type: string maxLength: 256 - type: 'null' title: Session Id description: >- Identifies a conversation, so its requests keep reaching the provider that holds its prompt cache. Any stable string you choose — a thread id, a ticket number, an agent run. Also accepted as the `x-session-id` header, for clients that cannot add body fields; the body field wins if both are sent. Without one, a conversation is recognised from its opening messages instead. router_candidates: anyOf: - items: type: string type: array - type: 'null' title: Router Candidates description: >- Models the '@edenai' router may choose BETWEEN — it picks the model, whereas `routing` picks the provider for a model you already named. Used only when model='@edenai'. Each entry should be 'provider/model', e.g. ['openai/gpt-4o', 'anthropic/claude-3-5-sonnet-20241022']. If not provided, defaults to all available models. pre_hooks: anyOf: - items: additionalProperties: true type: object type: array - type: 'null' title: Pre Hooks description: >- List of hooks to run before the LLM provider call. Each entry must have an 'action' key and optional 'params'. Example: [{'action': 'pdf_text_extract', 'params': {'method': 'default'}}] post_hooks: anyOf: - items: additionalProperties: true type: object type: array - type: 'null' title: Post Hooks description: >- List of hooks to run after the LLM provider call. Each entry must have an 'action' key and optional 'params'. Example: [{'action': 'json_heal', 'params': {'json_schema': {...}}}] model: type: string title: Model description: The name of the LLM model to use. messages: items: $ref: '#/components/schemas/Message' type: array title: Messages description: The messages to send to the LLM model. 'n': anyOf: - type: integer minimum: 1 - type: 'null' title: 'N' description: >- The number of completions to generate for each prompt. Defaults to 1. default: 1 reasoning_effort: anyOf: - type: string enum: - minimal - low - medium - high - max - xhigh - disable - none - type: 'null' title: Reasoning Effort description: The reasoning effort level for the LLM model. metadata: anyOf: - additionalProperties: true type: object - type: 'null' title: Metadata description: >- Object of metadata associated with the chat request. Can be used to provide additional context or tracking information. frequency_penalty: anyOf: - type: number maximum: 2 minimum: -2 - type: 'null' title: Frequency Penalty description: Penalty for repeated tokens in the output. logit_bias: anyOf: - additionalProperties: type: number type: object - type: 'null' title: Logit Bias description: Logit bias to influence token generation. logprobs: anyOf: - type: boolean - type: 'null' title: Logprobs description: >- Whether to include log probabilities of tokens in the output. Defaults to False. default: false top_logprobs: anyOf: - type: integer maximum: 20 minimum: 0 - type: 'null' title: Top Logprobs description: >- Number of top log probabilities to return with each token. An integer between 0 and 20. max_tokens: anyOf: - type: integer minimum: 1 - type: 'null' title: Max Tokens description: The maximum number of tokens to generate in the chat completion max_completion_tokens: anyOf: - type: integer minimum: 1 - type: 'null' title: Max Completion Tokens description: >- An upper bound for the number of tokens that can be generated for a completion, including visible output tokens and reasoning tokens. modalities: anyOf: - items: type: string type: array - type: 'null' title: Modalities description: List of supported input/output modalities for the chat. prediction: anyOf: - additionalProperties: true type: object - type: 'null' title: Prediction description: field for storing prediction-related information. audio: anyOf: - additionalProperties: true type: object - type: 'null' title: Audio description: dictionary for audio-related parameters or metadata. presence_penalty: anyOf: - type: number maximum: 2 minimum: -2 - type: 'null' title: Presence Penalty description: Penalty for new tokens based on their presence in the text so far. response_format: anyOf: - additionalProperties: true type: object - type: 'null' title: Response Format description: Specify the desired response format for the completion. seed: anyOf: - type: integer - type: 'null' title: Seed description: Seed for random number generation. service_tier: anyOf: - type: string enum: - auto - default - flex - scale - priority - type: 'null' title: Service Tier description: >- 'auto': Automatically select appropriate tier 'default': Use the default service tier 'flex': 50% cheaper processing with increased latency (OpenAI o3/o4-mini) 'scale' / 'priority': OpenAI scale and priority processing tiers stop: anyOf: - type: string - items: type: string type: array - type: 'null' title: Stop description: >- Stop sequence(s) that end generation: a single string or a list of up to 4 strings. stream: anyOf: - type: boolean - type: 'null' title: Stream description: Whether to stream the response in real-time. Defaults to False. default: false stream_options: anyOf: - additionalProperties: true type: object - type: 'null' title: Stream Options description: Options for streaming responses, such as chunk size or format. temperature: anyOf: - type: number maximum: 2 minimum: 0 - type: 'null' title: Temperature description: Sampling temperature for controlling randomness in output. top_p: anyOf: - type: number maximum: 1 minimum: 0 - type: 'null' title: Top P description: >- Nucleus sampling parameter for controlling diversity in output. Defaults to 1.0. default: 1 tools: anyOf: - items: additionalProperties: true type: object type: array - type: 'null' title: Tools description: >- List of tools that can be used by the model to assist in generating responses. tool_choice: anyOf: - type: string - additionalProperties: true type: object - type: 'null' title: Tool Choice description: >- Specify how tools should be used. Can be 'auto', 'required', 'none', or an object to force a specific tool. parallel_tool_calls: anyOf: - type: boolean - type: 'null' title: Parallel Tool Calls description: Whether to allow parallel tool calls in the completion. user: anyOf: - type: string - type: 'null' title: User description: User identifier for tracking or personalization purposes. function_call: anyOf: - type: string enum: - none - auto - additionalProperties: true type: object - type: 'null' title: Function Call description: >- Controls function calling (legacy). The string 'none' or 'auto', or an object forcing a specific function, e.g. {'name': 'my_function'}. functions: anyOf: - items: additionalProperties: true type: object type: array - type: 'null' title: Functions description: >- List of functions that can be called by the model to assist in generating responses. thinking: anyOf: - additionalProperties: true type: object - type: 'null' title: Thinking description: Parameters related to the model's reasoning or thinking process. web_search_options: anyOf: - additionalProperties: true type: object - type: 'null' title: Web Search Options description: >- Options for web search integration. Example: json web_search_options={ "search_context_size": "medium" # Options: "low", "medium", "high" } verbosity: anyOf: - type: string enum: - low - medium - high - type: 'null' title: Verbosity description: >- Hint the model to be more or less expansive in its replies. Values: "low", "medium", "high". low (gpt5 models) prompt_cache_key: anyOf: - type: string - type: 'null' title: Prompt Cache Key description: >- Prompt-cache routing hint (OpenAI): requests sharing a key and a common prompt prefix are routed to the same cache shard, improving hit rates for high-volume shared prefixes. Forwarded to providers that support it, dropped elsewhere. Also read for provider stickiness when no `session_id` or `x-session-id` is given. prompt_cache_retention: anyOf: - type: string enum: - in_memory - 24h - type: string - type: 'null' title: Prompt Cache Retention description: >- How long the provider retains the prompt cache — OpenAI currently accepts "in_memory" (provider default, typically 5-10 minutes) and "24h" (extended retention, supported on gpt-5.x and gpt-4.1). The known values are advertised in the schema but not enforced: the value is passed through verbatim for the provider to validate, so new provider values work without an Eden AI release. Dropped for providers that don't support it. prompt_cache_options: anyOf: - $ref: '#/components/schemas/PromptCacheOptions' - type: 'null' description: >- Request-level prompt-cache settings (mode and ttl) for OpenAI GPT-5.6 and newer models. Ignored by models that don't support prompt caching. extra_body: anyOf: - additionalProperties: true type: object - type: 'null' title: Extra Body description: >- Additional parameters to pass in the request body to the provider API. image_config: anyOf: - $ref: '#/components/schemas/GeminiImageConfig' - type: 'null' description: >- Image generation configuration for Google Gemini image models (e.g. google/gemini-2.5-flash-image). extra_headers: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Extra Headers description: Additional HTTP headers to pass to the provider API. type: object required: - model - messages title: LlmCompletionBody ChatCompletionResponse: properties: id: type: string title: Id description: Unique identifier for the chat completion. object: type: string const: chat.completion title: Object description: Object type. Always 'chat.completion' for this endpoint. default: chat.completion created: type: integer title: Created description: Unix timestamp (seconds) when the completion was created. model: type: string title: Model description: Model that produced the completion. choices: items: $ref: '#/components/schemas/ChatCompletionChoice' type: array title: Choices description: List of completion choices generated for the request. usage: anyOf: - $ref: '#/components/schemas/ChatCompletionUsage' - type: 'null' description: Token usage statistics for the request. system_fingerprint: anyOf: - type: string - type: 'null' title: System Fingerprint description: Backend configuration fingerprint that produced the response. service_tier: anyOf: - type: string - type: 'null' title: Service Tier description: Service tier that processed the request. additionalProperties: true type: object required: - id - created - model - choices title: ChatCompletionResponse description: Response body for POST /chat/completions (non-streaming). HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError ProviderRoutingPreferences: properties: sort: anyOf: - type: string enum: - cost - speed - latency - exact - type: 'null' title: Sort description: >- What to optimise for when several providers serve the requested model. 'cost' (default) picks the cheapest for this request's shape; 'speed' the highest tokens/second; 'latency' the fastest to first token; 'exact' the most reliable at producing well-formed tool calls / structured output. Health is always a filter first — no mode will route you to a failing provider. Can also be written as a model suffix, e.g. 'gpt-5.5:speed'. sticky: anyOf: - type: boolean - type: 'null' title: Sticky description: >- Keep a conversation on the provider holding its prompt cache. On by default, and only ever active for models whose providers discount cache reads. Set false to route every request independently on price instead. Naming an explicit `sort` also takes priority over cache affinity. allow_fallbacks: type: boolean title: Allow Fallbacks description: >- Whether other providers of the same model may be tried when the chosen one fails. Set false to pin the request to the single best provider: it then fails rather than silently moving to another seller. useful when a cache-warm prompt would cold-miss elsewhere. This governs PROVIDERS of the requested model only; models you list in `fallbacks` are your own choice and are always kept. default: true allowed_providers: anyOf: - items: type: string type: array - type: 'null' title: Allowed Providers description: >- Restrict routing to these providers, e.g. ['openai', 'anthropic']. Only providers that serve the requested model are considered, so an entry that does not sell it is simply inert. If none of them do, the request fails rather than falling back to a provider you excluded. Case-insensitive. Applies to routed providers only. a concrete 'provider/model' you named in `fallbacks` is your own choice and is kept. type: object title: ProviderRoutingPreferences description: >- How to choose between SELLERS of one model — not which model to use. Only meaningful when `model` is a canonical name (`gpt-5.5`) rather than a concrete `provider/model` — with a concrete id there is nothing to choose between. For choosing the MODEL itself see ``router_candidates`` and ``model="@edenai"``, which is a different router. Message: properties: role: type: string enum: - user - assistant - system - tool - developer - function title: Role description: The role of the message sender (e.g., 'user', 'assistant'). content: anyOf: - type: string - items: anyOf: - $ref: '#/components/schemas/MessageTextContent' - $ref: '#/components/schemas/MessageImageContent' - $ref: '#/components/schemas/MessageAudioContent' - $ref: '#/components/schemas/MessageFileContent' - $ref: '#/components/schemas/MessageRefusalContent' type: array - type: 'null' title: Content description: >- The content of the message: a string, or a list of content parts (text, image_url, input_audio, file, refusal). cache_control: anyOf: - $ref: '#/components/schemas/CacheControl' - type: 'null' description: >- Optional prompt-cache marker. When set, this message becomes a cache boundary: prefix content is stored and reused on subsequent requests to reduce latency and cost. Silently ignored by providers that don't support prompt caching. additionalProperties: true type: object required: - role title: Message PromptCacheOptions: properties: mode: anyOf: - type: string enum: - implicit - explicit - type: string - type: 'null' title: Mode description: >- "implicit" (default) caches automatically and also honors any prompt_cache_breakpoint you set; "explicit" caches only the blocks you mark with prompt_cache_breakpoint. Known values are advertised in the schema but not enforced. ttl: anyOf: - type: string const: 30m - type: string - type: 'null' title: Ttl description: >- How long to keep the prompt cache, e.g. "30m". Leave unset for the provider default. Known values are advertised in the schema but not enforced. additionalProperties: true type: object title: PromptCacheOptions description: >- Request-level prompt-cache settings (OpenAI GPT-5.6 and newer). Controls how this request's prompt cache behaves — whether caching happens automatically or only on the blocks you mark with ``prompt_cache_breakpoint``, and how long the cache is kept. Ignored by models that don't support prompt caching. GeminiImageConfig: properties: aspect_ratio: anyOf: - type: string - type: 'null' title: Aspect Ratio description: >- Output aspect ratio. Examples: '1:1', '16:9', '9:16', '4:3', '3:4', '21:9'. Allowed set varies by model; see Gemini docs. image_size: anyOf: - type: string - type: 'null' title: Image Size description: >- Output resolution. Examples: '1K', '2K', '4K'. '512' is valid on Gemini 3.1 Flash Image only. additionalProperties: false type: object title: GeminiImageConfig description: >- Image generation config for Gemini image models (google/gemini-2.5-flash-image). Values are passed through to Gemini's generationConfig.imageConfig. Allowed values may vary by model — see https://ai.google.dev/gemini-api/docs/image-generation. ChatCompletionChoice: properties: index: type: integer title: Index description: Position of the choice in the list. message: $ref: '#/components/schemas/ChatCompletionMessage' description: Message produced by the model for this choice. finish_reason: anyOf: - type: string enum: - stop - length - tool_calls - content_filter - function_call - type: 'null' title: Finish Reason description: Reason the model stopped generating tokens. logprobs: anyOf: - additionalProperties: true type: object - type: 'null' title: Logprobs description: Log probability information for the choice, if requested. additionalProperties: true type: object required: - index - message title: ChatCompletionChoice description: A single choice in a chat completion response. ChatCompletionUsage: properties: prompt_tokens: type: integer title: Prompt Tokens description: Tokens in the prompt. completion_tokens: type: integer title: Completion Tokens description: Tokens in the generated completion. total_tokens: type: integer title: Total Tokens description: Total tokens consumed by the request. prompt_tokens_details: anyOf: - additionalProperties: true type: object - type: 'null' title: Prompt Tokens Details description: Breakdown of prompt tokens (e.g. cached_tokens, audio_tokens). completion_tokens_details: anyOf: - additionalProperties: true type: object - type: 'null' title: Completion Tokens Details description: Breakdown of completion tokens (e.g. reasoning_tokens). additionalProperties: true type: object required: - prompt_tokens - completion_tokens - total_tokens title: ChatCompletionUsage description: Token usage block returned by the OpenAI-compatible chat completion API. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError MessageTextContent: properties: cache_control: anyOf: - $ref: '#/components/schemas/CacheControl' - type: 'null' prompt_cache_breakpoint: anyOf: - $ref: '#/components/schemas/PromptCacheBreakpoint' - type: 'null' type: type: string const: text title: Type text: type: string title: Text description: The text content of the message. type: object required: - type - text title: MessageTextContent MessageImageContent: properties: cache_control: anyOf: - $ref: '#/components/schemas/CacheControl' - type: 'null' prompt_cache_breakpoint: anyOf: - $ref: '#/components/schemas/PromptCacheBreakpoint' - type: 'null' type: type: string const: image_url title: Type image_url: $ref: '#/components/schemas/MessageImageUrl' type: object required: - type - image_url title: MessageImageContent MessageAudioContent: properties: cache_control: anyOf: - $ref: '#/components/schemas/CacheControl' - type: 'null' prompt_cache_breakpoint: anyOf: - $ref: '#/components/schemas/PromptCacheBreakpoint' - type: 'null' type: type: string const: input_audio title: Type input_audio: $ref: '#/components/schemas/MessageAudioInput' type: object required: - type - input_audio title: MessageAudioContent MessageFileContent: properties: cache_control: anyOf: - $ref: '#/components/schemas/CacheControl' - type: 'null' prompt_cache_breakpoint: anyOf: - $ref: '#/components/schemas/PromptCacheBreakpoint' - type: 'null' type: type: string const: file title: Type file: anyOf: - $ref: '#/components/schemas/MessageFileUrlInput' - $ref: '#/components/schemas/MessageFileB64Input' title: File type: object required: - type - file title: MessageFileContent MessageRefusalContent: properties: cache_control: anyOf: - $ref: '#/components/schemas/CacheControl' - type: 'null' prompt_cache_breakpoint: anyOf: - $ref: '#/components/schemas/PromptCacheBreakpoint' - type: 'null' type: type: string const: refusal title: Type refusal: type: string title: Refusal description: The refusal message generated by the model. type: object required: - type - refusal title: MessageRefusalContent CacheControl: properties: type: type: string const: ephemeral title: Type description: Cache type. Currently only 'ephemeral' is supported. ttl: anyOf: - type: string - type: 'null' title: Ttl description: Optional cache time-to-live, e.g. '3600s'. Provider-dependent. type: object required: - type title: CacheControl description: |- Prompt-cache marker. Marks a message (or content part) as a cache boundary so that the prefix up to that point is stored and reused on subsequent requests, reducing latency and cost. Only a single contiguous cache-marked block is stored per request, and providers enforce a minimum token count below which caching is silently skipped. Silently ignored by providers that don't support prompt caching. ChatCompletionMessage: properties: role: type: string const: assistant title: Role description: Role of the message author. default: assistant content: anyOf: - type: string - type: 'null' title: Content description: Content of the message. tool_calls: anyOf: - items: additionalProperties: true type: object type: array - type: 'null' title: Tool Calls description: Tool calls produced by the model, if any. refusal: anyOf: - type: string - type: 'null' title: Refusal description: Refusal message from the model, if any. reasoning_content: anyOf: - type: string - type: 'null' title: Reasoning Content description: Reasoning trace from the model, when supported by the provider. additionalProperties: true type: object title: ChatCompletionMessage description: Message returned in a chat completion choice. PromptCacheBreakpoint: properties: mode: anyOf: - type: string const: explicit - type: string - type: 'null' title: Mode description: >- Breakpoint mode. Currently only "explicit" is defined; the known value is advertised in the schema but not enforced, so a new provider value works without an Eden AI release. Leave unset for the provider default. additionalProperties: true type: object title: PromptCacheBreakpoint description: >- Marks the end of a reusable prompt prefix (OpenAI GPT-5.6 and newer). Set it on the last content part of the stable prefix you want cached: the prompt up to and including that part is stored and reused on later requests that share it, reducing latency and cost. Providers enforce a minimum token count below which caching is skipped. Ignored by models that don't support explicit cache breakpoints. MessageImageUrl: properties: url: type: string title: Url type: object required: - url title: MessageImageUrl MessageAudioInput: properties: data: type: string title: Data description: The audio data in base64 format or Http(s) link. format: anyOf: - type: string - type: 'null' title: Format description: The format of the audio file (e.g., 'mp3', 'wav'). type: object required: - data title: MessageAudioInput MessageFileUrlInput: properties: file_id: type: string title: File Id description: >- File identifier: either a UUID from /v3/upload endpoint or an HTTP(S) URL. type: object required: - file_id title: MessageFileUrlInput MessageFileB64Input: properties: file_data: type: string title: File Data description: The file data in base64 format. type: object required: - file_data title: MessageFileB64Input securitySchemes: AuthBearer: type: http scheme: bearer ````