# Create a response

Accepts text or a full conversation in input and translates it to Chat Completions for
the routed provider. Normal answers contain message, reasoning and function_call output
items. Streams send typed lifecycle and output delta events as upstream produces them,
followed by done events and response.completed or response.incomplete, then `[DONE]`.
A failure after the first byte ends with response.failed and catalog metadata in
response.error; HTTP failures before streaming use the normal error envelope.

Routing, EUR billing, key policies, content capture and session/chain recording are shared
with Chat Completions. A completed response is recorded before its final event leaves.
No response state is stored for previous_response_id; send the complete history in input.

`POST https://api.tokenlane.de/v1/responses`

## Authorizations

[
  [
    {
      "name": "Authorization",
      "description": "API key as bearer token in the `Authorization` header: `Authorization: Bearer sk-tl-v1-…`. Existing `sk-eu-` keys remain valid. Missing, unknown or expired keys get 401 `authentication`.",
      "type": "http bearer",
      "location": "",
      "scopes": []
    }
  ]
]

## curl

```curl
curl --request POST \
  --url 'https://api.tokenlane.de/v1/responses' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "input": "What is the capital of Portugal?",
  "instructions": "Answer in one sentence.",
  "max_output_tokens": 400,
  "model": "deepseek/deepseek-v4-flash-0731"
}'
```

## node

```node
import OpenAI from 'openai';

const client = new OpenAI({ baseURL: "https://api.tokenlane.de/v1", apiKey: process.env.TOKENLANE_API_KEY });
const response = await client.responses.create({
  "input": "What is the capital of Portugal?",
  "instructions": "Answer in one sentence.",
  "max_output_tokens": 400,
  "model": "deepseek/deepseek-v4-flash-0731"
}, {});
console.log(response);
```

## python

```python
import os
import json
from openai import OpenAI

client = OpenAI(base_url="https://api.tokenlane.de/v1", api_key=os.environ["TOKENLANE_API_KEY"])
body = json.loads(r'''{
  "input": "What is the capital of Portugal?",
  "instructions": "Answer in one sentence.",
  "max_output_tokens": 400,
  "model": "deepseek/deepseek-v4-flash-0731"
}''')
response = client.responses.create(
    model=body["model"],
    input=body["input"],
    instructions=body["instructions"],
    max_output_tokens=body["max_output_tokens"]
)
print(response)
```

## vercel

```vercel
// This operation uses HTTP directly.
const response = await fetch("https://api.tokenlane.de/v1/responses", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.TOKENLANE_API_KEY,
    "Content-Type": "application/json",
  },
  body: `{
  "input": "What is the capital of Portugal?",
  "instructions": "Answer in one sentence.",
  "max_output_tokens": 400,
  "model": "deepseek/deepseek-v4-flash-0731"
}`,
});
console.log(await response.text());
```

## header: Idempotency-Key (optional)

Explicit opt-in to encrypted response replay across gateway nodes. One 1..=255 printable ASCII value per logical operation, scoped to this API key ID. Reuse the same method, path and normalized body. Completed responses are retained for at most 10 minutes; replay is free and creates no generation. Conflicting content or unavailable replay returns 409. A successful replay carries Idempotent-Replayed: true and preserves the original request and generation IDs. See /docs/guides/idempotency.

### s0: string | null

{}

## header: x-session-id (optional)

Session ID, unless session_id is present in the body; same limits as Chat Completions.

## Body: application/json

```json
{
  "input": "What is the capital of Portugal?",
  "instructions": "Answer in one sentence.",
  "max_output_tokens": 400,
  "model": "deepseek/deepseek-v4-flash-0731"
}
```

### s32: object

A stateless Responses invocation, translated to Chat Completions for the selected model.
`input` is text or a conversation of message, reasoning, function_call and
function_call_output items. Messages support input_text, output_text, input_image,
input_file, input_audio and input_video parts. Function tools and choices use Responses'
flat shape (`{"type":"function","name":"get_weather","parameters":{...}}`).
`text.format` selects text, json_object or json_schema; max_output_tokens limits generation.
Routing, policies, EUR costs, reasoning controls, sessions and plugins follow the Chat API.

This endpoint does not store response state: previous_response_id, enabled background/store,
stored prompts, opaque reasoning, server-tool schemas and include expansions fail with
not_available issues. Send the complete history in input. Automatic truncation and output
media generation are unavailable. Unknown top-level fields appear in x-ignored-params.

{}

```json
{
  "input": "What is the capital of Portugal?",
  "instructions": "Answer in one sentence.",
  "max_output_tokens": 400,
  "model": "deepseek/deepseek-v4.1-flash"
}
```

- model (optional): s372

### s372: string | null

Public model ID or gateway alias; required unless models lists fallbacks.

{}

```json
"deepseek/deepseek-v4.1-flash"
```

- stream (optional): s373

### s373: boolean | null

Streams typed response.created, output item/part/delta/done and terminal events.

{}

```json
false
```

- * (optional): s374

### s374: any

Responses parameters, including input (a string or heterogeneous array of input items),
instructions, tools, max_output_tokens and the generation/routing options above.
Input items retain provider extensions; the gateway validates their known fields.

{}

## Response 200: application/json

Responses envelope or typed SSE events, ending in [DONE]. Costs are EUR. Output is retained only within the shared response budget (at most 32 MiB) for done/completed events; deltas stream immediately. Overload, invalid upstream output and disconnects release the upstream request.

```json
{
  "completed_at": 1792417001,
  "created_at": 1792417000,
  "error": null,
  "frequency_penalty": 0,
  "id": "gen-019a-abc",
  "incomplete_details": null,
  "instructions": null,
  "metadata": {},
  "model": "deepseek/deepseek-v4.1-flash",
  "object": "response",
  "output": [
    {
      "content": [
        {
          "annotations": [],
          "logprobs": [],
          "text": "Lisbon.",
          "type": "output_text"
        }
      ],
      "id": "msg_019a_0",
      "role": "assistant",
      "status": "completed",
      "type": "message"
    }
  ],
  "parallel_tool_calls": true,
  "presence_penalty": 0,
  "status": "completed",
  "temperature": 1,
  "tool_choice": "auto",
  "tools": [],
  "top_p": 1
}
```

### s33: object

A response envelope. Output contains message items with output_text or refusal content,
reasoning items with reasoning_text content, and function_call items. No reasoning or
usage is invented when upstream omits it. The response ID is the generation lookup ID.

{}

```json
{
  "completed_at": 1792417001,
  "created_at": 1792417000,
  "error": null,
  "frequency_penalty": 0,
  "id": "gen-019a-abc",
  "incomplete_details": null,
  "instructions": null,
  "metadata": {},
  "model": "deepseek/deepseek-v4.1-flash",
  "object": "response",
  "output": [
    {
      "content": [
        {
          "annotations": [],
          "logprobs": [],
          "text": "Lisbon.",
          "type": "output_text"
        }
      ],
      "id": "msg_019a_0",
      "role": "assistant",
      "status": "completed",
      "type": "message"
    }
  ],
  "parallel_tool_calls": true,
  "presence_penalty": 0,
  "status": "completed",
  "temperature": 1,
  "tool_choice": "auto",
  "tools": [],
  "top_p": 1
}
```

- completed_at (optional): s375

### s375: integer | null

Completion time in Unix seconds, null while in progress or failed.

int64

{}

- created_at (required): s376

### s376: integer

Request creation time in Unix seconds.

int64

{}

- error (optional): s377

### s377: any

Failure information with the gateway's catalog metadata, otherwise null.

{}

- frequency_penalty (optional): s378

### s378: number | null

Effective frequency penalty, default 0.

double

{}

- id (required): s379

### s379: string

Gateway generation ID, also returned in x-generation-id.

{}

- incomplete_details (optional): s380

### s380: any

Why generation was incomplete (max_output_tokens or content_filter), otherwise null.

{}

- instructions (optional): s381

### s381: string | null

Instruction text echoed from the request, otherwise null.

{}

- metadata (required): s382

### s382: object

Caller metadata, default empty object.

{}

- * (optional): s1075

### s1075: any

{}

- model (required): s383

### s383: string

Actual model selected after aliases and fallbacks.

{}

- object (required): s384

### s384: string

Always response.

"response"

{}

- output (required): s385

### s385: array

Ordered output items with stable IDs and their content or function arguments.

{}

### s1076: any

{}

- parallel_tool_calls (required): s386

### s386: boolean

Whether parallel function calls were permitted, default true.

{}

- presence_penalty (optional): s387

### s387: number | null

Effective presence penalty, default 0.

double

{}

- status (required): s388

### s388: string

completed, incomplete, in_progress or failed. Token exhaustion is incomplete.

{}

- temperature (optional): s389

### s389: number | null

Effective sampling temperature, default 1.

double

{}

- tool_choice (required): s390

### s390: any

Effective tool selection, default auto.

{}

- tools (required): s391

### s391: array

Function tool definitions in Responses format, default empty list.

{}

### s1077: any

{}

- top_p (optional): s392

### s392: number | null

Effective nucleus sampling parameter, default 1.

double

{}

- usage (optional): s393

### s393: any

Token counts with input_tokens/output_tokens and details; cost is EUR, including the
original currency and FX metadata for providers priced in another currency.

{}

- * (optional): s394

### s394: any

Other effective options such as max_output_tokens, text, reasoning and store.

{}

## Response 200: text/event-stream

Responses envelope or typed SSE events, ending in [DONE]. Costs are EUR. Output is retained only within the shared response budget (at most 32 MiB) for done/completed events; deltas stream immediately. Overload, invalid upstream output and disconnects release the upstream request.

```text
event: response.output_text.delta
data: {"content_index":0,"delta":"Lisbon","item_id":"msg_019a_0","logprobs":[],"output_index":0,"sequence_number":4,"type":"response.output_text.delta"}


```

### s34: object

One server-sent event, whose JSON payload follows `data:` on the wire. The stream uses
`event:` for its event type and ends with the non-JSON `data: [DONE]` sentinel.

{}

```json
{
  "data": {
    "content_index": 0,
    "delta": "Lisbon",
    "item_id": "msg_019a_0",
    "logprobs": [],
    "output_index": 0,
    "sequence_number": 4,
    "type": "response.output_text.delta"
  }
}
```

- data (required): s395

### s395: object

Typed lifecycle or output event carried by the SSE frame.

{}

```json
{
  "content_index": 0,
  "delta": "Lisbon",
  "item_id": "msg_019a_0",
  "logprobs": [],
  "output_index": 0,
  "sequence_number": 4,
  "type": "response.output_text.delta"
}
```

- sequence_number (required): s971

### s971: integer

Monotonically increasing event number, starting at zero.

int64

{"minimum":"0"}

- type (required): s972

### s972: string

Lifecycle or output event name, also the SSE event field.

{}

- * (optional): s973

### s973: any

Event payload: response, item, part, delta or full text/arguments, with indices and IDs.

{}

## Response 400: application/json

Recognized upstream 400/422 request rejections are non-retryable client errors. Invalid JSON, invalid parameters with all issues in original input paths, unknown model or context length exceeded. Unsupported stateful options and server tools have not_available issues.

```json
{
  "error": {
    "code": 400,
    "message": "deepseek/deepseek-v4.1-flsh is not a valid model ID",
    "metadata": {
      "docs_url": "/docs#description/model-not-found",
      "issues": [
        {
          "code": "unknown_model",
          "message": "deepseek/deepseek-v4.1-flsh is not a valid model ID",
          "path": "$.model"
        }
      ],
      "remedy_hint": "Did you mean deepseek/deepseek-v4.1-flash?",
      "request_id": "req_01k7tm9qz3f5c8x2v6b4n0m7hd",
      "retryable": false,
      "type": "model_not_found"
    }
  },
  "user_id": "org_01k7tm2c4e6g8j0k2m4p6r8t0v"
}
```

### s3: object

Every response with an HTTP status of 400 or higher has this shape, OpenRouter's error
format. Everything the gateway adds is inside `error.metadata`, so OpenRouter clients see
nothing unfamiliar. See "Errors" in the introduction for all error types.

{}

```json
{
  "error": {
    "code": 400,
    "message": "deepseek/deepseek-v4.1-flsh is not a valid model ID",
    "metadata": {
      "docs_url": "/docs#description/model-not-found",
      "issues": [
        {
          "code": "unknown_model",
          "message": "deepseek/deepseek-v4.1-flsh is not a valid model ID",
          "path": "$.model"
        }
      ],
      "remedy_hint": "Did you mean deepseek/deepseek-v4.1-flash?",
      "request_id": "req_01k7tm9qz3f5c8x2v6b4n0m7hd",
      "retryable": false,
      "type": "model_not_found"
    }
  },
  "user_id": "org_01k7tm2c4e6g8j0k2m4p6r8t0v"
}
```

- error (required): s238

### s238: object

What went wrong.

{}

```json
{
  "code": 400,
  "message": "temperature must be at most 2, got 5 (and 1 more)",
  "metadata": {
    "docs_url": "/docs#description/invalid-parameter",
    "issues": [
      {
        "code": "out_of_range",
        "message": "temperature must be at most 2, got 5",
        "path": "$.temperature"
      },
      {
        "code": "invalid_value",
        "message": "messages[1].role must be one of system, developer, user, assistant, tool, got \"bot\"",
        "path": "$.messages[1].role"
      }
    ],
    "request_id": "req_01k7tm9qz3f5c8x2v6b4n0m7hd",
    "retryable": false,
    "type": "invalid_parameter"
  }
}
```

- code (required): s633

### s633: integer

The HTTP status of the response, as a number.

int32

{"minimum":"0"}

```json
400
```

- message (required): s634

### s634: string

What went wrong, in English. With several problems: the first one and how many more
follow; all of them are in `metadata.issues`. The text may change; match on
`metadata.type` instead.

{}

```json
"temperature must be at most 2, got 5"
```

- metadata (optional): s635

### s635: object

Details for programs: error type, request ID, every problem, a suggested fix and, for
provider errors, which provider failed. Always present on gateway errors.

{}

```json
{
  "docs_url": "/docs#description/rate-limited",
  "provider_error": {
    "category": "rate_limited",
    "provider_name": "deepinfra",
    "retry_after": 2,
    "retryable": true,
    "status": 429
  },
  "provider_name": "deepinfra",
  "remedy_hint": "Retry after the Retry-After interval, or allow fallbacks to other providers (provider.allow_fallbacks).",
  "request_id": "req_01k7tm9qz3f5c8x2v6b4n0m7hd",
  "retry_after": 2,
  "retryable": true,
  "type": "rate_limited"
}
```

- available_providers (optional): s639

### s639: array

Providers that serve the model (when `provider.only` excluded all of them).

{}

```json
[
  "deepinfra",
  "open-inference"
]
```

### s7: string

{}

- docs_url (required): s640

### s640: string

Link to the section of this error type in the documentation.

{}

```json
"/docs#description/model-not-found"
```

- failed_routing_step (optional): s641

### s641: string

The routing step that left no route (routing errors only).

{}

```json
"Filter by Max Price"
```

- issues (optional): s642

### s642: array

Every problem found in the request, so all can be fixed at once (at most 20); for
routing errors one entry per excluded route, for `no_provider_available` one per failed
attempt.

{}

### s123: object

One problem in the request, one reason a route was excluded, or one failed attempt.

{}

```json
{
  "code": "invalid_url",
  "message": "messages[2].content[0].image_url.url must be an http(s) URL or a base64 data URL",
  "path": "$.messages[2].content[0].image_url.url"
}
```

- code (required): s636

### s636: string

Kind of problem, stable for programs.

"required", "invalid_type", "invalid_value", "out_of_range", "empty", "invalid_url", "invalid_base64", "unsupported_media_type", "media_type_mismatch", "media_too_large", "too_many_media", "unsupported_media_transport", "media_fetch_failed", "unknown_tool", "unknown_model", "not_available", "not_allowed", "route_excluded", "bridge_failed", "provider_failed"

{}

```json
"out_of_range"
```

- message (required): s637

### s637: string

The problem in English, naming the field and, if short, the value sent.

{}

```json
"temperature must be at most 2, got 5"
```

- path (required): s638

### s638: string

Where the problem is: JSONPath of the field in the request body, for example
`$.messages[2].content[0].image_url.url`, or `query.<name>` for a query parameter.

{}

```json
"$.temperature"
```

- provider_error (optional): s643

### s643: oneOf

Safe provider diagnostics, identical for HTTP errors and terminal stream events.

{}

oneOf: s1158

### s1158: object

Provider diagnostics without provider-authored text. HTTP and terminal SSE errors use
this same structure; arbitrary upstream messages and metadata are discarded.

{}

```json
{
  "category": "rate_limited",
  "provider_name": "deepinfra",
  "retry_after": 2,
  "retryable": true,
  "status": 429
}
```

- category (required): s1299

### s1299: string

Gateway classification from HTTP status and recognized dialect identifiers.

"rate_limited", "overloaded", "invalid_request", "context_length", "content_filtered", "authentication", "billing", "timeout", "unavailable", "unknown"

{}

```json
"rate_limited"
```

- code (optional): s1300

### s1300: string

Exact identifier from the configured dialect's fixed list; arbitrary values vanish.

{}

```json
"rate_limit_exceeded"
```

- provider_name (required): s1301

### s1301: string

Configured provider name, never a name supplied by the upstream body.

{}

```json
"deepinfra"
```

- retry_after (optional): s1302

### s1302: integer

Bounded seconds from the upstream Retry-After header, when present and numeric.

int64

{"minimum":"0"}

```json
2
```

- retryable (required): s1303

### s1303: boolean

Whether the classified failure can be transient. Unknown failures are not promised retryable.

{}

- status (optional): s1304

### s1304: integer

Actual HTTP status received from the upstream, including 200 for native errors.
Absent when no HTTP status is available.

int32

{"minimum":"0"}

```json
429
```

oneOf: s588

### s588: null

{}

- provider_name (optional): s644

### s644: string

The provider that failed, as in the response field `provider` (provider errors only).

{}

```json
"deepinfra"
```

- raw (optional): s645

### s645: string

Reserved OpenRouter compatibility field. The gateway never fills it: provider
free text is deliberately withheld. Use provider_error instead.

{}

```json
""
```

- remedy_hint (optional): s646

### s646: string

A concrete fix, for example the closest model ID to a mistyped one.

{}

```json
"Did you mean deepseek/deepseek-v4.1-flash?"
```

- request_id (required): s647

### s647: string

ID of the request, the same as the `x-request-id` response header. Quote it when
contacting support.

{}

```json
"req_01k7tm9qz3f5c8x2v6b4n0m7hd"
```

- requested_providers (optional): s648

### s648: array

Providers named in `provider.only` (when it excluded all routes).

{}

```json
[
  "scaleway"
]
```

- retry_after (optional): s649

### s649: integer

Seconds to wait before retrying; also sent as the `Retry-After` header (429 and 503).

int64

{"minimum":"0"}

```json
2
```

- retryable (required): s650

### s650: boolean

Whether sending the identical request again can succeed (for example after a timeout
or rate limit), as opposed to errors that need a changed request.

{}

- routing_funnel (optional): s651

### s651: array

How routing narrowed down the providers: each step with the number of routes left
(routing errors only, same format as OpenRouter).

{}

### s200: object

One routing step, as in OpenRouter's `routing_funnel`.

{}

```json
{
  "endpoint_count": 0,
  "reason": "provider.max_price",
  "step": "Filter by Max Price"
}
```

- endpoint_count (required): s979

### s979: integer

Number of routes (providers of the model) left after the step.

{"minimum":"0"}

```json
2
```

- reason (optional): s980

### s980: string

The request field the step filtered on.

{}

```json
"provider.only"
```

- step (required): s981

### s981: string

Name of the step, as at OpenRouter.

{}

```json
"Initial Endpoints"
```

- type (required): s652

### s652: string

Stable error type to match on in code; see "Errors" in the introduction. Messages may
change, the type does not.

"invalid_request", "invalid_parameter", "unsupported_parameter", "context_length_exceeded", "authentication", "insufficient_credits", "workspace_budget_exceeded", "permission_denied", "moderation", "model_not_found", "no_endpoint", "not_found", "method_not_allowed", "timeout", "payload_too_large", "media_fetch_failed", "rate_limited", "provider_error", "idempotency_conflict", "idempotency_in_progress", "idempotency_unavailable", "provider_invalid_response", "no_provider_available", "byok_invalid_credential", "byok_rate_limited", "byok_unavailable", "feature_unavailable", "internal"

{}

```json
"invalid_parameter"
```

- user_id (optional): s239

### s239: string | null

Organization of the API key, if the key was recognized.

{}

```json
"org_01k7tm2c4e6g8j0k2m4p6r8t0v"
```

## Response 401: application/json

Missing, invalid or expired API key.

## Response 402: application/json

The API key spending limit, the workspace budget (`workspace_budget_exceeded`) or the organization prepaid balance cannot cover the estimated request reservation, including fees, media and concurrent reservations (`insufficient_credits` for key and organization). No paid upstream call starts without a reservation.

## Response 403: application/json

The organization, workspace or key policy forbids the requested model, or the key's policy the server tool.

## Response 404: application/json

No route supports the requested model, modalities, parameters or provider preferences.

## Response 408: application/json

Request upload, upstream connection, first byte or complete response timed out.

## Response 409: application/json

idempotency_conflict: this key has different request content; use a new key. idempotency_in_progress: the original is running; respect Retry-After. idempotency_unavailable: no safe replay is possible; do not silently recompute. See remedy_hint.

## Response 413: application/json

Request body exceeds 50 MiB or JSON structure excluding JSON string values exceeds 20 MiB.

## Response 429: application/json

Customer quota or provider rate limit; retry after the indicated delay.

## Response 500: application/json

Unexpected gateway error.

## Response 501: application/json

feature_unavailable: A required feature is permanently unconfigured on this gateway, for example encrypted idempotency replay without its encryption key, PII redaction without a detector, or BYOK import without import keys. Ask the operator to configure it or remove the optional feature from the request. Retrying the identical request cannot enable the feature: retryable is false and no Retry-After header is sent. Temporary cache, database, detector or provider outages, pending imports and missing or revoked individual customer credentials retain their existing error types.

## Response 502: application/json

Provider failure, invalid or excessively large output.

## Response 503: application/json

No provider answered, exchange rate missing, memory or generation queue exhausted, or shutdown in progress.
