OpenAI Parity

Vista mirroruje oficjalne OpenAI Responses API (vista-api/openapi.json), zachowując byte-for-byte kompatybilność.

Source of truth

platform.openai.com/docs/api-reference/responses

Authentication & headers

Header	Opis
Authorization: Bearer <OPENAI_API_KEY>	Obowiązkowy
OpenAI-Organization	Opcjonalny routing
OpenAI-Project	Opcjonalny routing
X-Client-Request-Id	Observability (client generated)
x-request-id	OpenAI response header
x-ratelimit-*	Rate-limit metadata

REST endpoints

Endpoint	Method	Purpose	Vista mapping
/v1/responses	POST	Create model response	paths['/v1/responses']
/v1/responses/{id}	GET/DELETE	Fetch/remove stored response	paths['/v1/responses/{response_id}']
/v1/responses/{id}/cancel	POST	Cancel background/streaming runs	same
/v1/responses/{id}/events	GET + SSE	Replay deltas or attach live	same
/v1/responses/{id}/input_items	GET	Inspect input lineage	same
/v1/responses/input_tokens	POST	Preflight token counts	same

Request payload - input types

Type	Opis
input_text	UTF-8 strings + optional mime type
input_image	base64 or URL + detail flag (low/high)
input_audio	PCM/WAV/Ogg bytes + sample_rate_hz, channels, language_hint
input_file	Arbitrary binary (base64) + filename/mime
tool_result	Structured output returned after tool run

Request payload - knobs

Field	Description
instructions	System prompt or array of input_text system items
conversation	Conversation ID or explicit list of historical items
stream / stream_options	Streaming toggles (channels + obfuscation)
tool_choice	auto, none, or forced { type, name }
tools[]	Built-in (web_search, file_search, etc.), custom functions, or MCP definitions
output_audio	Format/voice/sample-rate for TTS responses
reasoning	effort, enable_chain_of_thought for o-series
store	Whether response should persist for future GETs

Streaming events

SSE protocol emits typed events with type, sequence_number, and contextual IDs:

Event	Purpose
response.output_text.delta / .done	Incremental assistant text
response.output_audio.delta	Base64 audio chunks (when output_audio requested)
response.tool_call.delta / .done	Streaming tool call arguments
response.refusal.delta / .done	Refusal text stream
response.error	Terminal failure

Vista mapuje te eventy 1:1 przez ResponseEvent - frontend renderer traktuje OpenAI i Vista identycznie.

Conversations & input lineage

Endpoint	Purpose
GET /v1/responses/{id}/input_items	Returns exact items provided when response was created
GET/POST /v1/conversations/{conversation_id}/items	Append or fetch multi-turn history

Pagination: limit, after, order z envelope object: 'list'.

Tooling + MCP

• Tools opisane JSON Schema dla arguments (identycznie jak OpenAI tools)
• Built-ins: web_search, file_search, code_interpreter, computer
• MCP: type: 'mcp' definitions → server issues MCP RPCs

Speech & audio

OpenAI Responses API może ingestować/outputować audio, ale Vista trzyma premium STT pod /stt/v1/....

Envelope dla response.output_audio.delta matchuje format OpenAI - clients mogą swapować providery bez zmian kodu.

Error model

Każdy endpoint zwraca na failure:

{
  "error": {
    "code": "invalid_request_error",
    "message": "...",
    "param": "...",
    "type": "..."
  }
}

Kody: invalid_request_error, rate_limit_error, etc. - identyczne z OpenAI dla predykowalnych contract testów.

Kluczowe zasady

Nie driftuj od OpenAI

Ta dokumentacja to mapa między OpenAI docs a vista-api/openapi.json. Authoritative schema pozostaje JSON spec.

1. Każda zmiana w Vista API musi być backwards-compatible z OpenAI
2. Contract testy porównują Vista ↔ OpenAI behawior
3. Frontend renderer nie rozróżnia providerów