Skip to main content
ModelOne

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.

StatusCodeMessage
400invalidThe inference request is not valid.
401unauthorizedThe API key is not valid.
402quotaThis request exceeds the available inference allowance.
403disabledInference is not enabled.
403forbiddenThis account cannot use inference.
429limitedToo many inference requests. Wait and try again.
502upstreamThe model provider did not complete the request.
503storageInference 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.