Responses

Eden AI supports the OpenAI Responses API — a stateful alternative to chat completions that stores conversation history server-side, so you don’t need to resend the full message history on each turn.

Overview

Endpoints:

Method	Path	Description
`POST`	`/v3/responses`	Create a response
`GET`	`/v3/responses/{response_id}`	Retrieve a stored response
`DELETE`	`/v3/responses/{response_id}`	Delete a stored response

Provider-Dependent Behavior — The Responses API is a passthrough to the underlying provider. Stateful features (server-side storage, response retrieval/deletion, and previous_response_id chaining) are only available when the provider natively supports the Responses API (e.g. OpenAI). For all other providers, responses are not stored and the retrieve/delete endpoints are not functional.

How It Differs from Chat Completions

	Chat Completions	Responses
System prompt	`messages[{role: "system"}]`	`instructions` top-level field
User input	`messages` array	`input` string or array
Response text	`choices[0].message.content`	`output[0].content[0].text`
Multi-turn	Resend full history	`previous_response_id`
Persistence	Stateless	Stored by default (`store: true`)
Token fields	`prompt_tokens` / `completion_tokens`	`input_tokens` / `output_tokens`

Create a Response

import requests

url = "https://api.edenai.run/v3/responses"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

payload = {
    "model": "openai/gpt-4o",
    "input": "What is the capital of France?",
    "instructions": "You are a helpful assistant."
}

response = requests.post(url, headers=headers, json=payload)
result = response.json()

print(result["output"][0]["content"][0]["text"])

const response = await fetch("https://api.edenai.run/v3/responses", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "openai/gpt-4o",
    input: "What is the capital of France?",
    instructions: "You are a helpful assistant."
  })
});

const result = await response.json();
console.log(result.output[0].content[0].text);

curl -X POST https://api.edenai.run/v3/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "input": "What is the capital of France?",
    "instructions": "You are a helpful assistant."
  }'

Request Parameters

Parameter	Type	Default	Description
`model`	string	Required	Model string, e.g. `openai/gpt-4o`
`input`	string \| array	Required	User input — a plain string or an array of input items
`instructions`	string	—	System-level instructions for the model (replaces the `system` message)
`previous_response_id`	string	—	Chain to a prior response for multi-turn conversations
`store`	boolean	`true`	Persist the response server-side
`stream`	boolean	`false`	Enable streaming via SSE
`temperature`	float	`1.0`	Randomness (0–2)
`max_output_tokens`	integer	—	Maximum tokens to generate
`top_p`	float	`1.0`	Nucleus sampling threshold
`tools`	array	—	Tool definitions (function calling, web search)
`tool_choice`	string \| object	`"auto"`	How the model selects tools
`truncation`	string	`"disabled"`	Truncation strategy: `"auto"` or `"disabled"`
`metadata`	object	—	Arbitrary key-value pairs attached to the response
`user`	string	—	Stable identifier for the end-user

Response Object

{
  "id": "resp_abc123def456",
  "object": "response",
  "created_at": 1710000000,
  "model": "openai/gpt-4o",
  "status": "completed",
  "instructions": "You are a helpful assistant.",
  "output": [
    {
      "id": "msg_abc123",
      "type": "message",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "The capital of France is Paris."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 20,
    "output_tokens": 9,
    "total_tokens": 29
  },
  "provider": "openai",
  "cost": 0.000087,
  "provider_time": 1.23
}

Top-Level Fields

Field	Type	Description
`id`	string	Unique response identifier
`object`	string	Always `"response"`
`created_at`	integer	Unix timestamp of creation
`model`	string	Model that produced the response
`status`	string	`"completed"`, `"in_progress"`, `"incomplete"`, or `"failed"`
`instructions`	string	System instructions used
`output`	array	List of output items (messages, tool calls, reasoning)
`usage`	object	Token consumption
`error`	object	Present when `status` is `"failed"`
`provider`	string	Eden AI: provider name extracted from the model string
`cost`	float	Eden AI: estimated cost in USD for this request
`provider_time`	float	Eden AI: provider response time in seconds

`output[]` Item Types

`type`	Description
`message`	Assistant text response
`function_call`	A tool/function call requested by the model
`reasoning`	Reasoning steps (o-series models only)
`web_search_call`	Web search tool invocation

`usage` Fields

Field	Type	Description
`input_tokens`	integer	Tokens consumed by the input
`output_tokens`	integer	Tokens generated in the response
`total_tokens`	integer	Sum of input and output tokens

Multi-Turn Conversations

Because responses are stored server-side, you only need to send the new user message and reference the prior response ID:

import requests

url = "https://api.edenai.run/v3/responses"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

# First turn
res1 = requests.post(url, headers=headers, json={
    "model": "openai/gpt-4o",
    "input": "What is the capital of France?",
    "store": True
}).json()

print(res1["output"][0]["content"][0]["text"])

# Second turn — no need to resend history
res2 = requests.post(url, headers=headers, json={
    "model": "openai/gpt-4o",
    "input": "What is its population?",
    "previous_response_id": res1["id"]
}).json()

print(res2["output"][0]["content"][0]["text"])

const url = "https://api.edenai.run/v3/responses";
const headers = {
  "Authorization": "Bearer YOUR_API_KEY",
  "Content-Type": "application/json"
};

const res1 = await fetch(url, {
  method: "POST",
  headers,
  body: JSON.stringify({
    model: "openai/gpt-4o",
    input: "What is the capital of France?",
    store: true
  })
}).then(r => r.json());

const res2 = await fetch(url, {
  method: "POST",
  headers,
  body: JSON.stringify({
    model: "openai/gpt-4o",
    input: "What is its population?",
    previous_response_id: res1.id
  })
}).then(r => r.json());

console.log(res2.output[0].content[0].text);

previous_response_id chaining only works for providers with native Responses API support. For other providers, responses are not stored server-side — you must manage conversation history client-side (e.g. by resending the full message array, as with chat completions).

Pass store: false if you don’t need persistence and want to keep the conversation stateless, like chat completions.

Retrieve a Response

This endpoint only works for providers with native Responses API support. For other providers, responses are not stored and this endpoint will return an error.

Fetch a previously stored response by ID:

import requests

response_id = "resp_abc123def456"
url = f"https://api.edenai.run/v3/responses/{response_id}"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

result = requests.get(url, headers=headers).json()
print(result["output"][0]["content"][0]["text"])

curl https://api.edenai.run/v3/responses/resp_abc123def456 \
  -H "Authorization: Bearer YOUR_API_KEY"

Delete a Response

This endpoint only works for providers with native Responses API support. For other providers, responses are not stored and this endpoint will return an error.

Remove a stored response. The response will no longer be retrievable or usable as a previous_response_id:

import requests

response_id = "resp_abc123def456"
url = f"https://api.edenai.run/v3/responses/{response_id}"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

result = requests.delete(url, headers=headers).json()
print(result)  # {"id": "resp_abc123def456", "deleted": true}

curl -X DELETE https://api.edenai.run/v3/responses/resp_abc123def456 \
  -H "Authorization: Bearer YOUR_API_KEY"

OpenAI SDK

Use Eden AI’s Responses endpoint directly with the OpenAI Python SDK:

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_EDEN_AI_API_KEY",
    base_url="https://api.edenai.run/v3"
)

response = client.responses.create(
    model="anthropic/claude-sonnet-4-5",
    input="What is the capital of France?",
    instructions="You are a helpful assistant."
)

print(response.output[0].content[0].text)

For multi-turn with the SDK:

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_EDEN_AI_API_KEY",
    base_url="https://api.edenai.run/v3"
)

res1 = client.responses.create(
    model="openai/gpt-4o",
    input="What is the capital of France?",
    store=True
)

res2 = client.responses.create(
    model="openai/gpt-4o",
    input="What is its population?",
    previous_response_id=res1.id
)

print(res2.output[0].content[0].text)

Streaming

Set stream: true to receive output incrementally as Server-Sent Events. See Streaming for the full SSE format and parsing examples.

Next Steps

Chat Completions

Use the stateless chat completions endpoint

Streaming

Receive responses token by token via SSE

Structured Output

Constrain responses to a JSON schema

V3 Documentation

Quick Start

Overview

LLMs

Expert Models

General

Organization

Data Governance

Integrations

Overview

How It Differs from Chat Completions

Create a Response

Request Parameters

Response Object

Top-Level Fields

`output[]` Item Types

`usage` Fields

Multi-Turn Conversations

Retrieve a Response

Delete a Response

OpenAI SDK

Streaming

Next Steps

Chat Completions

Streaming

Structured Output

​Overview

​How It Differs from Chat Completions

​Create a Response

​Request Parameters

​Response Object

​Top-Level Fields

​output[] Item Types

​usage Fields

​Multi-Turn Conversations

​Retrieve a Response

​Delete a Response

​OpenAI SDK

​Streaming

​Next Steps

Chat Completions

Streaming

Structured Output

Overview

How It Differs from Chat Completions

Create a Response

Request Parameters

Response Object

Top-Level Fields

`output[]` Item Types

`usage` Fields

Multi-Turn Conversations

Retrieve a Response

Delete a Response

OpenAI SDK

Streaming

Next Steps