# openai cheatsheetEvery export of @deckyard/openai. Guides are listed in the introduction .
jennifer import "@deckyard/openai/" as openai;A failure throws OpenaiError (kind "openai") with the HTTP status (0 when no server answered), the error's type, code and param, and the requestId, the retryAfterMs the server asked for and its rate-limit headers (limits); a reply over the cap is kind "limit", a deadline that passed kind "timeout", a connection closed mid-reply kind "closed", a cancelled task kind "cancelled", a network failure kind "net" (a net.NetError, passed on as it is). A c argument is a Client; a request or reply is a json.Value in the API's own fields.
# ConstantsConstant Value Meaning DEFAULT_BASE_URL"https://api.openai.com/v1"the OpenAI API DEFAULT_TIMEOUT_MS600000the deadline of one attempt DEFAULT_RETRIES2retries on 408, 409, 429, 5xx, a network failure before the request was sent DEFAULT_MAX_BYTES33554432the largest reply read DEFAULT_MAX_TOOL_INPUT1048576the largest tool input a tool loop hands to a handler (and toolCalls parses) AZURE_API_VERSION"2024-10-21"the last dated GA api-version of Azure OpenAI MAX_TURNS100the most requests of one tool loop MAX_INPUTS2048the most texts of one embed
# The clientFunction Returns Does client(apiKey)Clienta client for OpenAI, the key as Authorization: Bearer; "" sends no key withBaseUrl(c, url)Clientanother OpenAI-compatible server, such as http://127.0.0.1:11434/v1 azure(endpoint, apiKey)ClientAzure OpenAI's v1 API: <endpoint>/openai/v1, api-key header azureVersioned(endpoint, apiKey, apiVersion)ClientAzure OpenAI's dated API: the deployment (the request's model) in the path, api-version on every request withOrganization(c, id)Clientsend OpenAI-Organization withProject(c, id)Clientsend OpenAI-Project withHeader(c, name, value)Clientsend one more header (a name given again, in any case, replaces it); the client's own are refused withPlainHttp(c)Clientallow plain http to another machine withTls(c, tls)Clientcertificate options (caCert, skipVerify) withTimeout(c, ms)Clientthe deadline of one attempt, 1000 to 86400000 ms withRetries(c, n)Clientretries on 408, 409, 429, 5xx, a network failure before the request was sent, 0 to 10 withMaxBytes(c, most)Clientthe largest reply, 65536 to 1073741824 bytes withMaxToolInput(c, most)Clientthe largest tool input a tool loop hands to a handler, 1024 to 1073741824 bytes; a larger one gets a toolError models(c)list of Modelthe models the server offers call(c, method, path, body)json.Valueany other request below the base URL; body JSON null for none
# ChatFunction Returns Does newRequest(model)json.Value{"model": model, "messages": []}withSystem(request, text)json.Valueset the instructions: a first system message, replacing a first system or developer one addUserText(request, text)json.Valueadd a user message addMessage(request, role, content)json.Valueadd a text message: system, developer, user, assistant addReply(request, reply)json.Valueadd the reply's message as the assistant's turn, reasoning_content included addToolResult(request, id, result)json.Valueadd a tool result (tool message); a JSON string as its text tool(name, description, parameters)json.Valuea function tool with a JSON Schema of its arguments withStrict(tool)json.Valuethe tool with strict: arguments follow the schema exactly addTool(request, tool)json.Valueoffer one tool (function, or a custom tool built with json) addTools(request, tools)json.Valueoffer several tools setSchema(request, name, schema, strict)json.Valueask for structured output (response_format json_schema) chat(c, request)json.ValuePOST /chat/completions; streaming is refusedtext(reply)stringthe first choice's text, "" for none refusal(reply)stringwhy the model refused, "" when it did not finishReason(reply)stringstop, length, tool_calls, content_filtertoolCalls(reply)list of ToolCallthe tool calls of the first choice, their arguments parsed (up to DEFAULT_MAX_TOOL_INPUT; "" as {}) usage(reply)Usagethe tokens used, cached and reasoning tokens included parsed(reply)json.Valuethe text as JSON; throws on a refusal, a cut-off reply or non-JSON
Function Returns Does runTools(c, request, handler, maxTurns)ToolRunthe tool loop; handler(name, input) returns a json.Value; stops after maxTurns requests with stopped "maxTurns" runToolsWith(c, request, handler, context, maxTurns)ToolRunthe same, handler(name, input, context) gets a read-only context toolError(message)json.Valuea result a handler returns to tell the model the call failed: {"error": message}
# EmbeddingsFunction Returns Does embeddings(c, request)json.ValuePOST /embeddings as givenembed(c, model, inputs)list of list of floatone vector per text, sent as base64 vectors(reply)list of list of floatthe vectors of a reply in index order, numbers or base64
# Types# ClientField Meaning baseUrl as stringthe API's URL without a trailing slash (azureVersioned: the endpoint) apiKey as stringthe key, "" for none; do not print a Client keyHeader as string"bearer" or "api-key"azureVersion as stringthe api-version of an azureVersioned client, "" otherwise organization as stringthe OpenAI-Organization header, "" for none project as stringthe OpenAI-Project header, "" for none headers as map of string to stringmore headers for every request tls as http.TlsOptionscertificate checks for https allowPlainHttp as boolplain http to another machine allowed timeoutMs as intthe deadline of one attempt retries as intretries on 408, 409, 429, 5xx, a network failure before the request was sent maxBytes as intthe largest reply maxToolInput as intthe largest tool input a tool loop hands to a handler
# OpenaiErrorField Meaning kind as stringalways "openai" message as stringopenai: <request>: <why> (HTTP nnn, type ..., code ...)status as intthe HTTP status, 0 when no server answered type as stringthe error's type, "" when absent code as stringthe error's code (a number as its digits), "" when absent param as stringthe request field the error is about, "" when absent requestId as stringx-request-id (Azure: apim-request-id), "" when absentretryAfterMs as intthe wait the server asked for (retry-after-ms, retry-after seconds or HTTP date), ms; 0 when none limits as map of string to stringthe rate-limit headers (x-ratelimit-*, retry-after, retry-after-ms), names lower-cased
# ModelField Meaning id as stringthe id a request names created as intUnix seconds, 0 when unknown ownedBy as stringthe owner, "" when unknown
Field Meaning id as stringthe call's id, which the result names name as stringthe tool input as json.Valuethe arguments parsed (a map, "" as {}); a custom tool's input as a JSON string; JSON null when they are not a JSON object, came as a JSON value instead of a string, or are over the cap raw as stringthe arguments as the model wrote them (JSON text; arguments sent as a JSON value, encoded), or a custom tool's input type as stringfunction or custom
# UsageField Meaning inputTokens as intthe whole prompt, cached tokens included (prompt_tokens) outputTokens as intgenerated, reasoning included (completion_tokens) totalTokens as inttotal_tokens; inputTokens + outputTokens when the server sends nonecachedTokens as intprompt tokens from the cache reasoningTokens as intgenerated tokens spent on reasoning
Field Meaning reply as json.Valuethe last reply: the one without tool calls, or the one the loop stopped at request as json.Valuethe conversation with every turn, the last reply included turns as intthe requests sent calls as intthe tool calls run usage as Usagethe tokens of all its requests, summed stopped as string"" when the model finished, "maxTurns" when the loop stopped there (the last calls answered, the conversation continuable)