Chat

Chat Completions

OpenAI-compatible chat completions endpoint (v3).

post/v3/chat/completions

Request

Base URL
https://api.edenai.run
Auth
HTTP bearer

Request body

tagsunknown

fallbacksstring[] 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_idstring 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_candidatesstring[] 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_hooksobject[] 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_hooksobject[] 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': {...}}}]

modelstring required

The name of the LLM model to use.

ninteger nullable

The number of completions to generate for each prompt. Defaults to 1.

The reasoning effort level for the LLM model.

metadataobject nullable

Object of metadata associated with the chat request. Can be used to provide additional context or tracking information.

frequency_penaltynumber nullable

Penalty for repeated tokens in the output.

logit_biasobject nullable

Logit bias to influence token generation.

logprobsboolean nullable

Whether to include log probabilities of tokens in the output. Defaults to False.

top_logprobsinteger nullable

Number of top log probabilities to return with each token. An integer between 0 and 20.

max_tokensinteger nullable

The maximum number of tokens to generate in the chat completion

max_completion_tokensinteger nullable

An upper bound for the number of tokens that can be generated for a completion, including visible output tokens and reasoning tokens.

modalitiesstring[] nullable

List of supported input/output modalities for the chat.

predictionobject nullable

field for storing prediction-related information.

audioobject nullable

dictionary for audio-related parameters or metadata.

presence_penaltynumber nullable

Penalty for new tokens based on their presence in the text so far.

response_formatobject nullable

Specify the desired response format for the completion.

seedinteger 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

streamboolean nullable

Whether to stream the response in real-time. Defaults to False.

stream_optionsobject nullable

Options for streaming responses, such as chunk size or format.

temperaturenumber nullable

Sampling temperature for controlling randomness in output.

top_pnumber nullable

Nucleus sampling parameter for controlling diversity in output. Defaults to 1.0.

toolsobject[] nullable

List of tools that can be used by the model to assist in generating responses.

parallel_tool_callsboolean nullable

Whether to allow parallel tool calls in the completion.

userstring nullable

User identifier for tracking or personalization purposes.

functionsobject[] nullable

List of functions that can be called by the model to assist in generating responses.

thinkingobject nullable

Parameters related to the model's reasoning or thinking process.

web_search_optionsobject 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_keystring 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.

extra_bodyobject nullable

Additional parameters to pass in the request body to the provider API.

extra_headersobject nullable

Additional HTTP headers to pass to the provider API.

Example request

{
  "tags": {
    "client": "acme",
    "project": "invoices"
  }
}

Response

Successful Response

idstring required

Unique identifier for the chat completion.

object'chat.completion'

Object type. Always 'chat.completion' for this endpoint.

createdinteger required

Unix timestamp (seconds) when the completion was created.

modelstring required

Model that produced the completion.

system_fingerprintstring nullable

Backend configuration fingerprint that produced the response.

service_tierstring nullable

Service tier that processed the request.

Changes

No recorded changes to this operation across all 1 revision of this API.