Skip to content
IdleAI/Docs
Workspace
Handbook/Use IdleAI
Implemented

Developer quickstart

Create real API credentials, understand the base URL, and avoid confusing authentication with available inference.

Reviewed 20 September 20265 sectionsUnderstand the status labels

In this chapter

Create an API key#

  1. Sign in with your wallet at the canonical workspace.
  2. Open Developers and choose a descriptive key label, such as a server or environment name.
  3. Create the key and copy it into a suitable secret manager immediately.
  4. Keep the key on your backend. Do not embed it in browser JavaScript, public repositories, screenshots, or client-side environment variables.
  5. Create separate keys for separate applications and revoke any key that may be exposed.

The complete key is returned once. Subsequent listings show a prefix and metadata, not the recoverable secret. The current format uses an idle_sk_ prefix and a random secret. Key existence does not fund an account or activate a model.

Keys accept an optional dollar spend cap at creation (capUsd). The cap is enforced inside the pipeline: cap space is reserved at the request's maximum charge before funds move, then reconciled to the actual charge — a capped key can never overshoot, and a buggy retry loop cannot drain the account. Keys without a cap are unlimited.

API base URL#

text
https://idleai.xyz/api/v1

Use the base URL displayed by the deployed workspace. The model-list endpoint is read-only; the completion endpoint runs the real pipeline — reserve, upstream call, reconcile, capture — and requires a funded balance.

Completion request shape#

bash
curl https://idleai.xyz/api/v1/chat/completions \
  -H "Authorization: Bearer $IDLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<VERIFIED_MODEL_ID>",
    "messages": [{"role": "user", "content": "Explain inference in one paragraph."}],
    "max_tokens": 256
  }'
Supply IDLE_API_KEY through your own secure environment; never put a real key into documentation.

Credential boundaries#

Wallet sessions authorize browser account operations. Bearer API keys authorize the developer inference path. These are separate mechanisms: an API key is not permission to change another account's keys or supplier application. Account ownership comes from the verified session, not a submitted address field.

Revocation is checked against persistent storage. A revoked key must not continue working merely because a process has an old in-memory copy. Invalid or revoked keys return 401; unfunded accounts receive 402 with the maximum charge estimate.

Before running a production client#

  • Read the live model catalog instead of assuming a model exists.
  • Set request timeouts and output limits.
  • Do not retry a paid request blindly after a timeout; its outcome may be unknown.
  • Require verified idempotency and usage-reconciliation semantics before relying on automated retries.
  • Keep credentials out of logs and error-reporting payloads.
  • Do not assume streaming, tool calls, image input, or every OpenAI option is supported solely because an endpoint resembles OpenAI's API.
Handbook