Responses endpoint

POST /v1/responses accepts input and returns an output item list. This is the interface used by the Responses request builder and compatible agent clients. Treat text, tool calls and generated media as different output item types.

Request

curl https://api.b2b-llm.com/v1/responses \
  -H "Authorization: Bearer $B2B_API_KEY" -H 'Content-Type: application/json' \
  -d '{"model":"gpt-5.4","input":[{"role":"user","content":[{"type":"input_text","text":"Summarize a safe deployment checklist."}]}],"stream":false}'

Response

{"id":"resp_example","object":"response","status":"completed","output":[{"type":"message","role":"assistant","content":[{"type":"output_text","text":"Back up, validate, deploy, then check service health."}]}]}

PDF representation

For a supported PDF input, include {"type":"input_file","filename":"brief.pdf","file_data":"data:application/pdf;base64,BASE64_PDF"} alongside the text content. Replace the placeholder with actual PDF bytes encoded as base64. Bare base64 in file_data is not this request-builder contract.

Generated images and search

A model supporting image-generation tools can receive tools: [{"type":"image_generation"}]; its generated media is returned in an image_generation_call item's result. This differs from the Images endpoint's data array. Hosted web search uses its own tool; see Responses search. Do not enable unsupported tools merely because a model supports text Responses.

A Responses image tool remains a provider-dependent Responses feature. It does not inherit the company Images operation ledger, private-file API or the single-intent dispatch fence. Do not substitute it to bypass an unavailable reviewed image route; verify that separate tool/accounting contract or use dedicated Images operations.

Session ID

Use a stable JSON session_id or X-Session-ID header for every turn of this conversation. Priority is session_id → X-Session-ID → recognized session in metadata.user_id → prompt_cache_key → opening conversation content. The identity layer is independent of provider type. Keeping the same ID does not guarantee a cache hit or disable eligible failover. See conversation identity and sticky routing for automatic fallback, scope, limits and the difference from idempotency and stored context.

The same identity is retained for streaming and for asynchronous submission where this endpoint supports it. Do not send a new paid POST merely to test a session after a timeout; check the existing request first.

For a continuation using previous_response_id, reuse your explicit conversation ID. A stored response ID and a Session ID serve different purposes; do not substitute one for the other.

An existing recognized metadata session is used without a mismatch error; an ordinary metadata.user_id is preserved, not treated as a conversation. Higher-priority explicit fields win. See the linked identity reference for formats and upstream transport limits.

A recognized metadata session takes precedence over a cache hint. Automatic identity ignores known cache_control decorations and equivalent single-text wrappers without changing the model request. A separately configured, compatible upstream session-header transport does not occupy ordinary metadata.user_id; this capability is configured by the operator, not selected by the client.