OpenAI-compatible.
Explicit by design.

List, select, run.

Install the OpenAI Python SDK, keep your key in the environment, then select an exact ID from the live catalog. Do not hard-code a model name that the catalog did not return.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://newtons.dev/api/v1",
    api_key=os.environ["NEWTONS_API_KEY"],
)

catalog = client.models.list()
if not catalog.data:
    raise RuntimeError("No models published.")

model_id = catalog.data[0].id
completion = client.chat.completions.create(
    model=model_id,
    messages=[{"role": "user", "content": "Reply exactly: Newton's connected"}],
    max_tokens=32,
)

print(completion.choices[0].message.content)
print("resolved model:", completion.model)

Expected application result: a normal Chat Completion whose model matches the selected published ID. The JSON response also contains a newtons receipt object. Keep the key out of source code, chat, logs, screenshots, and committed files.

{
  "id": "chatcmpl-…",
  "object": "chat.completion",
  "model": "<published-model-id>",
  "choices": [{ "index": 0, "message": { "role": "assistant", "content": "Newton's connected" } }],
  "usage": { "prompt_tokens": 12, "completion_tokens": 4, "total_tokens": 16 },
  "newtons": {
    "request_id": "…",
    "requested_model": "<published-model-id>",
    "resolved_model": "<published-model-id>",
    "fallback_used": false,
    "billing_mode": "membership",
    "included": true,
    "membership_plan": "solo",
    "policy_status": "normal",
    "cost_estimated": false
  }
}

Focused surface.

Use https://newtons.dev/api/v1 as the SDK base URL. All routes require Authorization: Bearer $NEWTONS_API_KEY.

Read through the final receipt.

Set stream=True and consume the stream until [DONE]. Newton’s appends a terminal chunk with empty choices and the settled newtons receipt before the done sentinel.

stream = client.chat.completions.create(
    model=model_id,
    messages=[{"role": "user", "content": "Explain inertia in one sentence."}],
    max_tokens=80,
    stream=True,
)

receipt = None
for chunk in stream:
    if chunk.choices:
        text = chunk.choices[0].delta.content
        if text:
            print(text, end="", flush=True)
    extra = getattr(chunk, "model_extra", None) or {}
    receipt = extra.get("newtons") or receipt

print("\\nreceipt:", receipt)

The HTTP receipt headers at stream start are an authorization estimate. The terminal receipt is the settled result. If the stream emits an error event, treat it as terminal and do not execute tool side effects from an incomplete response.

Retry by class, not by instinct.

A retry can create a second billable completion if the first request finished upstream but its response was lost. Retry only operations your application can safely repeat, and never retry a completed tool side effect merely because its reporting request failed.

Known envelopes.

Solo and Team have no daily or monthly token cutoff for legitimate human-driven interactive use. Capacity, safety, fair-use policy, and model availability still apply. Trial and Agents also require funded credit. A rate or concurrency response uses 429 and includes Retry-After.

Every accepted call accounts for itself.

x-newtons-request-id
x-newtons-requested-model
x-newtons-resolved-model
x-newtons-fallback-used
x-newtons-billing-mode
x-newtons-membership-plan
x-newtons-usage-included
x-newtons-policy-status
x-newtons-request-cost-usd
x-newtons-balance-usd
x-newtons-cost-estimated
x-newtons-rpm-limit
x-newtons-concurrency-limit

Membership receipts say the request was included; trial and Agents receipts report prepaid cost and balance impact. Newton’s still records tokens and supplier cost internally for analytics and service economics, not as a Solo or Team allowance. Receipts are accounting metadata, not cryptographic attestations. Save the request ID—not the prompt or API key—when asking for support.

Pinned means no silent swap.

A published model ID remains pinned to that route. Newton’s requires the upstream-reported ID to match; mismatched or unconfirmed responses fail closed. If you explicitly provide documented fallback_models, Newton’s may try up to three of those published IDs in the order supplied and reports whether a fallback was used.

Automatic model routing is not currently part of the public API.

Know where the request goes.

Newton’s sends supported request content to the upstream inference processor and routed model provider used by the selected published route. Yunwu API is a current inference processor, and other configured suppliers may serve particular routes. The processor used can therefore vary by route and available capacity. Review the Privacy Notice before sending production data.

Your NEWTONS_API_KEY authenticates to Newton’s and is never forwarded as an upstream supplier credential. Some routes may use an account-scoped supplier credential that Newton’s stores encrypted at rest and can revoke independently. Other routes may use Newton’s shared upstream service credentials. Supplier-credential isolation is route- and configuration-dependent, not a universal property of every request.

Know what is—and is not—implemented.