# Autarcho documentation https://autarcho.com/docs/ # Documentation Autarcho serves open models through an OpenAI-compatible API. You pay for the tokens a model generates and nothing for the prompt, so a long document costs whatever the answer costs. ## Getting started The base URL is https://api.autarcho.com/v1. Every request carries a key in the Authorization header. A key is ak_ followed by 64 hex characters, and you make it yourself rather than signing up for it. ``` printf 'ak_%s\n' "$(openssl rand -hex 32)" ``` Only a hash of the key is stored, so the key is the only copy. Save it before you close the terminal. ## Add credit Credit is bought with USDC on Solana. Ask for a payment request, pay the address it returns, and the balance appears under that key once the transfer confirms. ``` curl -s -X POST "https://api.autarcho.com/deposits/intent?amount=10" \ -H "Authorization: Bearer ak_..." ``` The response includes a solana_pay_url you can open in any Solana wallet. The payment walkthrough covers the whole step, including what to do if the credit does not arrive. ## Send a request ``` curl -s https://api.autarcho.com/v1/chat/completions \ -H "Authorization: Bearer ak_..." \ -H "content-type: application/json" \ -d '{ "model": "", "messages": [{ "role": "user", "content": "Hello" }], "stream": true }' ``` The same request through the OpenAI SDK, which needs only a new base URL and key. ``` from openai import OpenAI client = OpenAI(base_url="https://api.autarcho.com/v1", api_key="ak_...") stream = client.chat.completions.create( model="", messages=[{"role": "user", "content": "Hello"}], stream=True, ) for chunk in stream: print(chunk.choices[0].delta.content or "", end="") ``` ## Find a model GET /v1/models lists the models available to your key. A model id is the hash of the file, or an alias for it, and either works in a request. ``` curl -s https://api.autarcho.com/v1/models \ -H "Authorization: Bearer ak_..." ``` Prices are set per model and can change. To read one without a key, ask for it directly: ``` curl -s "https://api.autarcho.com/model//price?for_client=true" ``` The models page has a price and a file size for each one. ## Next - API reference: every parameter, and what happens with a stream. - Billing: what a request costs and how to retry without paying twice. - Batch requests: send a list of requests and collect the answers later. A program that reads one file: llms-full.txt is this documentation as plain text. # API reference The API follows the OpenAI chat-completions shape. It is a subset: anything outside it is refused with an error that names the parameter, rather than accepted and changed without saying so. The machine-readable version of this page is api.autarcho.com/openapi.yaml, an OpenAPI 3.1 document. It needs no key, so a client generator, an editor plugin or an agent tool can be pointed at it before anything exists. ## From your stack Anything that speaks the OpenAI chat shape points at this base URL. Two that people ask about, with the form that works today: ``` from litellm import completion # LiteLLM routes any OpenAI-compatible endpoint through its openai/ prefix. # The model is the id from GET /v1/models, or its 64-character hash. response = completion( model="openai/", api_base="https://api.autarcho.com/v1", api_key="ak_<64 hex>", messages=[{"role": "user", "content": "hello"}], ) print(response.choices[0].message.content) ``` ``` from langchain_openai import ChatOpenAI llm = ChatOpenAI( model="", base_url="https://api.autarcho.com/v1", api_key="ak_<64 hex>", ) print(llm.invoke("hello").content) ``` Use the hash when the call has to mean the same model next month. An alias is a convenience and a model owner can point it somewhere else; the hash is the file. A model that has left the verified catalogue answers 404 model_not_found, which is final, while a model with no operator online answers 503, which is worth retrying. The price per generated token is GET /model/{hash}/price, so cost tracking can read it rather than hard-code it. ## For agents There is an MCP server for agent clients: npx autarcho-mcp. It exposes list_models, get_price, chat_completion and get_balance, needs only AUTARCHO_API_KEY, and caps one completion at 2048 generated tokens. Source and configuration blocks: npmjs.com/package/autarcho-mcp. ## Endpoints Method and path | What it does | POST /v1/chat/completions | One completion for one conversation. | GET /v1/models | The models available to your key. | GET /v1/models/{model} | One model by id or alias. | GET /model/{hash}/price | A price. Add ?for_client=true, and no key is needed. | POST /v1/batches | A list of requests. See Batch requests. | ## Authentication Send Authorization: Bearer ak_<64 hex> on every call except the price lookup. Keys are generated by your client, not issued through a sign-up form: there is no email verification and no identity check. A key in that format that has no credit yet is a 402, the same as a key whose balance is spent. A missing key, or a value that could not be a key at all, is a 401. ## Chat completions Field | Type | Notes | model | string | Required. A model id or an alias. | messages | array | Required. Roles system, user and assistant, with string content. | stream | boolean | Server-sent events instead of one response. Default false. | max_tokens | integer | Upper bound on the tokens generated. | temperature, top_p, top_k, min_p | number | Sampling. Each is validated and refused if out of range. | presence_penalty, frequency_penalty | number | Between -2 and 2. | logit_bias | object | Token id to a bias between -100 and 100. Up to 1024 entries. | dry_multiplier and the other dry_* fields | number | Penalises repeated sequences, which breaks loops a token penalty cannot see. | response_format | object | text, json_object or json_schema. | tools, tool_choice | array, value | Function calling. See below. | max_price_per_token_micro_usdc | integer | Refuse the request if the price is above this, before anything is charged. | The response carries the text, why generation stopped, and what it cost. ``` { "choices": [ { "message": { "role": "assistant", "content": "Hello." }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 0, "completion_tokens": 6, "cost_micro_usdc": 6 } } ``` finish_reason is stop when the model finished, length when it reached max_tokens, and tool_calls when it asked for a function. prompt_tokens is always zero because the prompt is not billed. ## Streaming With stream: true the response is server-sent events, one piece of text per event, ending with data: [DONE]. ``` data: {"choices":[{"delta":{"content":"Hel"}}]} data: {"choices":[{"delta":{"content":"lo"}}]} data: {"choices":[{"delta":{},"finish_reason":"stop"}]} data: [DONE] ``` The first event can take a while on a model that is not loaded yet, which is the reason to stream: you see progress instead of waiting on one response. Do not set a timeout of a few seconds on the first event. ## Tool calls Pass tools in the OpenAI shape and the model can answer with a call instead of text. tool_choice takes auto, required, none, or a named function. ``` { "choices": [ { "message": { "role": "assistant", "content": null, "tool_calls": [ { "id": "call_1", "type": "function", "function": { "name": "get_weather", "arguments": "{\"city\":\"Oslo\"}" } } ] }, "finish_reason": "tool_calls" } ] } ``` Send the result back as a user message and ask again. A streamed call arrives complete at the end of the stream, because a name and its arguments cannot be split before both exist. ## Structured output response_format with json_object returns a JSON object. With json_schema the output follows your schema, and when the schema admits only a finite set of documents generation stops on its own: the text parses and finish_reason is stop. An open object can keep growing until max_tokens, so give it a realistic budget. ## Reasoning models A model that thinks before it answers returns the thinking in reasoning_content, separate from content. Both are part of the generated token count. ## Parameters that are refused These return 400 with unsupported_parameter rather than being ignored: stop, seed, logprobs, n above 1, image or audio content, and anything outside the table above. ## Errors An error body carries a code, a message, and a retryable flag, so a client can decide without matching on prose. Status | Code | What to do | 400 | unsupported_parameter | Change or remove the parameter named in the message. | 401 | invalid_api_key | The key is missing, retired, or not in the key format. Add credit to a retired key and it is still refused: use its replacement. | 402 | insufficient_quota | The price is above your limit, or the key has no credit yet. Nothing was charged. | 404 | model_not_found | No such model. GET /v1/models has the list. | 409 | idempotency_in_progress | Wait for Retry-After and ask again. | 429 | rate_limited | Slow down, then retry with backoff. | 503 | unavailable | The request could not be served this time. Retry with backoff. | Billing explains which failures are free and how to retry a request without being charged twice. # Billing You pay for the tokens a model generates. The prompt is free, so a 4,000-token document that returns a 120-token answer is billed as 120 tokens. You pay with USDC on Solana. There is no card on file, no subscription and no invoice. You do not need an account in the usual sense: the key is generated on your device and the balance is attached to it. No name, email or ID is collected. ## What a request costs The price is per model and per generated token, set by the operator who publishes the model. It does not change with which machine serves the request. The price can change over time; the app shows the price in force before you send, and every response reports what the request cost. ## Reading a price The price lookup does not need a key, so you can check a model before you hold credit. ``` curl -s "https://api.autarcho.com/model//price?for_client=true" ``` The models page lists a price per model, and each model page shows the same figure. ## When you are not charged - A request that is refused before it runs, such as a parameter we do not accept. - A request that fails without producing any text. - A request whose price is above the limit you set. In each case the balance is unchanged, and the error names the reason. ## Capping the price Add max_price_per_token_micro_usdc to any request. If the model's price is above it, the request is refused with 402 before anything is charged, which is the simplest way to bound what a loop can spend. ## Streams that stop early If a stream is cut off, the tokens already produced are charged, because they were delivered. A client that gives up after a few seconds pays for what it received and nothing more. ## Retrying without paying twice Send Idempotency-Key with a value between 1 and 255 characters using letters, digits, ., _, : or -. The key belongs to your account, so two keys can use the same value without colliding. Situation | What happens | The same request is sent again with the same key | The stored response is returned and nothing is charged. | The first request is still running | 409 idempotency_in_progress with Retry-After. | The body changed under the same key | 409 idempotency_key_reused. Use a new key for a different request. | A stream was already completed under the key | 409 idempotency_already_completed. Streamed answers are not replayed. | A request that failed can be retried with the same key. A failed request is not charged, so retrying it is what the key is for. ## What a response reports usage.completion_tokens is the number of tokens billed. usage.prompt_tokens is zero because the prompt is not billed. usage.cost_micro_usdc is the charge for that request, in millionths of a USDC. # Batch requests A batch is a list of chat requests submitted in one call and collected later. Use it for work that does not need an answer immediately: classifying a file line by line, rewriting a set of descriptions, running the same prompt against many inputs. ## Submit a batch POST /v1/batches takes a model and an array of chat requests. Up to 1,000 items at a time. ``` curl -s https://api.autarcho.com/v1/batches \ -H "Authorization: Bearer ak_..." \ -H "content-type: application/json" \ -d '{ "model": "", "items": [ { "messages": [{ "role": "user", "content": "Name three uses for a shed." }] }, { "messages": [{ "role": "user", "content": "Rewrite this in one sentence: ..." }] } ] }' ``` The answer carries a batch_id, a status URL, a results URL, and the window your results are retained for. ## Check a batch GET /v1/batches/{id} reports how many items are queued, running, finished or failed, and how much credit the submission holds. GET /v1/batches lists your submissions newest first, which is how you find a batch again after losing the response. ``` curl -s https://api.autarcho.com/v1/batches/ \ -H "Authorization: Bearer ak_..." ``` ## Fetch results GET /v1/batches/{id}/results returns JSON Lines, one line per finished request, with the question it answered and the answer. ``` {"seq":1,"state":"done","prompt":"Name three uses for a shed.","content":"Storage, workshop, office.","finish_reason":"stop"} {"seq":2,"state":"done","prompt":"Rewrite this in one sentence: ...","content":"The shed is used for storage.","finish_reason":"stop"} ``` Items finish out of order. Read the whole set and match lines by seq rather than assuming the highest number you have seen means the batch is complete. A line with no text says why: the item failed, or its result had already expired. ## Cancel a batch POST /v1/batches/{id}/cancel refunds every item that has not started. Items already finished, or running at that moment, are not affected. ## What a batch costs The price is the same per generated token as a chat request. The amount held when you submit is an upper bound, calculated from the item count, the token budget and the price; the charge is the sum of what each item actually generated. An item that fails without producing any text is refunded. Billing covers the per-token rate, and the API reference covers the request fields inside an item.