Responses API
Use POST /v1/responses for typed input and output items, function-call continuations, and the newest OpenAI-compatible response shape.
On this page 1 of 8
Request#
For a single text turn, input can be a string:
from getpass import getpass
from openai import OpenAI
client = OpenAI(
base_url="https://api.keirolabs.ai/v1",
api_key=getpass("Keiro API key: "),
)
response = client.responses.create(
model="eb1-preview",
input="Give three practical uses for structured outputs.",
)
print(response.output_text)
{
"model": "eb1-preview",
"input": "Explain token buckets in one sentence."
}
For multimodal or multi-turn work, send an array of typed message, text, image, function-call, and function-output items. Put stable application instructions in instructions.
Response#
OpenAI-compatible SDKs expose response.output_text as a convenience. In raw JSON, inspect output in order and read assistant output_text content parts. The same array can contain function-call and other structured output items.
For tool continuation, resend the complete conversation items, including the model's function_call and your matching function_call_output. Stateful previous_response_id continuation is not a portable public eb1 contract.
Supported controls#
The current Responses surface supports documented input and instructions plus controls including metadata, text response format, function tools and tool choice, parallel tool calls, streaming, maximum output tokens, sampling and stop controls, reasoning, user attribution, include controls, service tier (auto or default), prompt-cache key, truncation, and idempotency.
On eb1 models, temperature and top_p apply only when the model serving the request takes them. When it does not, Keiro leaves them out of the call and does not refuse the request.
service_tier accepts auto and default. Any other value is refused with a 400 whose error.param is service_tier, apart from "ultrafast" on eb1-frontier-preview; see Faster frontier requests.
metadata holds at most 16 pairs, with keys up to 64 characters and values up to 512 characters. A request over any of these bounds is refused with a 400.
On eb1 models, strict validation rejects unknown fields with a 400 invalid_request_error whose message and error.param name the field. So are background: true and top_logprobs above 0; background: false, top_logprobs: 0 and null are accepted and have no effect. On models outside the eb1 family, Keiro forwards any other top-level field unchanged, and that model's API accepts or rejects it; the rejection is a 400 whose message names the forwarded fields. Only keys with access to models outside the eb1 family can make those requests: any other key gets a 403 model_not_available for a model Keiro offers to other accounts, and a 404 model_not_found for any other model ID. prompt, context_management, access_programs and moderation are refused on every model with a 409 capability_conflict. safeguards is accepted and ignored. A text.format of type json_schema is accepted. JSON mode, type json_object, is accepted when the model serving the request has it. When the model serving a request cannot honor a schema or JSON mode, the request is refused instead of answered without it; see Structured output conflicts.
Streaming#
Set stream to true to receive typed server-sent events. Assemble text from response.output_text.delta, process structured items by their output index, and finish only after response.completed or response.incomplete.
from getpass import getpass
from openai import OpenAI
client = OpenAI(
base_url="https://api.keirolabs.ai/v1",
api_key=getpass("Keiro API key: "),
)
stream = client.responses.create(
model="eb1-preview",
input="Write a short haiku about reliable APIs.",
stream=True,
)
for event in stream:
if event.type == "response.output_text.delta":
print(event.delta, end="", flush=True)
A request lives as long as the model keeps working: no wall-clock limit ends a stream or a non-streaming request. See Streaming for how a run ends early and how a slow non-streaming reply is delivered, and Streaming for the event taxonomy and in-band errors.
Tools and images#
- Responses function tools use flat
nameandparametersfields and returnfunction_calloutput items; see Tool calling. - Images use
input_imageparts whoseimage_urlis an HTTPS URL or a base64 data URL; see Images and vision.input_image.file_idis refused with a400. - An
input_filepart must carry a PDF as a base64 data URL infile_data.input_file.file_idandinput_file.file_urlare refused with a400: Keiro keeps no file store to reference and does not fetch documents.
Faster frontier requests#
Set "service_tier": "ultrafast" with "model": "eb1-frontier-preview" for a faster response. This setting is available on paid self-serve plans and beta and alpha accounts. It is separate from reasoning effort and is unavailable on other models.
When the faster speed is served, it costs $20 per million input tokens, $2 per million cached input tokens, $100 per million output tokens, and $360 per million reasoning tokens. Very long prompts and requests under heavy load can run at standard speed, and those bill at standard rates. The terminal response reports what was served: service_tier is "ultrafast" or "default". In-progress streaming events omit this field.
Ultra frontier requests#
Set "reasoning": {"effort": "ultra"} with "model": "eb1-frontier-preview" to have eb1 orchestration use more models and deeper reasoning on a request. It is opt-in on each request: max does not turn it on, and the other eb1 models ignore ultra. It is available on paid self-serve plans and on alpha, beta and enterprise accounts; on any other account the request runs as a normal request. Compare it with a normal request on your own prompts before relying on it.
It costs more and turns take longer. A request can take many minutes, and a streamed one may send only keepalives before its first text; see Long requests. Billing works as on any eb1 request, and the added models and reasoning appear as reasoning tokens; see Usage and billing. The request also holds more of your spend limit while it runs. A small max_output_tokens lowers the reasoning depth, so leave it unset for the deepest reasoning. Some tool requests, including those that use provider-hosted tools or remote MCP servers, use one model at the deepest reasoning.
The x-keiro-reasoning-mode response header reports the mode the request ran in: ultra, or standard when it ran as a normal request at normal cost. reasoning.effort in the response body echoes what you sent, not what was served.