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

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

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

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

{
  "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.

{}

{
  "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.

{}

"deepseek/deepseek-v4.1-flash"
  • stream (optional): s373

s373: boolean | null

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

{}

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.

{
  "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.

{}

{
  "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.

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.

{}

{
  "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.

{}

{
  "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.

{
  "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.

{}

{
  "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.

{}

{
  "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"}

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.

{}

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

{}

{
  "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).

{}

[
  "deepinfra",
  "open-inference"
]

s7: string

{}

  • docs_url (required): s640

s640: string

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

{}

"/docs#description/model-not-found"
  • failed_routing_step (optional): s641

s641: string

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

{}

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

{}

{
  "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"

{}

"out_of_range"
  • message (required): s637

s637: string

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

{}

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

{}

"$.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.

{}

{
  "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"

{}

"rate_limited"
  • code (optional): s1300

s1300: string

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

{}

"rate_limit_exceeded"
  • provider_name (required): s1301

s1301: string

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

{}

"deepinfra"
  • retry_after (optional): s1302

s1302: integer

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

int64

{"minimum":"0"}

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"}

429

oneOf: s588

s588: null

{}

  • provider_name (optional): s644

s644: string

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

{}

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

{}

""
  • remedy_hint (optional): s646

s646: string

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

{}

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

{}

"req_01k7tm9qz3f5c8x2v6b4n0m7hd"
  • requested_providers (optional): s648

s648: array

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

{}

[
  "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"}

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.

{}

{
  "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"}

2
  • reason (optional): s980

s980: string

The request field the step filtered on.

{}

"provider.only"
  • step (required): s981

s981: string

Name of the step, as at OpenRouter.

{}

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

{}

"invalid_parameter"
  • user_id (optional): s239

s239: string | null

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

{}

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