API reference
Chat completions
Two routes are implemented. Both require Authorization: Bearer and a ModelOne API key. A Privy session is rejected. The base URL is https://modelone.app/api/v1.
Authentication
Send the key from a server as Authorization: Bearer $MODELONE_API_KEY. The key is created on the keys page and shown once. Failed and revoked keys return 401. A suspended account returns 403. Checking one key is limited to 30 attempts per minute.
POST /api/v1/chat/completions
The JSON object may contain only model, messages, max_tokens, and stream. Any other field is rejected. model must be an enabled allowlist id. stream defaults to false. max_tokens defaults to 1024 or the model cap, whichever is lower, and must be a safe integer inside that cap.
Request
{
"model": "openai/gpt-4.1-mini",
"messages": [
{
"role": "user",
"content": "Reply with one short sentence."
}
],
"max_tokens": 64,
"stream": false
}The JSON below shows the response fields. The numbers are illustrative, not a recorded provider call. usage is null when the provider does not report both token counts. finish_reason is the provider value when it is a short token, otherwise null.
200 application/json
{
"id": "00000000-0000-4000-8000-000000000000",
"object": "chat.completion",
"created": 1763580000,
"model": "openai/gpt-4.1-mini",
"choices": [
{
"index": 0,
"message": { "role": "assistant", "content": "Hello from ModelOne." },
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 12,
"completion_tokens": 6,
"total_tokens": 18
},
"modelone": {
"settlement": "settled",
"settled_microusd": "12",
"reserved_microusd": "320000",
"available_microusd": "9968000"
}
}GET /api/v1/models
Returns object, inference_enabled, and data. Each model has id, object, owned_by set to openai or anthropic, context_length, max_output_tokens, and pricing in micro-USD per 1,000,000 tokens. The pricing fields are the reservation prompt rate and the reservation completion rate. This route answers when inference is off. inference_enabled is false in that case.
cURL
curl https://modelone.app/api/v1/models \
-H "Authorization: Bearer $MODELONE_API_KEY"Messages
Send 1 to 32 messages. Each object has only role and content. The role is system, user, or assistant. Content is a string of 1 to 8,000 characters. At least one message must use the user role. Images, audio, files, and tool calls are not accepted.
Streaming
stream: true returns text/event-stream. Each event is data: plus a chat completion chunk. Content arrives on choices[0].delta.content. The last chunk before data: [DONE] includes modelone. That object adds prompt_tokens and completion_tokens, which the JSON response instead places under usage.
text/event-stream
data: {"id":"00000000-0000-4000-8000-000000000000","object":"chat.completion.chunk","created":1763580000,"model":"openai/gpt-4.1-mini","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}
data: {"id":"00000000-0000-4000-8000-000000000000","object":"chat.completion.chunk","created":1763580000,"model":"openai/gpt-4.1-mini","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"modelone":{"settlement":"settled","settled_microusd":"12","reserved_microusd":"320000","available_microusd":"9968000","prompt_tokens":12,"completion_tokens":6}}
data: [DONE]Usage and settlement
Every accepted completion reserves the maximum price for the prompt bound and the requested output. modelone.settlement is settled when the provider reports a cost within that reservation. It is unknown when the cost is missing or above the reservation, and the reservation stays held. Amounts are micro-USD strings. 1,000,000 micro-USD is $1.00. available_microusd is the balance after the request.
Errors
Errors use error.message, error.type, and error.code. The type is rate_limit_error for 429 and invalid_request_error otherwise. A 429 includes Retry-After: 60. Credit, daily, concurrency, and provider ceilings use 402 and code quota.
| Status | Code | Message |
|---|---|---|
| 400 | invalid | The inference request is not valid. |
| 401 | unauthorized | The API key is not valid. |
| 402 | quota | This request exceeds the available inference allowance. |
| 403 | disabled | Inference is not enabled. |
| 403 | forbidden | This account cannot use inference. |
| 429 | limited | Too many inference requests. Wait and try again. |
| 502 | upstream | The model provider did not complete the request. |
| 503 | storage | Inference storage is not available. |
Limits
- One request reserves at most $0.50.
- Daily inference spend is $2 UTC.
- 3 requests can be open for one account.
- 20 inference requests per account each minute.
- 30 key checks per key each minute.
- Output is capped at 4,096 tokens and at what $0.50 can buy for that model.
- The JSON body can be at most 100,000 characters.
Skip to main content