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

# Create a response

> Create a model response with text input, tools, reasoning controls, streaming, and multi-turn continuation.

Creates a response from text or structured input. The Responses API represents model output as typed items and is the recommended surface for new agentic workflows.

## Endpoint

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
POST https://api.yelu.ai/v1/responses
```

## Headers

<ParamField header="Authorization" type="string" required>
  API key using the format `Bearer $YELU_API_KEY`.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`.
</ParamField>

## Request body

<ParamField body="model" type="string" required>
  A model ID returned by [`GET /v1/models`](/en/api-reference/models).
</ParamField>

<ParamField body="input" type="string | array">
  Text input or an array of typed input messages/items. Supply input unless continuing in a provider-supported way.
</ParamField>

<ParamField body="instructions" type="string">
  High-priority instructions for the response.
</ParamField>

<ParamField body="previous_response_id" type="string">
  ID of a prior response to continue a conversation when the selected model/provider supports stored response state.
</ParamField>

<ParamField body="max_output_tokens" type="integer">
  Maximum output tokens, including model-specific reasoning usage where applicable.
</ParamField>

<ParamField body="temperature" type="number">
  Sampling temperature on models that expose this control.
</ParamField>

<ParamField body="top_p" type="number">
  Nucleus sampling probability on models that expose this control.
</ParamField>

<ParamField body="stream" type="boolean" default="false">
  Returns typed Server-Sent Events when `true`.
</ParamField>

<ParamField body="tools" type="array">
  Tools the model may call, including function definitions supported by the selected model.
</ParamField>

<ParamField body="tool_choice" type="string | object">
  Controls whether and which tool the model may select.
</ParamField>

<ParamField body="reasoning" type="object">
  Reasoning configuration. Supported fields include `effort` (`low`, `medium`, or `high`) and provider-supported summary controls.
</ParamField>

<ParamField body="truncation" type="string" default="disabled">
  `auto` allows context truncation when supported; `disabled` fails instead of silently removing context.
</ParamField>

## Response

<ResponseField name="id" type="string" required>
  Unique response identifier.
</ResponseField>

<ResponseField name="object" type="string" required>
  Always `response` for the completed response object.
</ResponseField>

<ResponseField name="created_at" type="integer" required>
  Unix timestamp for creation.
</ResponseField>

<ResponseField name="status" type="string" required>
  `completed`, `failed`, `in_progress`, or `incomplete`.
</ResponseField>

<ResponseField name="model" type="string" required>
  Model that handled the request.
</ResponseField>

<ResponseField name="output" type="array" required>
  Typed output items. A message item commonly includes `id`, `status`, `role`, and a `content` array with `output_text` objects. Tool calls appear as separate items.
</ResponseField>

<ResponseField name="usage" type="object">
  Input, output, total, cached, or reasoning token accounting supplied by the selected model.
</ResponseField>

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl https://api.yelu.ai/v1/responses \
    -H "Authorization: Bearer $YELU_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-4o-mini",
      "instructions": "Answer for a software engineering audience.",
      "input": "What is idempotency?",
      "max_output_tokens": 160
    }'
  ```

  ```javascript JavaScript (Fetch) theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch('https://api.yelu.ai/v1/responses', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.YELU_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'gpt-4o-mini',
      instructions: 'Answer for a software engineering audience.',
      input: 'What is idempotency?',
      max_output_tokens: 160,
    }),
  });

  if (!response.ok) throw new Error(await response.text());
  const data = await response.json();
  const text = data.output
    .flatMap((item) => item.content ?? [])
    .filter((item) => item.type === 'output_text')
    .map((item) => item.text)
    .join('');
  console.log(text);
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import os
  import requests

  response = requests.post(
      "https://api.yelu.ai/v1/responses",
      headers={"Authorization": f"Bearer {os.environ['YELU_API_KEY']}"},
      json={
          "model": "gpt-4o-mini",
          "instructions": "Answer for a software engineering audience.",
          "input": "What is idempotency?",
          "max_output_tokens": 160,
      },
      timeout=60,
  )
  response.raise_for_status()
  data = response.json()
  text = "".join(
      part["text"]
      for item in data["output"]
      for part in item.get("content", [])
      if part.get("type") == "output_text"
  )
  print(text)
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "id": "resp_01JYELU9R2",
    "object": "response",
    "created_at": 1783900800,
    "status": "completed",
    "model": "gpt-4o-mini",
    "output": [
      {
        "type": "message",
        "id": "msg_01JYELU9R3",
        "status": "completed",
        "role": "assistant",
        "content": [
          {
            "type": "output_text",
            "text": "Idempotency means repeating the same operation has the same intended effect as performing it once."
          }
        ]
      }
    ],
    "usage": {
      "input_tokens": 20,
      "output_tokens": 22,
      "total_tokens": 42
    }
  }
  ```

  ```json 400 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "error": {
      "message": "Input is required for this request.",
      "type": "invalid_request_error",
      "param": "input",
      "code": "missing_required_parameter"
    }
  }
  ```
</ResponseExample>

## Error codes

| Status      | Code or type                            | Meaning                                               |
| ----------- | --------------------------------------- | ----------------------------------------------------- |
| `400`       | `invalid_request_error`                 | Invalid input item, field, tool, or model capability. |
| `401`       | `authentication_error`                  | Missing or invalid API key.                           |
| `403`       | `permission_denied`                     | The model or operation is not allowed.                |
| `404`       | `model_not_found` or response not found | Invalid model or unsupported prior response ID.       |
| `413`       | `request_too_large`                     | Input exceeds the accepted request or context size.   |
| `429`       | `rate_limit_error`                      | Request limit reached.                                |
| `500`–`504` | `server_error`                          | Temporary gateway or upstream failure.                |

<Warning>
  Provider support for stored response state varies. Persist the conversation state your application needs; do not rely solely on `previous_response_id` without testing the selected model route.
</Warning>