API guide

01 · Start here

Quickstart

1. Sign in and open Manage API key.
2. Select a chat model, choose an optional expiry, and create the key. The secret is shown once.
3. Copy it immediately into a password manager or secret store. Do not put it in source code, screenshots, chat, logs, or browser URLs.
4. Call the API with the returned base URL and selected model.
5. Revoke the key from the same page when finished.

Python with the OpenAI SDK

python -m pip install openai

export NEODYM_API_KEY="your-key-from-the-portal"

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEODYM_API_KEY"],
    base_url="https://compute.neodym.ai/v1",
)

response = client.chat.completions.create(
    model="qwen2.5:7b",
    messages=[
        {"role": "system", "content": "Be concise."},
        {"role": "user", "content": "Explain shared model inference."},
    ],
    max_tokens=256,
)
print(response.choices[0].message.content)

cURL

export NEODYM_API_KEY="your-key-from-the-portal"

curl --fail-with-body https://compute.neodym.ai/v1/chat/completions \
  -H "Authorization: Bearer $NEODYM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen2.5:7b",
    "messages": [{"role": "user", "content": "Reply with: hello"}],
    "max_tokens": 64,
    "stream": false
  }'

02 · Access

Authentication and API keys

Send the key on every API request:

Authorization: Bearer your-api-key

• Each ordinary account can have one active key.
• The key is scoped to the model selected during creation.
• The raw secret is shown once; later page loads show only safe metadata and a short prefix.
• Key expiry and shared model-runtime expiry are separate. A key can expire while a shared deployment remains available to other valid keys.
• Revocation takes effect immediately for new API calls and returns 401 api_key_revoked.
• Creating and revoking keys is done through the signed-in portal. Bearer keys are for inference, jobs, models, and usage—not portal administration.

03 · Discovery

Models

curl https://compute.neodym.ai/v1/models \
  -H "Authorization: Bearer $NEODYM_API_KEY"

A normal model-scoped key returns only its approved model aliases. Use one of the returned IDs in chat or job requests. Model names are exact and case-sensitive.

04 · Synchronous inference

Chat completions

Request

{
  "model": "qwen2.5:7b",
  "messages": [
    {"role": "system", "content": "Be concise."},
    {"role": "user", "content": "What is a shared deployment?"}
  ],
  "max_tokens": 256,
  "n": 1,
  "stream": false
}

Supported message roles are system, developer, user, assistant, and tool. The current implementation generates one choice, so n must be 1. You may use max_tokens or max_completion_tokens.

Response

{
  "id": "chatcmpl-…",
  "object": "chat.completion",
  "created": 1760000000,
  "model": "qwen2.5:7b",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "…"},
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 20,
    "total_tokens": 32
  }
}

Non-streaming responses include an X-DGX-Request-ID. Keep that identifier when contacting support; it helps correlate a request without sharing your key or prompt.

05 · SSE

Streaming chat

Set "stream": true on /v1/chat/completions. The response uses Server-Sent Events with OpenAI-compatible chat.completion.chunk objects and ends with:

data: [DONE]

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["NEODYM_API_KEY"],
    base_url="https://compute.neodym.ai/v1",
)

stream = client.chat.completions.create(
    model="qwen2.5:7b",
    messages=[{"role": "user", "content": "Write a short explanation."}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

06 · Queued inference

Asynchronous jobs

Use jobs when the caller should receive a job ID quickly, poll independently, and retrieve the result later.

Submit

curl --fail-with-body https://compute.neodym.ai/v1/jobs \
  -H "Authorization: Bearer $NEODYM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen2.5:7b",
    "input": {
      "messages": [{"role": "user", "content": "Write a short summary."}]
    },
    "max_tokens": 256,
    "priority": "normal",
    "timeout_seconds": 300
  }'

The response includes job_id, state, status_url, result_url, poll_after_ms, Location, and Retry-After. Poll at the suggested interval instead of tight-looping.

States

queued → loading_model → running → completed. Terminal alternatives are failed, cancelled, and timed_out.

Poll and retrieve

curl https://compute.neodym.ai/v1/jobs/JOB_ID \
  -H "Authorization: Bearer $NEODYM_API_KEY"

curl https://compute.neodym.ai/v1/jobs/JOB_ID/result \
  -H "Authorization: Bearer $NEODYM_API_KEY"

Result retrieval before completion returns 409 job_result_not_ready. A completed result includes output text, token usage, queue dwell time, inference time, and total duration.

Cancel

curl -X DELETE https://compute.neodym.ai/v1/jobs/JOB_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Cancellation succeeds only while the job is nonterminal. Cancelling a completed, failed, timed-out, or already-cancelled job returns 409 job_already_terminal.

07 · Accounting

Usage and status

curl https://compute.neodym.ai/v1/usage \
  -H "Authorization: Bearer $NEODYM_API_KEY"

The response reports requests-per-minute, tokens-per-minute, concurrency, total request/token ceilings, consumed totals, active_requests, and up to the latest 100 usage rows. Rows include endpoint, model, approximate input/output tokens, queue and inference duration, status, error code, and timestamp.

The API Keys page is the authoritative ordinary-user view for key and shared-deployment state. Internal host IDs are intentionally omitted.

08 · Fair use

Limits, queueing, and capacity

Your current limits are displayed on the API Keys page and returned by /v1/usage. Administrators can configure them per account, so clients should read the live values instead of assuming defaults.

Synchronous requests can wait in a bounded queue and then return a normal completion. Async jobs expose queue state and timing. Same-model users share a warm deployment but retain separate keys, quotas, usage, and job ownership.

09 · Recovery

Errors and retries

Errors use an OpenAI-style JSON envelope:

{
  "error": {
    "message": "Human-readable explanation",
    "type": "invalid_request_error",
    "param": null,
    "code": "machine_readable_code"
  }
}

Recommended retry policy

• Never automatically retry most 400, 401, or 403 responses.
• For 409 job_result_not_ready, use the job's poll_after_ms or Retry-After.
• For 429 and temporary 503, honor Retry-After, then use exponential backoff with jitter and a bounded attempt count.
• Record X-DGX-Request-ID, HTTP status, and error code for support—but never the bearer key or private prompt.

10 · Runtime behavior

Key, deployment, and idle lifecycle

1. Key creation reserves capacity and attaches to or warms a shared model deployment.
2. The key becomes active only after the deployment is ready.
3. Successful inference refreshes deployment activity.
4. Revoking one user's key does not interrupt other valid users sharing that model.
5. When no active inference or nonterminal jobs remain, the deployment becomes eligible for idle cleanup.

The current server idle interval is 900 seconds. Cleanup runs on a reaper cadence, so the public deployment row may clear shortly after the nominal deadline rather than at exactly 900.000 seconds.

Key expiration, key revocation, and model idle cleanup are different events. Do not force-stop a shared model merely because one key was revoked.

11 · Data boundaries

Privacy and tenant isolation

• Raw API keys are not shown again after creation and are not stored as plaintext.
• Ordinary users see only their own key metadata.
• One user's revocation does not revoke another user's key.
• Async job status, result, and cancellation require the exact submitting key.
• Public API and deployment responses omit internal host identifiers, private infrastructure addresses, credentials, and storage paths.
• Synchronous prompt and completion text is not included in usage rows. Completed async job output is retained so the submitting key can retrieve it later.

Applications should minimize sensitive input, apply their organization's data policy, avoid logging bearer headers, and redact prompts/results from diagnostic bundles unless explicitly required and protected.

12 · OpenAI surface

Compatibility and current boundaries

Only depend on fields documented here. Backend/model behavior can differ from OpenAI even when request and response envelopes are compatible.

13 · Diagnose safely

Troubleshooting checklist

1. Check health: GET https://compute.neodym.ai/api/health.
2. Check the key: open Manage API key and confirm it is active, not pending, expired, or revoked.
3. Check model scope: call GET /v1/models and use the returned model ID exactly.
4. Check usage: call GET /v1/usage for current totals, limits, and active requests.
5. For jobs: poll the provided status_url; do not guess routes or poll faster than instructed.
6. For 429/503: honor Retry-After and back off.
7. For support: provide UTC time, endpoint, status, error code, and X-DGX-Request-ID. Never provide the raw key, cookies, passwords, or private data.