> ## Documentation Index > Fetch the complete documentation index at: https://docs.beta.b3os.org/llms.txt > Use this file to discover all available pages before exploring further. # Create a response (OpenAI Responses API) A stateless subset of the OpenAI Responses API on the node's own models, for SDKs and agent frameworks that speak Responses (the OpenAI Agents SDK among them) with only the base URL changed: `input` as a string or as items (`message` with `input_text` and `input_image` parts, or `output_text` for assistant turns; `function_call`, `function_call_output` and `reasoning` items), `instructions`, function tools with `tool_choice` and `parallel_tool_calls`, structured output through `text.format` (`json_schema`, `json_object`), `reasoning.effort` (`low` and above turn the model's reasoning phase on; its text arrives in `reasoning` items), `max_output_tokens`, `temperature`, `top_p`, and the Responses event stream (`response.created` ... `response.completed`, as OpenAI sends them). Nothing is stored: send the whole conversation as `input` items each turn. `previous_response_id`, `conversation`, `prompt`, `background: true` and `truncation: "auto"` are `400 unsupported_parameter`; `store`, `metadata` (echoed), `user`, `safety_identifier`, `prompt_cache_key`, `service_tier`, `text.verbosity`, `reasoning.summary` and `include: ["reasoning.encrypted_content"]` are accepted and ignored, and every response reports `store: false`. Tools other than `function` (web search, file search, computer use, code interpreter, MCP, image generation, shell) run on OpenAI's side and are `400 unsupported_parameter`. `null` means unset for every optional parameter. Images and JSON Schemas have the limits of chat completions. A stream that fails after it started ends with an `error` event; one that fails before the first token is a plain HTTP error. The response head of a stream waits for the first generated token, so `Server-Timing` can carry `ttft`. Bills input and output tokens, with the admission and limits of chat completions (the estimated prompt plus `max_output_tokens`, else 512 tokens, settled with the real counts; an abandoned stream is billed to its last token). ` POST /v1/infer/responses ` Create a response (OpenAI Responses API) A stateless subset of the OpenAI Responses API on the node's own models, for SDKs and agent frameworks that speak Responses (the OpenAI Agents SDK among them) with only the base URL changed: `input` as a string or as items (`message` with `input_text` and `input_image` parts, or `output_text` for assistant turns; `function_call`, `function_call_output` and `reasoning` items), `instructions`, function tools with `tool_choice` and `parallel_tool_calls`, structured output through `text.format` (`json_schema`, `json_object`), `reasoning.effort` (`low` and above turn the model's reasoning phase on; its text arrives in `reasoning` items), `max_output_tokens`, `temperature`, `top_p`, and the Responses event stream (`response.created` ... `response.completed`, as OpenAI sends them). Nothing is stored: send the whole conversation as `input` items each turn. `previous_response_id`, `conversation`, `prompt`, `background: true` and `truncation: "auto"` are `400 unsupported_parameter`; `store`, `metadata` (echoed), `user`, `safety_identifier`, `prompt_cache_key`, `service_tier`, `text.verbosity`, `reasoning.summary` and `include: ["reasoning.encrypted_content"]` are accepted and ignored, and every response reports `store: false`. Tools other than `function` (web search, file search, computer use, code interpreter, MCP, image generation, shell) run on OpenAI's side and are `400 unsupported_parameter`. `null` means unset for every optional parameter. Images and JSON Schemas have the limits of chat completions. A stream that fails after it started ends with an `error` event; one that fails before the first token is a plain HTTP error. The response head of a stream waits for the first generated token, so `Server-Timing` can carry `ttft`. Bills input and output tokens, with the admission and limits of chat completions (the estimated prompt plus `max_output_tokens`, else 512 tokens, settled with the real counts; an abandoned stream is billed to its last token). ## Servers - ` https://beta-api.b3os.org ` — API (API keys and CLI tokens) - ` https://beta.b3os.org ` — Dashboard (session cookie and CSRF header; same paths) ## Authentication The operation accepts these alternatives. Schemes within one alternative are required together. ### Alternative 1 - ` apiKey `: ` http ` - HTTP scheme: ` bearer ` (b3os_sk_ API key or b3os_pat_ token) - `Authorization: Bearer `. Two credential kinds are accepted: - **API keys** `b3os_sk_<32 base32>_`, created in the dashboard or with `POST /v1/keys`. A key belongs to one project, has scopes, an optional spend cap and expiry, and is shown only once. - **CLI tokens** `b3os_pat_<32 base32>_`, issued by the device login (`b3os login`). They act for one user in the organization and project chosen at approval. Keys are stored as SHA-256 hashes. The edge exchanges them for a 60-second node token before forwarding a request to a node, so nodes never see your key. ### Alternative 2 - ` session `: ` apiKey ` - Credential: ` __Host-b3os_session ` in ` cookie ` - The dashboard session cookie on `beta.b3os.org` (host-only, `Secure`, `HttpOnly`). Requests other than `GET`/`HEAD` must also send `x-b3os-csrf: ` from `GET /v1/auth/session`; SameSite is not relied on. The cookie is never sent to `beta-api.b3os.org` or `usercontent.b3os.org`. ## Request body (required) Content type: ` application/json ` - ` value `: type ` object ` — OpenAI Responses parameters this node takes. Any other parameter is `400 unsupported_parameter` (`previous_response_id`, `conversation`, `prompt`, `top_logprobs` and `max_tool_calls` too, unless null); `null` means unset. - Required fields: ` model `, ` input ` - ` model `: type ` string ` - minLength: ` 1 ` - maxLength: ` 256 ` - ` input `: type ` unknown ` - ` anyOf alternative 1 `: type ` string ` - ` anyOf alternative 2 `: type ` array ` - ` array item `: type ` unknown ` - ` anyOf alternative 1 `: type ` object ` — A message. `user` messages take `input_text` and `input_image` parts, `system` and `developer` messages `input_text` parts (both become the system prompt, after `instructions`), `assistant` messages `output_text` and `refusal` parts. A string is one text part. - Required fields: ` role `, ` content ` - ` type `: type ` string `; nullable - enum: ` ["message",null] ` - ` role `: type ` string ` - enum: ` ["user","assistant","system","developer"] ` - ` content `: type ` unknown ` - ` anyOf alternative 1 `: type ` string ` - ` anyOf alternative 2 `: type ` array ` - ` array item `: type ` unknown ` - ` anyOf alternative 1 `: type ` object ` - Required fields: ` type `, ` text ` - ` type `: type ` string ` - enum: ` ["input_text"] ` - ` text `: type ` string ` - ` prompt_cache_breakpoint `: type ` object `; nullable — Accepted and ignored; the runtime caches prompt prefixes on its own. - ` mode `: type ` string `; nullable - enum: ` ["explicit",null] ` - ` anyOf alternative 2 `: type ` object ` - Required fields: ` type `, ` image_url ` - ` type `: type ` string ` - enum: ` ["input_image"] ` - ` image_url `: type ` string ` — `https://` (fetched by the node through its egress guard) or a base64 `data:` URL. - pattern: ` "^(https://|data:image/(png|jpeg|jpg|webp|gif);base64,)" ` - ` detail `: type ` string `; nullable — Accepted and ignored; images are resized to about 1 MP. - enum: ` ["auto","low","high","original",null] ` - ` file_id `: type ` string `; nullable — The Files API is not available on this node (null only). - enum: ` [null] ` - ` prompt_cache_breakpoint `: type ` object `; nullable — Accepted and ignored; the runtime caches prompt prefixes on its own. - ` mode `: type ` string `; nullable - enum: ` ["explicit",null] ` - ` anyOf alternative 3 `: type ` object ` - Required fields: ` type `, ` text ` - ` type `: type ` string ` - enum: ` ["output_text"] ` - ` text `: type ` string ` - ` annotations `: type ` array `; nullable - ` array item `: type ` object ` - ` logprobs `: type ` array `; nullable - ` array item `: type ` object ` - ` anyOf alternative 4 `: type ` object ` - Required fields: ` type `, ` refusal ` - ` type `: type ` string ` - enum: ` ["refusal"] ` - ` refusal `: type ` string ` - ` id `: type ` string `; nullable - ` status `: type ` string `; nullable - ` phase `: type ` string `; nullable - ` anyOf alternative 2 `: type ` object ` — A function call the model made in an earlier turn. - Required fields: ` type `, ` call_id `, ` name `, ` arguments ` - ` type `: type ` string ` - enum: ` ["function_call"] ` - ` call_id `: type ` string ` - minLength: ` 1 ` - ` name `: type ` string ` - minLength: ` 1 ` - ` arguments `: type ` string ` - ` id `: type ` string `; nullable - ` status `: type ` string `; nullable - ` caller `: type ` object `; nullable - ` namespace `: type ` string `; nullable - ` async `: type ` boolean `; nullable — Accepted and ignored. - ` anyOf alternative 3 `: type ` object ` — A function's result for an earlier `function_call` with the same `call_id` in `input`. Images in `output` reach the model as a user message after the tool results. - Required fields: ` type `, ` call_id `, ` output ` - ` type `: type ` string ` - enum: ` ["function_call_output"] ` - ` call_id `: type ` string ` - ` output `: type ` unknown ` - ` anyOf alternative 1 `: type ` string ` - ` anyOf alternative 2 `: type ` array ` - ` array item `: type ` unknown ` - ` anyOf alternative 1 `: type ` object ` - Required fields: ` type `, ` text ` - ` type `: type ` string ` - enum: ` ["input_text"] ` - ` text `: type ` string ` - ` prompt_cache_breakpoint `: type ` object `; nullable — Accepted and ignored; the runtime caches prompt prefixes on its own. - ` mode `: type ` string `; nullable - enum: ` ["explicit",null] ` - ` anyOf alternative 2 `: type ` object ` - Required fields: ` type `, ` image_url ` - ` type `: type ` string ` - enum: ` ["input_image"] ` - ` image_url `: type ` string ` — `https://` (fetched by the node through its egress guard) or a base64 `data:` URL. - pattern: ` "^(https://|data:image/(png|jpeg|jpg|webp|gif);base64,)" ` - ` detail `: type ` string `; nullable — Accepted and ignored; images are resized to about 1 MP. - enum: ` ["auto","low","high","original",null] ` - ` file_id `: type ` string `; nullable — The Files API is not available on this node (null only). - enum: ` [null] ` - ` prompt_cache_breakpoint `: type ` object `; nullable — Accepted and ignored; the runtime caches prompt prefixes on its own. - ` mode `: type ` string `; nullable - enum: ` ["explicit",null] ` - ` id `: type ` string `; nullable - ` status `: type ` string `; nullable - ` caller `: type ` object `; nullable - ` name `: type ` string `; nullable - ` namespace `: type ` string `; nullable - ` anyOf alternative 4 `: type ` object ` — Reasoning from an earlier turn; its `content` (else its `summary`) goes back to the model with that turn. `encrypted_content` is accepted and ignored. - Required fields: ` type ` - ` type `: type ` string ` - enum: ` ["reasoning"] ` - ` id `: type ` string `; nullable - ` summary `: type ` array `; nullable - ` array item `: type ` object ` - Required fields: ` type `, ` text ` - ` type `: type ` string ` - enum: ` ["reasoning_text","summary_text"] ` - ` text `: type ` string ` - ` content `: type ` array `; nullable - ` array item `: type ` object ` - Required fields: ` type `, ` text ` - ` type `: type ` string ` - enum: ` ["reasoning_text","summary_text"] ` - ` text `: type ` string ` - ` encrypted_content `: type ` string `; nullable - ` status `: type ` string `; nullable - ` instructions `: type ` string `; nullable - ` max_output_tokens `: type ` integer `; nullable - minimum: ` 1 ` - ` temperature `: type ` number `; nullable - minimum: ` 0 ` - maximum: ` 2 ` - ` top_p `: type ` number `; nullable — Nucleus sampling. `0` keeps only the most probable token (passed to the runtime as 1e-9, the same thing, since vLLM takes values above 0 only). - minimum: ` 0 ` - maximum: ` 1 ` - ` tools `: type ` array `; nullable - ` array item `: type ` object ` - Required fields: ` type `, ` name ` - ` type `: type ` string ` - enum: ` ["function"] ` - ` name `: type ` string ` — Unique within `tools`. - pattern: ` "^[A-Za-z0-9_-]{1,64}$" ` - ` description `: type ` string `; nullable - ` parameters `: type ` object `; nullable — A JSON Schema object (at most 64 KiB serialized and 32 levels deep); absent means no arguments. - ` strict `: type ` boolean `; nullable - ` allowed_callers `: type ` array `; nullable - ` array item `: type ` string ` - enum: ` ["direct"] ` - ` defer_loading `: type ` boolean `; nullable - enum: ` [false,null] ` - ` output_schema `: type ` object `; nullable — Accepted (a JSON Schema object) and ignored. - ` tool_choice `: type ` unknown ` - ` anyOf alternative 1 `: type ` string `; nullable - enum: ` ["none","auto","required"] ` - ` anyOf alternative 2 `: type ` object ` - Required fields: ` type `, ` name ` - ` type `: type ` string ` - enum: ` ["function"] ` - ` name `: type ` string ` - ` parallel_tool_calls `: type ` boolean `; nullable - ` text `: type ` object `; nullable - ` format `: type ` object `; nullable - Required fields: ` type ` - ` type `: type ` string ` - enum: ` ["text","json_object","json_schema"] ` - ` name `: type ` string ` — Required with `json_schema`. - pattern: ` "^[A-Za-z0-9_-]{1,64}$" ` - ` schema `: type ` object ` — `json_schema` only: the JSON Schema the answer matches (at most 64 KiB and 32 levels). - ` description `: type ` string `; nullable - ` strict `: type ` boolean `; nullable - ` verbosity `: type ` string `; nullable — Accepted and ignored. - enum: ` ["low","medium","high",null] ` - ` reasoning `: type ` object `; nullable - ` effort `: type ` string `; nullable — `low` and above turn the reasoning phase on; unset, `none` and `minimal` leave it off. - enum: ` ["none","minimal","low","medium","high","xhigh",null] ` - ` summary `: type ` string `; nullable — Accepted and ignored. - enum: ` ["auto","concise","detailed",null] ` - ` generate_summary `: type ` string `; nullable — Accepted and ignored. - enum: ` ["auto","concise","detailed",null] ` - ` stream `: type ` boolean `; nullable - ` stream_options `: type ` object `; nullable - ` include_obfuscation `: type ` boolean `; nullable — Accepted and ignored. - ` store `: type ` boolean `; nullable — Accepted and ignored; nothing is stored. - ` metadata `: type ` object `; nullable — Echoed in the response. - ` user `: type ` string `; nullable - ` safety_identifier `: type ` string `; nullable - ` prompt_cache_key `: type ` string `; nullable - ` service_tier `: type ` string `; nullable - ` truncation `: type ` string `; nullable — `auto` is refused: the node never drops input items. - enum: ` ["disabled",null] ` - ` background `: type ` boolean `; nullable - enum: ` [false,null] ` - ` include `: type ` array `; nullable - ` array item `: type ` string ` - enum: ` ["reasoning.encrypted_content"] ` - ` previous_response_id `: type ` string `; nullable — Null only: responses are not stored; send the conversation as `input`. - enum: ` [null] ` - ` conversation `: type ` string `; nullable — Null only. - enum: ` [null] ` - ` prompt `: type ` object `; nullable — Null only. - enum: ` [null] ` - ` top_logprobs `: type ` integer `; nullable — Null only. - enum: ` [null] ` - ` max_tool_calls `: type ` integer `; nullable — Null only. - enum: ` [null] ` ## Responses ### ` 200 ` — The response, or the event stream with `stream: true`. Content type: ` application/json ` - ` value `: type ` object ` — A response. The request's parameters are echoed as OpenAI does (`instructions`, `tools`, `tool_choice`, `text`, `reasoning`, `metadata` and the sampling parameters); `store` is always false. `status` is `incomplete`, with `incomplete_details.reason` `max_output_tokens`, when the output hit that limit. - Required fields: ` id `, ` object `, ` created_at `, ` status `, ` model `, ` output ` - ` id `: type ` string ` - ` object `: type ` string ` - enum: ` ["response"] ` - ` created_at `: type ` integer ` - ` completed_at `: type ` integer ` - ` status `: type ` string ` - enum: ` ["in_progress","completed","incomplete","failed"] ` - ` background `: type ` boolean ` - ` error `: type ` object `; nullable - ` incomplete_details `: type ` object `; nullable - ` reason `: type ` string ` - ` instructions `: type ` string `; nullable - ` max_output_tokens `: type ` integer `; nullable - ` model `: type ` string ` - ` output `: type ` array ` - ` array item `: type ` unknown ` - ` anyOf alternative 1 `: type ` object ` - Required fields: ` type `, ` id `, ` status `, ` role `, ` content ` - ` type `: type ` string ` - enum: ` ["message"] ` - ` id `: type ` string ` - ` status `: type ` string ` - enum: ` ["in_progress","completed","incomplete"] ` - ` role `: type ` string ` - enum: ` ["assistant"] ` - ` content `: type ` array ` - ` array item `: type ` object ` - Required fields: ` type `, ` text ` - ` type `: type ` string ` - enum: ` ["output_text"] ` - ` text `: type ` string ` - ` annotations `: type ` array `; nullable - ` array item `: type ` object ` - ` logprobs `: type ` array `; nullable - ` array item `: type ` object ` - ` anyOf alternative 2 `: type ` object ` - Required fields: ` type `, ` id `, ` summary ` - ` type `: type ` string ` - enum: ` ["reasoning"] ` - ` id `: type ` string ` - ` status `: type ` string ` - enum: ` ["in_progress","completed","incomplete"] ` - ` summary `: type ` array ` - ` array item `: type ` object ` - Required fields: ` type `, ` text ` - ` type `: type ` string ` - enum: ` ["reasoning_text","summary_text"] ` - ` text `: type ` string ` - ` content `: type ` array ` - ` array item `: type ` object ` - Required fields: ` type `, ` text ` - ` type `: type ` string ` - enum: ` ["reasoning_text","summary_text"] ` - ` text `: type ` string ` - ` anyOf alternative 3 `: type ` object ` - Required fields: ` type `, ` id `, ` status `, ` call_id `, ` name `, ` arguments ` - ` type `: type ` string ` - enum: ` ["function_call"] ` - ` id `: type ` string ` - ` status `: type ` string ` - enum: ` ["in_progress","completed","incomplete"] ` - ` call_id `: type ` string ` - ` name `: type ` string ` - ` arguments `: type ` string ` - ` parallel_tool_calls `: type ` boolean ` - ` previous_response_id `: type ` string `; nullable - enum: ` [null] ` - ` reasoning `: type ` object ` - ` store `: type ` boolean ` - enum: ` [false] ` - ` temperature `: type ` number `; nullable - ` text `: type ` object ` - ` tool_choice `: type ` unknown ` - ` tools `: type ` array ` - ` array item `: type ` object ` - ` top_p `: type ` number `; nullable - ` truncation `: type ` string ` - ` metadata `: type ` object ` - ` usage `: type ` object `; nullable - Required fields: ` input_tokens `, ` input_tokens_details `, ` output_tokens `, ` output_tokens_details `, ` total_tokens ` - ` input_tokens `: type ` integer ` - ` input_tokens_details `: type ` object ` - ` cached_tokens `: type ` integer ` - ` cache_write_tokens `: type ` integer ` - ` output_tokens `: type ` integer ` - ` output_tokens_details `: type ` object ` - ` reasoning_tokens `: type ` integer ` - ` total_tokens `: type ` integer ` - ` b3os `: type ` object ` — B3OS extension; OpenAI SDKs ignore it. On a stream it rides on the last chunk: the usage chunk with `stream_options.include_usage`, else the chunk with `finish_reason`. - ` route `: type ` string ` - enum: ` ["local","gateway"] ` - ` node `: type ` string ` - ` timing `: type ` object ` — Server-side milliseconds from the request head (`ttft_ms` on streams, `model_ms` without). - ` ttft_ms `: type ` number ` - ` model_ms `: type ` number ` - ` total_ms `: type ` number ` Response header ` x-request-id ` — The request ID (`req_…`). It is the `instance` of any problem and the key for `GET /v1/requests/{request_id}`. - ` value `: type ` string ` - pattern: ` "^req_[0-9a-hjkmnp-tv-z]{26}$" ` Response header ` Server-Timing ` — Phase durations in milliseconds (W3C Server Timing); the handler's phases break the request down. For a response whose body size is known, `total` runs from reading the request head to writing the response head. Streaming responses (event streams, WebSockets, chunked bodies) carry no `total` here: they report their final phases in the terminal event (`job.succeeded`, `job.failed`, `job.canceled`) or the final job. The time from the first request byte to the last response byte is recorded in the node's metrics and request log (`GET /v1/requests/{request_id}`). The edge prepends `edge_auth` and `edge_upstream`. - ` value `: type ` string ` Example: ```json { "id": "resp_01m5t5tmscqev5tf32q87tr1v5", "object": "response", "created_at": 1793001600, "completed_at": 1793001601, "status": "completed", "background": false, "error": null, "incomplete_details": null, "instructions": "You are a concise assistant.", "max_output_tokens": null, "model": "b3os/qwen3.5-9b", "output": [ { "type": "function_call", "id": "fc_01m5t5tmscqev5tf32q87tr1v5_0", "status": "completed", "call_id": "call_7f3a", "name": "get_weather", "arguments": "{\"city\":\"Eugene\"}" } ], "parallel_tool_calls": true, "previous_response_id": null, "reasoning": { "effort": null, "summary": null }, "store": false, "temperature": null, "text": { "format": { "type": "text" }, "verbosity": "medium" }, "tool_choice": "auto", "tools": [ { "type": "function", "name": "get_weather", "description": "Current weather for a city.", "parameters": { "type": "object", "properties": { "city": { "type": "string" } }, "required": [ "city" ] }, "strict": true } ], "top_p": null, "truncation": "disabled", "metadata": {}, "usage": { "input_tokens": 182, "input_tokens_details": { "cached_tokens": 0, "cache_write_tokens": 0 }, "output_tokens": 18, "output_tokens_details": { "reasoning_tokens": 0 }, "total_tokens": 200 }, "b3os": { "route": "local", "node": "n1", "timing": { "model_ms": 96.4, "total_ms": 97.1 } } } ``` ### ` 400 ` — The request is invalid (`invalid_request`, `unsupported_parameter`, `context_length_exceeded`). Content type: ` application/json ` - ` value `: type ` object ` — The OpenAI error body. `code` is the B3OS error code; `x-request-id` carries the request ID. - Required fields: ` error ` - ` error `: type ` object ` - Required fields: ` message `, ` type `, ` param `, ` code ` - ` message `: type ` string ` - ` type `: type ` string ` — `invalid_request_error`, `authentication_error`, `permission_error`, `rate_limit_error` or `server_error`. - ` param `: type ` string `; nullable - ` code `: type ` string `; nullable Response header ` x-request-id ` — The request ID (`req_…`). It is the `instance` of any problem and the key for `GET /v1/requests/{request_id}`. - ` value `: type ` string ` - pattern: ` "^req_[0-9a-hjkmnp-tv-z]{26}$" ` Response header ` Server-Timing ` — Phase durations in milliseconds (W3C Server Timing); the handler's phases break the request down. For a response whose body size is known, `total` runs from reading the request head to writing the response head. Streaming responses (event streams, WebSockets, chunked bodies) carry no `total` here: they report their final phases in the terminal event (`job.succeeded`, `job.failed`, `job.canceled`) or the final job. The time from the first request byte to the last response byte is recorded in the node's metrics and request log (`GET /v1/requests/{request_id}`). The edge prepends `edge_auth` and `edge_upstream`. - ` value `: type ` string ` Example: ```json { "error": { "message": "prompt_logprobs is not supported on this node", "type": "invalid_request_error", "param": "prompt_logprobs", "code": "unsupported_parameter" } } ``` ### ` 401 ` — Missing or invalid credentials (`unauthorized`). Content type: ` application/json ` - ` value `: type ` object ` — The OpenAI error body. `code` is the B3OS error code; `x-request-id` carries the request ID. - Required fields: ` error ` - ` error `: type ` object ` - Required fields: ` message `, ` type `, ` param `, ` code ` - ` message `: type ` string ` - ` type `: type ` string ` — `invalid_request_error`, `authentication_error`, `permission_error`, `rate_limit_error` or `server_error`. - ` param `: type ` string `; nullable - ` code `: type ` string `; nullable Response header ` x-request-id ` — The request ID (`req_…`). It is the `instance` of any problem and the key for `GET /v1/requests/{request_id}`. - ` value `: type ` string ` - pattern: ` "^req_[0-9a-hjkmnp-tv-z]{26}$" ` Response header ` Server-Timing ` — Phase durations in milliseconds (W3C Server Timing); the handler's phases break the request down. For a response whose body size is known, `total` runs from reading the request head to writing the response head. Streaming responses (event streams, WebSockets, chunked bodies) carry no `total` here: they report their final phases in the terminal event (`job.succeeded`, `job.failed`, `job.canceled`) or the final job. The time from the first request byte to the last response byte is recorded in the node's metrics and request log (`GET /v1/requests/{request_id}`). The edge prepends `edge_auth` and `edge_upstream`. - ` value `: type ` string ` Example: ```json { "error": { "message": "API key checksum does not match; check that the whole key was copied", "type": "authentication_error", "param": null, "code": "unauthorized" } } ``` ### ` 403 ` — The key lacks `infer:run` or `infer:read` (`forbidden`), or the egress guard refused an image URL (`egress_denied`). Content type: ` application/json ` - ` value `: type ` object ` — The OpenAI error body. `code` is the B3OS error code; `x-request-id` carries the request ID. - Required fields: ` error ` - ` error `: type ` object ` - Required fields: ` message `, ` type `, ` param `, ` code ` - ` message `: type ` string ` - ` type `: type ` string ` — `invalid_request_error`, `authentication_error`, `permission_error`, `rate_limit_error` or `server_error`. - ` param `: type ` string `; nullable - ` code `: type ` string `; nullable Response header ` x-request-id ` — The request ID (`req_…`). It is the `instance` of any problem and the key for `GET /v1/requests/{request_id}`. - ` value `: type ` string ` - pattern: ` "^req_[0-9a-hjkmnp-tv-z]{26}$" ` Response header ` Server-Timing ` — Phase durations in milliseconds (W3C Server Timing); the handler's phases break the request down. For a response whose body size is known, `total` runs from reading the request head to writing the response head. Streaming responses (event streams, WebSockets, chunked bodies) carry no `total` here: they report their final phases in the terminal event (`job.succeeded`, `job.failed`, `job.canceled`) or the final job. The time from the first request byte to the last response byte is recorded in the node's metrics and request log (`GET /v1/requests/{request_id}`). The edge prepends `edge_auth` and `edge_upstream`. - ` value `: type ` string ` ### ` 404 ` — The model is not served on this node (`model_not_available`). Content type: ` application/json ` - ` value `: type ` object ` — The OpenAI error body. `code` is the B3OS error code; `x-request-id` carries the request ID. - Required fields: ` error ` - ` error `: type ` object ` - Required fields: ` message `, ` type `, ` param `, ` code ` - ` message `: type ` string ` - ` type `: type ` string ` — `invalid_request_error`, `authentication_error`, `permission_error`, `rate_limit_error` or `server_error`. - ` param `: type ` string `; nullable - ` code `: type ` string `; nullable Response header ` x-request-id ` — The request ID (`req_…`). It is the `instance` of any problem and the key for `GET /v1/requests/{request_id}`. - ` value `: type ` string ` - pattern: ` "^req_[0-9a-hjkmnp-tv-z]{26}$" ` Response header ` Server-Timing ` — Phase durations in milliseconds (W3C Server Timing); the handler's phases break the request down. For a response whose body size is known, `total` runs from reading the request head to writing the response head. Streaming responses (event streams, WebSockets, chunked bodies) carry no `total` here: they report their final phases in the terminal event (`job.succeeded`, `job.failed`, `job.canceled`) or the final job. The time from the first request byte to the last response byte is recorded in the node's metrics and request log (`GET /v1/requests/{request_id}`). The edge prepends `edge_auth` and `edge_upstream`. - ` value `: type ` string ` Example: ```json { "error": { "message": "gpt-5 is not served on this node; set \"route\":\"gateway\" to use the B3IQ gateway", "type": "invalid_request_error", "param": "model", "code": "model_not_available" } } ``` ### ` 413 ` — The request body exceeds the model's `max_request_bytes` (`payload_too_large`). Content type: ` application/json ` - ` value `: type ` object ` — The OpenAI error body. `code` is the B3OS error code; `x-request-id` carries the request ID. - Required fields: ` error ` - ` error `: type ` object ` - Required fields: ` message `, ` type `, ` param `, ` code ` - ` message `: type ` string ` - ` type `: type ` string ` — `invalid_request_error`, `authentication_error`, `permission_error`, `rate_limit_error` or `server_error`. - ` param `: type ` string `; nullable - ` code `: type ` string `; nullable Response header ` x-request-id ` — The request ID (`req_…`). It is the `instance` of any problem and the key for `GET /v1/requests/{request_id}`. - ` value `: type ` string ` - pattern: ` "^req_[0-9a-hjkmnp-tv-z]{26}$" ` Response header ` Server-Timing ` — Phase durations in milliseconds (W3C Server Timing); the handler's phases break the request down. For a response whose body size is known, `total` runs from reading the request head to writing the response head. Streaming responses (event streams, WebSockets, chunked bodies) carry no `total` here: they report their final phases in the terminal event (`job.succeeded`, `job.failed`, `job.canceled`) or the final job. The time from the first request byte to the last response byte is recorded in the node's metrics and request log (`GET /v1/requests/{request_id}`). The edge prepends `edge_auth` and `edge_upstream`. - ` value `: type ` string ` Example: ```json { "error": { "message": "Request body is 12582912 bytes; this model accepts at most 10485760", "type": "invalid_request_error", "param": null, "code": "payload_too_large" } } ``` ### ` 415 ` — The body is not JSON (`unsupported_media_type`): send `Content-Type: application/json`. Content type: ` application/json ` - ` value `: type ` object ` — The OpenAI error body. `code` is the B3OS error code; `x-request-id` carries the request ID. - Required fields: ` error ` - ` error `: type ` object ` - Required fields: ` message `, ` type `, ` param `, ` code ` - ` message `: type ` string ` - ` type `: type ` string ` — `invalid_request_error`, `authentication_error`, `permission_error`, `rate_limit_error` or `server_error`. - ` param `: type ` string `; nullable - ` code `: type ` string `; nullable Response header ` x-request-id ` — The request ID (`req_…`). It is the `instance` of any problem and the key for `GET /v1/requests/{request_id}`. - ` value `: type ` string ` - pattern: ` "^req_[0-9a-hjkmnp-tv-z]{26}$" ` Response header ` Server-Timing ` — Phase durations in milliseconds (W3C Server Timing); the handler's phases break the request down. For a response whose body size is known, `total` runs from reading the request head to writing the response head. Streaming responses (event streams, WebSockets, chunked bodies) carry no `total` here: they report their final phases in the terminal event (`job.succeeded`, `job.failed`, `job.canceled`) or the final job. The time from the first request byte to the last response byte is recorded in the node's metrics and request log (`GET /v1/requests/{request_id}`). The edge prepends `edge_auth` and `edge_upstream`. - ` value `: type ` string ` Example: ```json { "error": { "message": "expected Content-Type: application/json", "type": "invalid_request_error", "param": null, "code": "unsupported_media_type" } } ``` ### ` 429 ` — A limit applies (`rate_limited` for requests, tokens or remote image bytes per minute, `concurrency_limited` for requests in flight for the organization, `quota_exceeded`; `credits_exhausted` arrives as 402). Content type: ` application/json ` - ` value `: type ` object ` — The OpenAI error body. `code` is the B3OS error code; `x-request-id` carries the request ID. - Required fields: ` error ` - ` error `: type ` object ` - Required fields: ` message `, ` type `, ` param `, ` code ` - ` message `: type ` string ` - ` type `: type ` string ` — `invalid_request_error`, `authentication_error`, `permission_error`, `rate_limit_error` or `server_error`. - ` param `: type ` string `; nullable - ` code `: type ` string `; nullable Response header ` x-request-id ` — The request ID (`req_…`). It is the `instance` of any problem and the key for `GET /v1/requests/{request_id}`. - ` value `: type ` string ` - pattern: ` "^req_[0-9a-hjkmnp-tv-z]{26}$" ` Response header ` Server-Timing ` — Phase durations in milliseconds (W3C Server Timing); the handler's phases break the request down. For a response whose body size is known, `total` runs from reading the request head to writing the response head. Streaming responses (event streams, WebSockets, chunked bodies) carry no `total` here: they report their final phases in the terminal event (`job.succeeded`, `job.failed`, `job.canceled`) or the final job. The time from the first request byte to the last response byte is recorded in the node's metrics and request log (`GET /v1/requests/{request_id}`). The edge prepends `edge_auth` and `edge_upstream`. - ` value `: type ` string ` Response header ` Retry-After ` — Seconds to wait before retrying or polling again. - ` value `: type ` integer ` - minimum: ` 0 ` Response header ` RateLimit-Limit ` — Requests allowed in the current window for the limit that applies to this operation. - ` value `: type ` integer ` Response header ` RateLimit-Remaining ` — Requests left in the current window. - ` value `: type ` integer ` Response header ` RateLimit-Reset ` — Seconds until the current window resets. - ` value `: type ` integer ` Example: ```json { "error": { "message": "200000 tokens per minute allowed on b3os/qwen3.5-9b; retry in 9 seconds", "type": "rate_limit_error", "param": null, "code": "rate_limited" } } ``` ### ` 500 ` — Something failed inside B3OS (`internal`). Content type: ` application/json ` - ` value `: type ` object ` — The OpenAI error body. `code` is the B3OS error code; `x-request-id` carries the request ID. - Required fields: ` error ` - ` error `: type ` object ` - Required fields: ` message `, ` type `, ` param `, ` code ` - ` message `: type ` string ` - ` type `: type ` string ` — `invalid_request_error`, `authentication_error`, `permission_error`, `rate_limit_error` or `server_error`. - ` param `: type ` string `; nullable - ` code `: type ` string `; nullable Response header ` x-request-id ` — The request ID (`req_…`). It is the `instance` of any problem and the key for `GET /v1/requests/{request_id}`. - ` value `: type ` string ` - pattern: ` "^req_[0-9a-hjkmnp-tv-z]{26}$" ` Response header ` Server-Timing ` — Phase durations in milliseconds (W3C Server Timing); the handler's phases break the request down. For a response whose body size is known, `total` runs from reading the request head to writing the response head. Streaming responses (event streams, WebSockets, chunked bodies) carry no `total` here: they report their final phases in the terminal event (`job.succeeded`, `job.failed`, `job.canceled`) or the final job. The time from the first request byte to the last response byte is recorded in the node's metrics and request log (`GET /v1/requests/{request_id}`). The edge prepends `edge_auth` and `edge_upstream`. - ` value `: type ` string ` Example: ```json { "error": { "message": "internal error (request req_01m5t4yg394wegr3j4y01qb363)", "type": "server_error", "param": null, "code": "internal" } } ``` ### ` 503 ` — The model runtime, the voice service or the B3IQ gateway route is restarting, overloaded or not set up on this node (`infer_backend_unavailable`, `capacity_unavailable`), or the node is unavailable (`node_unavailable`). Content type: ` application/json ` - ` value `: type ` object ` — The OpenAI error body. `code` is the B3OS error code; `x-request-id` carries the request ID. - Required fields: ` error ` - ` error `: type ` object ` - Required fields: ` message `, ` type `, ` param `, ` code ` - ` message `: type ` string ` - ` type `: type ` string ` — `invalid_request_error`, `authentication_error`, `permission_error`, `rate_limit_error` or `server_error`. - ` param `: type ` string `; nullable - ` code `: type ` string `; nullable Response header ` x-request-id ` — The request ID (`req_…`). It is the `instance` of any problem and the key for `GET /v1/requests/{request_id}`. - ` value `: type ` string ` - pattern: ` "^req_[0-9a-hjkmnp-tv-z]{26}$" ` Response header ` Server-Timing ` — Phase durations in milliseconds (W3C Server Timing); the handler's phases break the request down. For a response whose body size is known, `total` runs from reading the request head to writing the response head. Streaming responses (event streams, WebSockets, chunked bodies) carry no `total` here: they report their final phases in the terminal event (`job.succeeded`, `job.failed`, `job.canceled`) or the final job. The time from the first request byte to the last response byte is recorded in the node's metrics and request log (`GET /v1/requests/{request_id}`). The edge prepends `edge_auth` and `edge_upstream`. - ` value `: type ` string ` Response header ` Retry-After ` — Seconds to wait before retrying or polling again. - ` value `: type ` integer ` - minimum: ` 0 ` Example: ```json { "error": { "message": "The model runtime on n1 is restarting; retry in 5 seconds", "type": "server_error", "param": null, "code": "infer_backend_unavailable" } } ``` ## Request examples ### cURL ```curl curl -X POST 'https://beta-api.b3os.org/v1/infer/responses' \ -H 'Authorization: Bearer YOUR_API_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "model": "string", "input": "string", "instructions": "string", "max_output_tokens": 1, "temperature": 0, "top_p": 0, "tools": [ { "type": "function", "name": "string", "description": "string", "parameters": {}, "strict": true, "allowed_callers": [ "direct" ], "defer_loading": false, "output_schema": {} } ], "tool_choice": "none", "parallel_tool_calls": true, "text": { "format": { "type": "text", "name": "string", "schema": {}, "description": "string", "strict": true }, "verbosity": "low" }, "reasoning": { "effort": "none", "summary": "auto", "generate_summary": "auto" }, "stream": true, "stream_options": { "include_obfuscation": true }, "store": true, "metadata": {}, "user": "string", "safety_identifier": "string", "prompt_cache_key": "string", "service_tier": "string", "truncation": "disabled", "background": false, "include": [ "reasoning.encrypted_content" ], "previous_response_id": null, "conversation": null, "prompt": null, "top_logprobs": null, "max_tool_calls": null }' ``` ### JavaScript ```javascript const response = await fetch('https://beta-api.b3os.org/v1/infer/responses', { method: 'POST', headers: { "Authorization": "Bearer YOUR_API_TOKEN", "Content-Type": "application/json" }, body: JSON.stringify({ "model": "string", "input": "string", "instructions": "string", "max_output_tokens": 1, "temperature": 0, "top_p": 0, "tools": [ { "type": "function", "name": "string", "description": "string", "parameters": {}, "strict": true, "allowed_callers": [ "direct" ], "defer_loading": false, "output_schema": {} } ], "tool_choice": "none", "parallel_tool_calls": true, "text": { "format": { "type": "text", "name": "string", "schema": {}, "description": "string", "strict": true }, "verbosity": "low" }, "reasoning": { "effort": "none", "summary": "auto", "generate_summary": "auto" }, "stream": true, "stream_options": { "include_obfuscation": true }, "store": true, "metadata": {}, "user": "string", "safety_identifier": "string", "prompt_cache_key": "string", "service_tier": "string", "truncation": "disabled", "background": false, "include": [ "reasoning.encrypted_content" ], "previous_response_id": null, "conversation": null, "prompt": null, "top_logprobs": null, "max_tool_calls": null }) }); const data = await response.json(); console.log(data); ``` ### Python ```python import requests headers = { 'Authorization': 'Bearer YOUR_API_TOKEN' } response = requests.post('https://beta-api.b3os.org/v1/infer/responses', headers=headers, json={ "model": "string", "input": "string", "instructions": "string", "max_output_tokens": 1, "temperature": 0, "top_p": 0, "tools": [ { "type": "function", "name": "string", "description": "string", "parameters": {}, "strict": true, "allowed_callers": [ "direct" ], "defer_loading": false, "output_schema": {} } ], "tool_choice": "none", "parallel_tool_calls": true, "text": { "format": { "type": "text", "name": "string", "schema": {}, "description": "string", "strict": true }, "verbosity": "low" }, "reasoning": { "effort": "none", "summary": "auto", "generate_summary": "auto" }, "stream": true, "stream_options": { "include_obfuscation": true }, "store": true, "metadata": {}, "user": "string", "safety_identifier": "string", "prompt_cache_key": "string", "service_tier": "string", "truncation": "disabled", "background": false, "include": [ "reasoning.encrypted_content" ], "previous_response_id": null, "conversation": null, "prompt": null, "top_logprobs": null, "max_tool_calls": null }) print(response.json()) ```