Repository Public Research preview
1/** Short, verified guidance per topic. Behavioural claims match knowledge.json (live probes). */2export const GUIDES = {3 models: `Current line-up per the official models page: gpt-6-astra (flagship, hardest work), gpt-6.1-sol (balanced default), gpt-6.1-terra (fast and efficient), gpt-6-luna (cheapest, high volume). Older and still served: gpt-5.x, gpt-4.1, gpt-4o, o3. "-pro" models (gpt-5.5-pro, gpt-5.4-pro, gpt-5.2-pro, gpt-5-pro, o3-pro) and gpt-5.3-codex are Responses-only. The models endpoint returns ids only: limits and prices come from the documentation (model_reference). Never invent an id: call list_models.`,4 responses_api: `client.responses.create({model, input, instructions?, max_output_tokens?, reasoning?, text?, tools?}). input is a string or an array of items ({role, content} messages, function_call, function_call_output, reasoning). Read response.output_text, or walk response.output (items of type message, reasoning, function_call, web_search_call, …). Check response.status: "completed", or "incomplete" with incomplete_details.reason (often max_output_tokens). max_output_tokens has a minimum of 16 and includes reasoning tokens. This is the recommended API for every current model.`,5 chat_completions: `client.chat.completions.create({model, messages, max_completion_tokens}). Still supported for most models, not for the -pro models or gpt-5.3-codex. On reasoning models the legacy max_tokens and stop are rejected; logprobs are rejected. On the gpt-6 / gpt-5.6 line, function tools work on Chat Completions only with reasoning_effort "none" (gpt-6.1-sol and gpt-6-astra have no "none": use Responses). Use chat_to_responses to convert a request.`,6 reasoning: `reasoning: {effort} on Responses; reasoning_effort on Chat Completions. Levels differ by model: gpt-6/5.6 line none|low|medium|high|xhigh|max (gpt-6.1-sol and gpt-6-astra have no "none"); gpt-5.5/5.4/5.3/5.2 none…xhigh; gpt-5.1 none…high; gpt-5/5-mini/5-nano minimal|low|medium|high; -pro models medium|high|xhigh (gpt-5-pro: high only); o3 low|medium|high; gpt-4.1/4o: no reasoning. Reasoning tokens are billed as output and count against max_output_tokens. Add reasoning: {summary: "auto"} for a summary. For stateless use (store: false) request include: ["reasoning.encrypted_content"] and pass the reasoning items back.`,7 sampling: `temperature and top_p are accepted by non-reasoning models (gpt-4.1, gpt-4o) and, on reasoning models, ONLY while the effective reasoning effort is "none". gpt-5.4/5.2/5.1 default to none, so they accept temperature until you raise the effort; the gpt-6/5.6/5.5 line needs reasoning: {effort: "none"} explicitly; gpt-6.1-sol, gpt-6-astra, gpt-5, o3 and the -pro models never accept them. Prefer instructions, text.verbosity and structured outputs for control.`,8 structured_outputs: `Responses: text: {format: {type: "json_schema", name, schema, strict: true}}. Chat Completions: response_format: {type: "json_schema", json_schema: {name, schema, strict: true}}. Strict schemas need additionalProperties: false and every property in required (model optional fields as a union with null). SDK helpers: zodTextFormat + client.responses.parse (TypeScript), text_format=PydanticModel with client.responses.parse (Python); read output_parsed. Check status first: an incomplete response has truncated JSON. Accepted by every probed model.`,9 function_calling: `Responses tools are flat: {type: "function", name, description, parameters, strict}. The model returns function_call items (name, arguments as a JSON string, call_id). Run them and append {type: "function_call_output", call_id, output} for each, together with all the response's output items (reasoning items included), then call again. tool_choice: "auto" | "required" | "none" | {type: "function", name}. parallel_tool_calls: false limits to one call per turn. Arguments are model output: validate them.`,10 hosted_tools: `Run by OpenAI, Responses API only: {type: "web_search"}, {type: "code_interpreter", container: {type: "auto"}}, {type: "file_search", vector_store_ids: […]}, {type: "image_generation"}, {type: "mcp", server_label, server_url}. Billed per call on top of tokens. Web search results carry url_citation annotations. o3 and o3-pro only accept tool_choice "auto" when hosted tools are present; gpt-5-pro and gpt-5.2-pro reject code_interpreter.`,11 state: `Three ways to keep a conversation: (1) previous_response_id — the API stores turns (store defaults to true); instructions are not carried over, resend them. (2) Manage history yourself: append response.output items to your input array. (3) store: false with encrypted reasoning for zero retention. Background mode (background: true) runs long responses asynchronously: poll responses.retrieve; it requires stored responses.`,12 caching: `Prompt caching is automatic for long prompts: repeated prefixes are billed at the cached-input rate (see model_reference). Keep stable content first. prompt_cache_key groups requests that share a prefix; prompt_cache_retention "24h" extends retention. Verify with usage.input_tokens_details.cached_tokens.`,13 streaming: `stream: true returns typed events: response.created, response.output_text.delta (delta), response.function_call_arguments.delta, response.completed (final response with usage), response.incomplete, error. Iterate with for await (TypeScript) or a for loop (Python).`,14 batches: `Upload a JSONL file (purpose "batch") with one {custom_id, method: "POST", url: "/v1/responses", body} per line, then batches.create({input_file_id, endpoint: "/v1/responses", completion_window: "24h"}). Poll until status is completed, read the output file. Half price. Results are unordered: match on custom_id.`,15 embeddings: `client.embeddings.create({model: "text-embedding-3-small", input: [..]}) → 1536-dimension vectors (3-large: 3072; pass dimensions to shorten). Compare with cosine similarity. For retrieval without your own index, use vector stores + the file_search tool.`,16 agents: `Four levels: a single Responses call; your own function-calling loop; the Agents SDK (@openai/agents, openai-agents: Agent, tools, handoffs, guardrails, tracing — it runs the loop); hosted tools for search/code/files. Start with the simplest that works. Use scaffold_app for runnable starters.`,17 errors: `400 invalid_request_error (error.param names the field, error.code e.g. unsupported_parameter / unsupported_value: run lint_request), 401 invalid key, 403 not allowed (model or feature), 404 unknown model or model not on this endpoint, 429 rate limit or quota (honour retry-after; "insufficient_quota" means billing), 500/503 server (retry with backoff). SDKs retry 408/409/429/5xx twice by default. Log the x-request-id.`,18 cost: `Price = input + cached input + output (reasoning tokens are output). Levers in order: caching (stable prefixes), smaller prompts, batch or flex (about half price), lower reasoning effort, cheaper model. Above 272K input tokens long-context rates apply on the newest models. Fast mode costs about 2×. Use estimate_cost / compare_costs; verify with response.usage.`,19};20