Repository Public Research preview
1# Requests23Generate complete runnable files with `node scripts/openai-api.mjs scaffold <approach>`.45## Responses API anatomy67```json8{9 "model": "gpt-6.1-sol",10 "instructions": "Stable instructions.",11 "input": "The user's message, or an array of input items.",12 "reasoning": {"effort": "low"},13 "max_output_tokens": 400014}15```1617- `input` is a string, or an array of items: `{role, content}` messages (roles `user`,18 `assistant`, `developer`, `system`), `function_call`, `function_call_output`, `reasoning`.19- Message content parts: `input_text`, `input_image` (`image_url` is a URL or a data URL),20 `input_file`; assistant parts are `output_text`. `text` and `image_url` are the Chat shapes.21- Read `response.output_text`, or walk `response.output`.22- `max_output_tokens` ≥ 16, and it includes reasoning tokens.23- There is no `system` field: use `instructions` or a developer message.2425## Chat Completions (legacy surface)2627`client.chat.completions.create({model, messages, max_completion_tokens})`. Read28`choices[0].message.content`. Convert to Responses with29`node scripts/openai-api.mjs convert request.json`: it maps messages, tools, `tool_choice`,30`response_format`, token limits and reasoning effort, and lists what has no equivalent (`n`,31`stop`, `seed`, penalties, `logit_bias`).3233## Streaming3435`stream: true` yields typed events. Handle `response.output_text.delta` (`delta`),36`response.completed` (final response, with usage), `response.incomplete`, and `error`.3738## Structured outputs3940Responses:4142```json43"text": {"format": {"type": "json_schema", "name": "sentiment", "strict": true, "schema": {44 "type": "object",45 "properties": {"sentiment": {"type": "string", "enum": ["positive", "neutral", "negative"]}},46 "required": ["sentiment"], "additionalProperties": false}}}47```4849SDK helpers do this from a type: TypeScript `zodTextFormat(Schema, "name")` with50`client.responses.parse(...)`; Python `client.responses.parse(..., text_format=PydanticModel)`.51Read `response.output_parsed`. Check `status` first, and handle a `refusal` part. Verified on all5229 probed models.5354## Images and files as input5556`{"type": "input_image", "image_url": "https://… or data:image/png;base64,…"}` inside a user57message. Upload documents with `client.files.create({file, purpose: "user_data"})` and reference58them as `{"type": "input_file", "file_id": "file-…"}`.5960## Embeddings6162`client.embeddings.create({model: "text-embedding-3-small", input: [...]})` returns 1536-dimension63vectors (`text-embedding-3-large`: 3072; pass `dimensions` to shorten). Compare with cosine64similarity. For retrieval without running your own index: create a vector store, add files, then65either search it directly or give the model the `file_search` tool.6667## Batches6869Upload a JSONL file with one `{custom_id, method: "POST", url: "/v1/responses", body}` per line70(`purpose: "batch"`), then `client.batches.create({input_file_id, endpoint: "/v1/responses",71completion_window: "24h"})`. Poll until `status` is `completed`, read the output file. About half72price. Results are unordered: match on `custom_id`. Completion can take hours: in this skill's73tests a two-request batch was still `in_progress` after 12 minutes.7475## Token counting7677`client.responses.inputTokens.count({model, input, instructions, tools})` (Python:78`client.responses.input_tokens.count`) returns `input_tokens` for free. Count on the model you79will call.80