> ## Documentation Index
> Fetch the complete documentation index at: https://www.edenai.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

export const TechArticleSchema = ({title, description, path, articleSection, about, proficiencyLevel = "Beginner", dependencies, keywords = [], datePublished, dateModified, image, inLanguage = "en"}) => {
  const baseUrl = "https://www.edenai.co/docs";
  const canonicalUrl = `${baseUrl}/${path}`.replace(/\/+$/, "");
  const ogParams = new URLSearchParams({
    division: articleSection || "",
    title: title || "",
    description: description || ""
  });
  const resolvedImage = image || `https://edenai.mintlify.app/_mintlify/api/og?${ogParams.toString()}`;
  const data = {
    "@context": "https://schema.org",
    "@type": "TechArticle",
    "@id": `${canonicalUrl}#techarticle`,
    mainEntityOfPage: {
      "@type": "WebPage",
      "@id": canonicalUrl
    },
    headline: title,
    name: title,
    description: description,
    url: canonicalUrl,
    inLanguage: inLanguage,
    isPartOf: {
      "@type": "WebSite",
      name: "Eden AI Documentation",
      url: baseUrl
    },
    author: [{
      "@type": "Organization",
      name: "Eden AI",
      url: "https://www.edenai.co/"
    }],
    publisher: {
      "@type": "Organization",
      name: "Eden AI",
      url: "https://www.edenai.co/",
      logo: {
        "@type": "ImageObject",
        url: "https://www.edenai.co/assets/logo.png"
      }
    }
  };
  if (articleSection) data.articleSection = articleSection;
  if (about) data.about = {
    "@type": "Thing",
    name: about
  };
  if (proficiencyLevel) data.proficiencyLevel = proficiencyLevel;
  if (dependencies) data.dependencies = dependencies;
  if (keywords && keywords.length) data.keywords = keywords;
  if (datePublished) data.datePublished = datePublished;
  if (dateModified) data.dateModified = dateModified;
  data.image = Array.isArray(resolvedImage) ? resolvedImage : [resolvedImage];
  const json = JSON.stringify(data);
  const schemaId = `techarticle-${canonicalUrl}`;
  React.useEffect(() => {
    if (typeof document === "undefined") return;
    document.querySelectorAll(`script[data-schema-id="${schemaId}"]`).forEach(n => n.remove());
    const script = document.createElement("script");
    script.type = "application/ld+json";
    script.dataset.schemaId = schemaId;
    script.textContent = json;
    document.head.appendChild(script);
    return () => script.remove();
  }, [json, schemaId]);
  return null;
};

<TechArticleSchema title={"Responses"} description={"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."} path="v3/llms/responses" articleSection="LLMs" about={"LLM API"} proficiencyLevel="Intermediate" keywords={["Eden AI", "AI API", "LLM API", "chat completion", "OpenAI compatible"]} datePublished="2026-05-06T00:00:00Z" dateModified="2026-05-07T00:00:00Z" />

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   |

<Warning>
  **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.
</Warning>

## 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

<CodeGroup>
  ```python Python theme={null}
  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"])
  ```

  ```javascript JavaScript theme={null}
  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);
  ```

  ```bash cURL theme={null}
  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."
    }'
  ```
</CodeGroup>

## 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

```json theme={null}
{
  "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:

<CodeGroup>
  ```python Python theme={null}
  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"])
  ```

  ```javascript JavaScript theme={null}
  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);
  ```
</CodeGroup>

<Warning>
  `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).
</Warning>

<Tip>
  Pass `store: false` if you don't need persistence and want to keep the conversation stateless, like chat completions.
</Tip>

## Retrieve a Response

<Warning>
  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.
</Warning>

Fetch a previously stored response by ID:

<CodeGroup>
  ```python Python theme={null}
  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"])
  ```

  ```bash cURL theme={null}
  curl https://api.edenai.run/v3/responses/resp_abc123def456 \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</CodeGroup>

## Delete a Response

<Warning>
  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.
</Warning>

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

<CodeGroup>
  ```python Python theme={null}
  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}
  ```

  ```bash cURL theme={null}
  curl -X DELETE https://api.edenai.run/v3/responses/resp_abc123def456 \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</CodeGroup>

## OpenAI SDK

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

<CodeGroup>
  ```python Python theme={null}
  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)
  ```
</CodeGroup>

For multi-turn with the SDK:

<CodeGroup>
  ```python Python theme={null}
  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)
  ```
</CodeGroup>

## Streaming

Set `stream: true` to receive output incrementally as Server-Sent Events. See [Streaming](/v3/llms/streaming) for the full SSE format and parsing examples.

## Next Steps

<CardGroup cols={2}>
  <Card title="Chat Completions" icon="comment-dots" href="/v3/llms/chat-completions">
    Use the stateless chat completions endpoint
  </Card>

  <Card title="Streaming" icon="bolt" href="/v3/llms/streaming">
    Receive responses token by token via SSE
  </Card>

  <Card title="Structured Output" icon="brackets-curly" href="/v3/llms/structured-output">
    Constrain responses to a JSON schema
  </Card>
</CardGroup>