---
title: "Chat Completions"
method: POST
path: "/v3/chat/completions"
tags: ["Chat"]
---

# Chat Completions

`POST /v3/chat/completions`

## Request

- Base URL: `https://api.edenai.run`
- URL: `https://api.edenai.run/v3/chat/completions`
- Auth: HTTP bearer

OpenAI-compatible chat completions endpoint (v3).

## Request body

- LlmCompletionBody
  - `tags` unknown
  - `routing` ProviderRoutingPreferences: How to choose between SELLERS of one model — and, with ``@edenai``, how far to trade quality for cost when the platform chooses the model. ``order``, ``allowed_providers``, ``ignored_providers`` and ``max_price`` shape WHICH sellers and in what order; ``sort`` ranks the rest. The seller fields are 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; ``quality_cost`` below is the one field here that speaks to it.
    - `sort` 'cost' | 'speed' | 'latency' | 'exact', nullable: 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` boolean, nullable: 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` or an `order` also takes priority over cache affinity.
    - `allow_fallbacks` boolean, nullable: Whether other providers of the same model may be tried when the chosen one fails. On by default. 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.
    - `quality_cost` integer, nullable: Only with model='@edenai': how far to trade answer quality for cost when the platform chooses the MODEL. 0 asks for the best model for the request, 10 for the cheapest model that can still handle it, values in between blend the two; omit it to leave the choice to the platform (quality first). This is the one `routing` field that steers the model rather than the provider — `sort` never changes which model is chosen.
    - `allowed_providers` string[], nullable: 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.
    - `zero_data_retention` boolean, nullable: Serve this request only from providers that keep no prompts or outputs, and save neither its content nor its response. Applies to every model in the request, including a concrete 'provider/model' and your `fallbacks`: one that is not zero data retention fails the request. It can only add the restriction. When your organization requires zero data retention, `false` does not lift it.
    - `ignored_providers` string[], nullable: Never route to these providers, e.g. ['deepinfra']. The mirror of `allowed_providers`: an entry that does not sell the requested model is inert, and if the list removes every seller the request fails rather than falling back to one you excluded. Case-insensitive. A provider named in both lists is a validation error. A concrete 'provider/model' you named in `fallbacks` is your own choice and is kept.
    - `order` string[], nullable: Providers to try first, in this order, e.g. ['azure', 'openai']. They become the head of the fallback chain; the remaining providers of the model follow, ranked by `sort` (or load-balanced on price when no `sort` is given). An entry that does not sell the model is inert. A provider our health data marks as down is moved to the end of the chain whatever its position here. Naming an `order` turns cache affinity off, as naming a `sort` does. Case-insensitive.
    - `max_price` MaxPrice: A price ceiling in USD per MILLION tokens, one bar per direction, either one optional. Unknown keys are refused: a typo on one side (``ouput``) must not silently remove that bar.
      - `input` number, nullable: Highest input rate accepted, in USD per million tokens.
      - `output` number, nullable: Highest output rate accepted, in USD per million tokens.
  - `fallbacks` string[], nullable: 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` string, nullable: 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, and read from the headers coding agents already send (`x-claude-code-session-id`, `x-session-affinity`, `session-id`, `session_id`, and `x-client-request-id` from pi and Codex); the body field wins if both are sent. Without one, a conversation is recognised from its opening messages instead.
  - `router_candidates` string[], nullable: 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 is a bare model name (e.g. 'gpt-5.5' — the winner's provider is then picked like any provider-less request) or a 'provider/model' id (e.g. 'openai/gpt-5-nano' — the winner is served by that exact provider). Entries the router cannot rank are skipped and listed under `edenai_metadata.routing.auto.dropped`; entries naming a model already in the list collapse into its earliest spelling, which decides how the winner is returned. The request fails only when no entry is left. If not provided, the router chooses from a default pool of eligible catalog models. At most 64 entries of up to 128 characters each.
  - `pre_hooks` object[], nullable: 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` object[], nullable: 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` string, required: The name of the LLM model to use.
  - `messages` Message[], required: The messages to send to the LLM model.
    - `role` 'user' | 'assistant' | 'system' | 'tool' | 'developer' | 'function', required: The role of the message sender (e.g., 'user', 'assistant').
    - `content` union: The content of the message: a string, or a list of content parts (text, image_url, input_audio, file, refusal).
      - string
      - union[]
        - union
          - MessageTextContent
            - `cache_control` CacheControl: 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.
              - …
            - `prompt_cache_breakpoint` PromptCacheBreakpoint: 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.
              - …
            - `type` 'text', required
            - `text` string, required: The text content of the message.
          - MessageImageContent
            - `cache_control` CacheControl: 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.
              - …
            - `prompt_cache_breakpoint` PromptCacheBreakpoint: 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.
              - …
            - `type` 'image_url', required
            - `image_url` MessageImageUrl, required
              - …
          - MessageAudioContent
            - `cache_control` CacheControl: 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.
              - …
            - `prompt_cache_breakpoint` PromptCacheBreakpoint: 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.
              - …
            - `type` 'input_audio', required
            - `input_audio` MessageAudioInput, required
              - …
          - MessageFileContent
            - `cache_control` CacheControl: 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.
              - …
            - `prompt_cache_breakpoint` PromptCacheBreakpoint: 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.
              - …
            - `type` 'file', required
            - `file` union, required
              - …
          - MessageRefusalContent
            - `cache_control` CacheControl: 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.
              - …
            - `prompt_cache_breakpoint` PromptCacheBreakpoint: 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.
              - …
            - `type` 'refusal', required
            - `refusal` string, required: The refusal message generated by the model.
    - `cache_control` CacheControl: 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.
      - `type` 'ephemeral', required: Cache type. Currently only 'ephemeral' is supported.
      - `ttl` string, nullable: Optional cache time-to-live, e.g. '3600s'. Provider-dependent.
  - `n` integer, nullable: The number of completions to generate for each prompt. Defaults to 1.
  - `reasoning_effort` 'minimal' | 'low' | 'medium' | 'high' | 'max' | 'xhigh' | 'disable' | 'none', nullable: The reasoning effort level for the LLM model.
  - `metadata` object, nullable: Object of metadata associated with the chat request. Can be used to provide additional context or tracking information.
  - `frequency_penalty` number, nullable: Penalty for repeated tokens in the output.
  - `logit_bias` object, nullable: Logit bias to influence token generation.
  - `logprobs` boolean, nullable: Whether to include log probabilities of tokens in the output. Defaults to False.
  - `top_logprobs` integer, nullable: Number of top log probabilities to return with each token. An integer between 0 and 20.
  - `max_tokens` integer, nullable: The maximum number of tokens to generate in the chat completion
  - `max_completion_tokens` integer, nullable: An upper bound for the number of tokens that can be generated for a completion, including visible output tokens and reasoning tokens.
  - `modalities` string[], nullable: List of supported input/output modalities for the chat.
  - `prediction` object, nullable: field for storing prediction-related information.
  - `audio` object, nullable: dictionary for audio-related parameters or metadata.
  - `presence_penalty` number, nullable: Penalty for new tokens based on their presence in the text so far.
  - `response_format` object, nullable: Specify the desired response format for the completion.
  - `seed` integer, nullable: Seed for random number generation.
  - `service_tier` 'auto' | 'default' | 'flex' | 'scale' | 'priority', nullable: '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` union: Stop sequence(s) that end generation: a single string or a list of up to 4 strings.
    - string
    - string[]
  - `stream` boolean, nullable: Whether to stream the response in real-time. Defaults to False.
  - `stream_options` object, nullable: Options for streaming responses, such as chunk size or format.
  - `temperature` number, nullable: Sampling temperature for controlling randomness in output.
  - `top_p` number, nullable: Nucleus sampling parameter for controlling diversity in output. Defaults to 1.0.
  - `tools` object[], nullable: List of tools that can be used by the model to assist in generating responses.
  - `tool_choice` union: Specify how tools should be used. Can be 'auto', 'required', 'none', or an object to force a specific tool.
    - string
    - object
  - `parallel_tool_calls` boolean, nullable: Whether to allow parallel tool calls in the completion.
  - `user` string, nullable: User identifier for tracking or personalization purposes.
  - `function_call` union: Controls function calling (legacy). The string 'none' or 'auto', or an object forcing a specific function, e.g. {'name': 'my_function'}.
    - 'none' | 'auto'
    - object
  - `functions` object[], nullable: List of functions that can be called by the model to assist in generating responses.
  - `thinking` object, nullable: Parameters related to the model's reasoning or thinking process.
  - `web_search_options` object, nullable: Options for web search integration. Example: json web_search_options={ "search_context_size": "medium" # Options: "low", "medium", "high" }
  - `verbosity` 'low' | 'medium' | 'high', nullable: Hint the model to be more or less expansive in its replies. Values: "low", "medium", "high". low (gpt5 models)
  - `prompt_cache_key` string, nullable: 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 session header is given.
  - `prompt_cache_retention` union: 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.
    - 'in_memory' | '24h'
    - string
  - `prompt_cache_options` PromptCacheOptions: 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.
    - `mode` union: "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.
      - 'implicit' | 'explicit'
      - string
    - `ttl` union: 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.
      - '30m'
      - string
  - `extra_body` object, nullable: Additional parameters to pass in the request body to the provider API.
  - `image_config` GeminiImageConfig: 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.
    - `aspect_ratio` string, nullable: 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` string, nullable: Output resolution. Examples: '1K', '2K', '4K'. '512' is valid on Gemini 3.1 Flash Image only.
  - `extra_headers` object, nullable: Additional HTTP headers to pass to the provider API.

## Response `200`

Successful Response

- ChatCompletionResponse: Response body for POST /chat/completions (non-streaming).
  - `id` string, required: Unique identifier for the chat completion.
  - `object` 'chat.completion': Object type. Always 'chat.completion' for this endpoint.
  - `created` integer, required: Unix timestamp (seconds) when the completion was created.
  - `model` string, required: Model that produced the completion.
  - `choices` ChatCompletionChoice[], required: List of completion choices generated for the request.
    - `index` integer, required: Position of the choice in the list.
    - `message` ChatCompletionMessage, required: Message returned in a chat completion choice.
      - `role` 'assistant': Role of the message author.
      - `content` string, nullable: Content of the message.
      - `tool_calls` object[], nullable: Tool calls produced by the model, if any.
      - `refusal` string, nullable: Refusal message from the model, if any.
      - `reasoning_content` string, nullable: Reasoning trace from the model, when supported by the provider.
    - `finish_reason` 'stop' | 'length' | 'tool_calls' | 'content_filter' | 'function_call', nullable: Reason the model stopped generating tokens.
    - `logprobs` object, nullable: Log probability information for the choice, if requested.
  - `usage` ChatCompletionUsage: Token usage block returned by the OpenAI-compatible chat completion API.
    - `prompt_tokens` integer, required: Tokens in the prompt.
    - `completion_tokens` integer, required: Tokens in the generated completion.
    - `total_tokens` integer, required: Total tokens consumed by the request.
    - `prompt_tokens_details` object, nullable: Breakdown of prompt tokens (e.g. cached_tokens, audio_tokens).
    - `completion_tokens_details` object, nullable: Breakdown of completion tokens (e.g. reasoning_tokens).
  - `system_fingerprint` string, nullable: Backend configuration fingerprint that produced the response.
  - `service_tier` string, nullable: Service tier that processed the request.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/edenai/apis/eden-ai-api-v3.md) - [All operations](https://skmtc.dev/edenai/apis/eden-ai-api-v3/llms.txt) - [OpenAPI document](https://skmtc.dev/edenai/apis/eden-ai-api-v3/revisions/20ddfd49a3f4?raw)