Responses

POST /api/v1/responses translates Responses requests into the gateway's model routing and returns Responses-shaped output. Use an inference key and an exact catalogue model ID.

Request

curl --fail-with-body https://tokenhub-api.belive.sg/api/v1/responses \
  -H "Authorization: Bearer $TOKENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen/qwen3.8-max","input":"Write a one-sentence greeting.","max_output_tokens":128}'

State, tools and media

This endpoint is stateless: resend the needed history, instructions and function tools. store: true, previous_response_id and background: true are refused. Text and URL/data image inputs are translated; input_file, audio, video and image file IDs are not. Hosted tools such as web search do not execute through this compatibility endpoint. Unsupported fields that are ignored are listed in X-TokenHub-Ignored-Fields.

Output and streaming

Read the Responses output items and usage. With stream: true, consume Responses events and require a terminal response.completed event for success. A length stop uses response.incomplete; a failure uses response.failed with response.error.code. The Chat SSE choices array and DONE marker are not this protocol. Error objects use string codes rather than Chat's numeric code field. An interrupted stream is an incomplete answer.

For client configuration, see the Codex CLI guide.

Support and limits

Responses and Messages translate the fields they support to the selected model's route. A field the route does not take is refused with 400 or listed in X-TokenHub-Ignored-Fields.

Gateway validation, defaults and response forms are in the operation index and the OpenAPI schemas.

Error codes and recovery are in Errors and recovery. Keep the request or job ID from each response: it identifies the call in Activity and for support.