Create Response
curl --request POST \
--url https://api.edenai.run/v3/responses \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "<string>",
"routing": {
"sticky": true,
"allow_fallbacks": true,
"quality_cost": 5,
"allowed_providers": [
"<string>"
]
},
"fallbacks": [
"<string>"
],
"session_id": "<string>",
"router_candidates": [
"<string>"
],
"input": "<string>",
"instructions": "<string>",
"previous_response_id": "<string>",
"stream": false,
"tools": [
{}
],
"tool_choice": "<string>",
"temperature": 1,
"top_p": 0.5,
"max_output_tokens": 2,
"reasoning": {},
"store": true,
"metadata": {},
"user": "<string>",
"prompt_cache_key": "<string>",
"prompt_cache_options": {
"ttl": "30m"
},
"parallel_tool_calls": true,
"text": {},
"include": [
"<string>"
],
"background": true
}
'import requests
url = "https://api.edenai.run/v3/responses"
payload = {
"model": "<string>",
"routing": {
"sticky": True,
"allow_fallbacks": True,
"quality_cost": 5,
"allowed_providers": ["<string>"]
},
"fallbacks": ["<string>"],
"session_id": "<string>",
"router_candidates": ["<string>"],
"input": "<string>",
"instructions": "<string>",
"previous_response_id": "<string>",
"stream": False,
"tools": [{}],
"tool_choice": "<string>",
"temperature": 1,
"top_p": 0.5,
"max_output_tokens": 2,
"reasoning": {},
"store": True,
"metadata": {},
"user": "<string>",
"prompt_cache_key": "<string>",
"prompt_cache_options": { "ttl": "30m" },
"parallel_tool_calls": True,
"text": {},
"include": ["<string>"],
"background": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
model: '<string>',
routing: {
sticky: true,
allow_fallbacks: true,
quality_cost: 5,
allowed_providers: ['<string>']
},
fallbacks: ['<string>'],
session_id: '<string>',
router_candidates: ['<string>'],
input: '<string>',
instructions: '<string>',
previous_response_id: '<string>',
stream: false,
tools: [{}],
tool_choice: '<string>',
temperature: 1,
top_p: 0.5,
max_output_tokens: 2,
reasoning: {},
store: true,
metadata: {},
user: '<string>',
prompt_cache_key: '<string>',
prompt_cache_options: {ttl: '30m'},
parallel_tool_calls: true,
text: {},
include: ['<string>'],
background: true
})
};
fetch('https://api.edenai.run/v3/responses', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.edenai.run/v3/responses",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'model' => '<string>',
'routing' => [
'sticky' => true,
'allow_fallbacks' => true,
'quality_cost' => 5,
'allowed_providers' => [
'<string>'
]
],
'fallbacks' => [
'<string>'
],
'session_id' => '<string>',
'router_candidates' => [
'<string>'
],
'input' => '<string>',
'instructions' => '<string>',
'previous_response_id' => '<string>',
'stream' => false,
'tools' => [
[
]
],
'tool_choice' => '<string>',
'temperature' => 1,
'top_p' => 0.5,
'max_output_tokens' => 2,
'reasoning' => [
],
'store' => true,
'metadata' => [
],
'user' => '<string>',
'prompt_cache_key' => '<string>',
'prompt_cache_options' => [
'ttl' => '30m'
],
'parallel_tool_calls' => true,
'text' => [
],
'include' => [
'<string>'
],
'background' => true
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.edenai.run/v3/responses"
payload := strings.NewReader("{\n \"model\": \"<string>\",\n \"routing\": {\n \"sticky\": true,\n \"allow_fallbacks\": true,\n \"quality_cost\": 5,\n \"allowed_providers\": [\n \"<string>\"\n ]\n },\n \"fallbacks\": [\n \"<string>\"\n ],\n \"session_id\": \"<string>\",\n \"router_candidates\": [\n \"<string>\"\n ],\n \"input\": \"<string>\",\n \"instructions\": \"<string>\",\n \"previous_response_id\": \"<string>\",\n \"stream\": false,\n \"tools\": [\n {}\n ],\n \"tool_choice\": \"<string>\",\n \"temperature\": 1,\n \"top_p\": 0.5,\n \"max_output_tokens\": 2,\n \"reasoning\": {},\n \"store\": true,\n \"metadata\": {},\n \"user\": \"<string>\",\n \"prompt_cache_key\": \"<string>\",\n \"prompt_cache_options\": {\n \"ttl\": \"30m\"\n },\n \"parallel_tool_calls\": true,\n \"text\": {},\n \"include\": [\n \"<string>\"\n ],\n \"background\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.edenai.run/v3/responses")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"model\": \"<string>\",\n \"routing\": {\n \"sticky\": true,\n \"allow_fallbacks\": true,\n \"quality_cost\": 5,\n \"allowed_providers\": [\n \"<string>\"\n ]\n },\n \"fallbacks\": [\n \"<string>\"\n ],\n \"session_id\": \"<string>\",\n \"router_candidates\": [\n \"<string>\"\n ],\n \"input\": \"<string>\",\n \"instructions\": \"<string>\",\n \"previous_response_id\": \"<string>\",\n \"stream\": false,\n \"tools\": [\n {}\n ],\n \"tool_choice\": \"<string>\",\n \"temperature\": 1,\n \"top_p\": 0.5,\n \"max_output_tokens\": 2,\n \"reasoning\": {},\n \"store\": true,\n \"metadata\": {},\n \"user\": \"<string>\",\n \"prompt_cache_key\": \"<string>\",\n \"prompt_cache_options\": {\n \"ttl\": \"30m\"\n },\n \"parallel_tool_calls\": true,\n \"text\": {},\n \"include\": [\n \"<string>\"\n ],\n \"background\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.edenai.run/v3/responses")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"model\": \"<string>\",\n \"routing\": {\n \"sticky\": true,\n \"allow_fallbacks\": true,\n \"quality_cost\": 5,\n \"allowed_providers\": [\n \"<string>\"\n ]\n },\n \"fallbacks\": [\n \"<string>\"\n ],\n \"session_id\": \"<string>\",\n \"router_candidates\": [\n \"<string>\"\n ],\n \"input\": \"<string>\",\n \"instructions\": \"<string>\",\n \"previous_response_id\": \"<string>\",\n \"stream\": false,\n \"tools\": [\n {}\n ],\n \"tool_choice\": \"<string>\",\n \"temperature\": 1,\n \"top_p\": 0.5,\n \"max_output_tokens\": 2,\n \"reasoning\": {},\n \"store\": true,\n \"metadata\": {},\n \"user\": \"<string>\",\n \"prompt_cache_key\": \"<string>\",\n \"prompt_cache_options\": {\n \"ttl\": \"30m\"\n },\n \"parallel_tool_calls\": true,\n \"text\": {},\n \"include\": [\n \"<string>\"\n ],\n \"background\": true\n}"
response = http.request(request)
puts response.read_body{
"id": "<string>",
"created_at": 123,
"model": "<string>",
"status": "<string>",
"output": [
{
"id": "<string>",
"type": "message",
"role": "assistant",
"status": "<string>",
"content": [
{
"type": "output_text",
"text": "<string>",
"annotations": []
}
]
}
],
"cost": 123,
"provider": "<string>",
"object": "response",
"instructions": "<string>",
"previous_response_id": "<string>",
"usage": {
"input_tokens": 123,
"output_tokens": 123,
"total_tokens": 123,
"input_tokens_details": {},
"output_tokens_details": {}
},
"error": {},
"metadata": {}
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}Responses
Create Response
Create a model response.
POST
/
v3
/
responses
Create Response
curl --request POST \
--url https://api.edenai.run/v3/responses \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "<string>",
"routing": {
"sticky": true,
"allow_fallbacks": true,
"quality_cost": 5,
"allowed_providers": [
"<string>"
]
},
"fallbacks": [
"<string>"
],
"session_id": "<string>",
"router_candidates": [
"<string>"
],
"input": "<string>",
"instructions": "<string>",
"previous_response_id": "<string>",
"stream": false,
"tools": [
{}
],
"tool_choice": "<string>",
"temperature": 1,
"top_p": 0.5,
"max_output_tokens": 2,
"reasoning": {},
"store": true,
"metadata": {},
"user": "<string>",
"prompt_cache_key": "<string>",
"prompt_cache_options": {
"ttl": "30m"
},
"parallel_tool_calls": true,
"text": {},
"include": [
"<string>"
],
"background": true
}
'import requests
url = "https://api.edenai.run/v3/responses"
payload = {
"model": "<string>",
"routing": {
"sticky": True,
"allow_fallbacks": True,
"quality_cost": 5,
"allowed_providers": ["<string>"]
},
"fallbacks": ["<string>"],
"session_id": "<string>",
"router_candidates": ["<string>"],
"input": "<string>",
"instructions": "<string>",
"previous_response_id": "<string>",
"stream": False,
"tools": [{}],
"tool_choice": "<string>",
"temperature": 1,
"top_p": 0.5,
"max_output_tokens": 2,
"reasoning": {},
"store": True,
"metadata": {},
"user": "<string>",
"prompt_cache_key": "<string>",
"prompt_cache_options": { "ttl": "30m" },
"parallel_tool_calls": True,
"text": {},
"include": ["<string>"],
"background": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
model: '<string>',
routing: {
sticky: true,
allow_fallbacks: true,
quality_cost: 5,
allowed_providers: ['<string>']
},
fallbacks: ['<string>'],
session_id: '<string>',
router_candidates: ['<string>'],
input: '<string>',
instructions: '<string>',
previous_response_id: '<string>',
stream: false,
tools: [{}],
tool_choice: '<string>',
temperature: 1,
top_p: 0.5,
max_output_tokens: 2,
reasoning: {},
store: true,
metadata: {},
user: '<string>',
prompt_cache_key: '<string>',
prompt_cache_options: {ttl: '30m'},
parallel_tool_calls: true,
text: {},
include: ['<string>'],
background: true
})
};
fetch('https://api.edenai.run/v3/responses', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.edenai.run/v3/responses",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'model' => '<string>',
'routing' => [
'sticky' => true,
'allow_fallbacks' => true,
'quality_cost' => 5,
'allowed_providers' => [
'<string>'
]
],
'fallbacks' => [
'<string>'
],
'session_id' => '<string>',
'router_candidates' => [
'<string>'
],
'input' => '<string>',
'instructions' => '<string>',
'previous_response_id' => '<string>',
'stream' => false,
'tools' => [
[
]
],
'tool_choice' => '<string>',
'temperature' => 1,
'top_p' => 0.5,
'max_output_tokens' => 2,
'reasoning' => [
],
'store' => true,
'metadata' => [
],
'user' => '<string>',
'prompt_cache_key' => '<string>',
'prompt_cache_options' => [
'ttl' => '30m'
],
'parallel_tool_calls' => true,
'text' => [
],
'include' => [
'<string>'
],
'background' => true
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.edenai.run/v3/responses"
payload := strings.NewReader("{\n \"model\": \"<string>\",\n \"routing\": {\n \"sticky\": true,\n \"allow_fallbacks\": true,\n \"quality_cost\": 5,\n \"allowed_providers\": [\n \"<string>\"\n ]\n },\n \"fallbacks\": [\n \"<string>\"\n ],\n \"session_id\": \"<string>\",\n \"router_candidates\": [\n \"<string>\"\n ],\n \"input\": \"<string>\",\n \"instructions\": \"<string>\",\n \"previous_response_id\": \"<string>\",\n \"stream\": false,\n \"tools\": [\n {}\n ],\n \"tool_choice\": \"<string>\",\n \"temperature\": 1,\n \"top_p\": 0.5,\n \"max_output_tokens\": 2,\n \"reasoning\": {},\n \"store\": true,\n \"metadata\": {},\n \"user\": \"<string>\",\n \"prompt_cache_key\": \"<string>\",\n \"prompt_cache_options\": {\n \"ttl\": \"30m\"\n },\n \"parallel_tool_calls\": true,\n \"text\": {},\n \"include\": [\n \"<string>\"\n ],\n \"background\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.edenai.run/v3/responses")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"model\": \"<string>\",\n \"routing\": {\n \"sticky\": true,\n \"allow_fallbacks\": true,\n \"quality_cost\": 5,\n \"allowed_providers\": [\n \"<string>\"\n ]\n },\n \"fallbacks\": [\n \"<string>\"\n ],\n \"session_id\": \"<string>\",\n \"router_candidates\": [\n \"<string>\"\n ],\n \"input\": \"<string>\",\n \"instructions\": \"<string>\",\n \"previous_response_id\": \"<string>\",\n \"stream\": false,\n \"tools\": [\n {}\n ],\n \"tool_choice\": \"<string>\",\n \"temperature\": 1,\n \"top_p\": 0.5,\n \"max_output_tokens\": 2,\n \"reasoning\": {},\n \"store\": true,\n \"metadata\": {},\n \"user\": \"<string>\",\n \"prompt_cache_key\": \"<string>\",\n \"prompt_cache_options\": {\n \"ttl\": \"30m\"\n },\n \"parallel_tool_calls\": true,\n \"text\": {},\n \"include\": [\n \"<string>\"\n ],\n \"background\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.edenai.run/v3/responses")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"model\": \"<string>\",\n \"routing\": {\n \"sticky\": true,\n \"allow_fallbacks\": true,\n \"quality_cost\": 5,\n \"allowed_providers\": [\n \"<string>\"\n ]\n },\n \"fallbacks\": [\n \"<string>\"\n ],\n \"session_id\": \"<string>\",\n \"router_candidates\": [\n \"<string>\"\n ],\n \"input\": \"<string>\",\n \"instructions\": \"<string>\",\n \"previous_response_id\": \"<string>\",\n \"stream\": false,\n \"tools\": [\n {}\n ],\n \"tool_choice\": \"<string>\",\n \"temperature\": 1,\n \"top_p\": 0.5,\n \"max_output_tokens\": 2,\n \"reasoning\": {},\n \"store\": true,\n \"metadata\": {},\n \"user\": \"<string>\",\n \"prompt_cache_key\": \"<string>\",\n \"prompt_cache_options\": {\n \"ttl\": \"30m\"\n },\n \"parallel_tool_calls\": true,\n \"text\": {},\n \"include\": [\n \"<string>\"\n ],\n \"background\": true\n}"
response = http.request(request)
puts response.read_body{
"id": "<string>",
"created_at": 123,
"model": "<string>",
"status": "<string>",
"output": [
{
"id": "<string>",
"type": "message",
"role": "assistant",
"status": "<string>",
"content": [
{
"type": "output_text",
"text": "<string>",
"annotations": []
}
]
}
],
"cost": 123,
"provider": "<string>",
"object": "response",
"instructions": "<string>",
"previous_response_id": "<string>",
"usage": {
"input_tokens": 123,
"output_tokens": 123,
"total_tokens": 123,
"input_tokens_details": {},
"output_tokens_details": {}
},
"error": {},
"metadata": {}
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
application/json
Model identifier, e.g. 'openai/gpt-4o'
How to pick between the providers that serve the requested model. Applies 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. With model='@edenai' the platform chooses the model too: quality_cost steers that choice, and the provider fields apply whenever the chosen model is a provider-less name.
Show child attributes
Show child attributes
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']
Maximum array length:
3Identifies 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.
Maximum string length:
256Models 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.
Maximum array length:
64Maximum string length:
128Text, image, or file inputs to the model. Optional when continuing a conversation via previous_response_id.
System/developer instructions prepended to input. Not carried over when using previous_response_id.
ID of a prior response to continue a multi-turn conversation. The provider manages conversation state server-side.
Whether to stream the response via server-sent events.
List of tools the model may call (function, web_search, file_search, etc.).
Controls which tool is called. 'auto', 'required', 'none', or a specific tool object.
Required range:
0 <= x <= 2Required range:
0 <= x <= 1Required range:
x >= 1Reasoning configuration, e.g. {'effort': 'low'|'medium'|'high'}.
How to handle context that exceeds the model's context window.
Available options:
auto, disabled Whether the provider should store the response server-side for later retrieval.
Up to 16 key-value pairs for tagging.
Stable end-user identifier for abuse detection.
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.
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.
Available options:
in_memory, 24h 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.
Show child attributes
Show child attributes
Text output configuration, e.g. {'format': {'type': 'json_schema', ...}}.
Additional output data to include, e.g. 'file_search_call.results'.
Whether to run the model response in the background.
Response
Successful Response
- ResponseOutputMessage
- Option 2
Show child attributes
Show child attributes
Allowed value:
"response"Show child attributes
Show child attributes