Responses API

Use Responses for reasoning models, multimodal inputs and Lazu file_id dereferencing. This is the recommended endpoint when a request needs uploaded files or newer OpenAI response features.

BillingUsage tokens at the selected model and lane price; other billable dimensions may apply. Pricing & lanes ↗

When to use it

Request body

Content parts

File dereferencing

Upload via Files, then reference the resulting

file_id. Lazu adds X-Lazu-File-Dereference: 1 when the request dereferenced files.

Limits:

• Single file purpose limit still applies.
• Total dereferenced files in one Responses call must stay under 64 MB.
• Chat completions does not auto-dereference file_id.

Stateless compatibility bridges

Some catalog entries expose Responses through a lossless Chat bridge; check supported_endpoints[].mode. On such a route, omitted store is accepted and returns X-Lazu-Warning: stateless_bridge, while store: false is accepted without a warning. Explicit store: true, stateful fields, and unknown cross-protocol fields return 400 protocol_bridge_unsupported before an upstream call. The standard Responses body is not extended with Lazu-only fields.

Response

For full reconciliation, use

GET /api/usage/requests/{request_id} with the same API key.

See also

• Files API
• Chat completions
• Model catalog

Complete tool round trip

Select a model with Responses and function tools from your token-scoped catalog, then set LAZU_API_KEY and LAZU_MODEL. Keep every output item when continuing a stateless conversation, including reasoning items; append the tool result with the same call_id. Encrypted or provider-specific reasoning state remains native-only when a bridge cannot preserve it.

import json
import os
from openai import OpenAI, APIStatusError

client = OpenAI(
    api_key=os.environ["LAZU_API_KEY"],
    base_url=os.environ.get("LAZU_BASE_URL", "https://api.lazu.ai/v1"),
    max_retries=0,
)
model = os.environ["LAZU_MODEL"]
tools = [{"type": "function", "name": "add", "description": "Add two integers",
          "parameters": {"type": "object", "properties": {
              "a": {"type": "integer"}, "b": {"type": "integer"}},
              "required": ["a", "b"], "additionalProperties": False}}]
history = [{"role": "user", "content": "Use add to calculate 2 + 3."}]
try:
    first = client.responses.create(model=model, input=history, tools=tools,
        tool_choice={"type": "function", "name": "add"}, store=False,
        max_output_tokens=1024)
    history.extend(item.model_dump(exclude_unset=True) for item in first.output)
    for item in first.output:
        if item.type == "function_call":
            if item.name != "add":
                raise ValueError("Unexpected tool")
            args = json.loads(item.arguments)
            history.append({"type": "function_call_output", "call_id": item.call_id,
                            "output": json.dumps({"result": args["a"] + args["b"]})})
    final = client.responses.create(model=model, input=history, tools=tools,
        tool_choice="none", store=False, max_output_tokens=1024)
    print(final.output_text)
except APIStatusError as exc:
    print(exc.status_code, exc.response.headers.get("x-lazu-request-id"), exc.body)
    raise

Do not replay automatically after output has arrived. For 413 request_body_too_large, reduce the request; for 503 gateway_overloaded, retry later with backoff. Local overload does not imply a provider failure. Use request details to reconcile partial usage.