Repository Public Research preview
1# Requests23All examples use the official SDKs. Generate complete runnable files with4`node scripts/claude-api.mjs scaffold <approach>`.56## Anatomy78```json9{10 "model": "claude-opus-5-5",11 "max_tokens": 16000,12 "system": "Stable instructions. Keep volatile values out of here.",13 "thinking": {"type": "adaptive"},14 "output_config": {"effort": "medium"},15 "messages": [{"role": "user", "content": "…"}]16}17```1819- `messages` starts with a `user` turn. Roles are `user` and `assistant`; tool results travel in a20 `user` message as `tool_result` blocks (there is no `tool` role).21- `content` is a string or an array of blocks: `text`, `image`, `document`, `tool_use`,22 `tool_result`, `thinking`.23- Default `max_tokens`: about 16000 without streaming, up to 64000 with streaming. Lower only for a24 reason (a classifier needs ~256).2526## Streaming2728TypeScript: `client.messages.stream({...})`, `stream.on("text", …)`, `await stream.finalMessage()`.29Python: `with client.messages.stream(...) as s:` → `s.text_stream`, `s.get_final_message()`.30Use the helper's final message instead of reassembling events yourself.3132## Structured outputs3334```json35"output_config": {"format": {"type": "json_schema", "schema": {36 "type": "object",37 "properties": {"sentiment": {"type": "string", "enum": ["positive", "neutral", "negative"]}},38 "required": ["sentiment"], "additionalProperties": false}}}39```4041The reply's text block is JSON matching the schema when `stop_reason` is `end_turn`. Check that42first: `max_tokens` leaves truncated JSON. Verified on all 15 probed models. Cannot be combined43with citations.4445## Images, PDFs, files4647- Image: `{"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": "…"}}`.48- PDF: `{"type": "document", "source": {"type": "base64", "media_type": "application/pdf", "data": "…"}}`,49 placed before the question.50- Plain text document with citations:51 `{"type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "…"}, "citations": {"enabled": true}}`52 — cited text blocks then carry a `citations` array with `cited_text`.53- Files API: `client.files.upload(...)` → `file_id`, referenced as54 `{"type": "document", "source": {"type": "file", "file_id": "file_…"}}` (or `"type": "image"`).55 Also `files.list`, `files.retrieveMetadata` / `retrieve_metadata`, `files.delete`.5657## Batches5859`client.messages.batches.create({requests: [{custom_id, params}]})`, poll `retrieve(id)` until60`processing_status` is `"ended"`, then iterate `results(id)`. Half price. Results come in any61order: match on `custom_id`. Each result is `succeeded`, `errored`, `canceled` or `expired`.6263## Token counting6465`client.messages.countTokens({model, messages, system, tools})` (Python: `count_tokens`) returns66`input_tokens` for free. Count on the model you will call: the same text costs a different number67of tokens on different generations (the same 7-word prompt measured 14 tokens on 4.5/4.6 models,6816–21 on newer ones). Do not use a third-party tokenizer.69