Responses

Create Response

Create a model response.

post/v3/responses

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

Model identifier, e.g. 'openai/gpt-4o'

instructionsstring nullable

System/developer instructions prepended to input. Not carried over when using previous_response_id.

previous_response_idstring nullable

ID of a prior response to continue a multi-turn conversation. The provider manages conversation state server-side.

streamboolean nullable

Whether to stream the response via server-sent events.

toolsobject[] nullable

List of tools the model may call (function, web_search, file_search, etc.).

temperaturenumber nullable

top_pnumber nullable

max_output_tokensinteger nullable

reasoningobject nullable

Reasoning configuration, e.g. {'effort': 'low'|'medium'|'high'}.

truncation'auto' | 'disabled' nullable

How to handle context that exceeds the model's context window.

storeboolean nullable

Whether the provider should store the response server-side for later retrieval.

metadataobject nullable

Up to 16 key-value pairs for tagging.

userstring nullable

Stable end-user identifier for abuse detection.

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.

parallel_tool_callsboolean nullable

textobject nullable

Text output configuration, e.g. {'format': {'type': 'json_schema', ...}}.

includestring[] nullable

Additional output data to include, e.g. 'file_search_call.results'.

backgroundboolean nullable

Whether to run the model response in the background.

Processing tier, billed at that tier's rates (e.g. 'ultrafast' on openai/gpt-6.1-sol and openai/gpt-6-astra). A model that has no rates for the requested priority or ultrafast tier runs on the default tier; the response's service_tier reports the tier that ran.

Example request

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

Response

Successful Response

costnumber nullable

providerstring nullable

idstring required

object'response'

created_atinteger required

modelstring required

statusstring required

instructionsstring nullable

previous_response_idstring nullable

errorobject nullable