Quickstart

Use OpenAI-compatible and Anthropic-compatible APIs across active models and eligible suppliers. Start by changing your client's base URL and API key.

Review Acta Inference for supported interfaces and model-dependent limits. Use GET /v1/models for the current model catalog and published rates.

Get an API key

1. Get set up

Create an account at /signup.
Verify your email. This adds $5 of free credit to your account.
Create an API key in the console. Keys are shown once; store yours securely.
Point your OpenAI client at the Acta base URL:

Base URL	Use
https://multitudes.xyz/v1	Production API

2. Make your first request

cURL

curl https://multitudes.xyz/v1/chat/completions \
  -H "Authorization: Bearer acta_sk_…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "meta/llama-3.1-8b",
    "messages": [{"role": "user", "content": "Say hello in five words"}]
  }'

Python

from openai import OpenAI

client = OpenAI(
    base_url="https://multitudes.xyz/v1",
    api_key="acta_sk_…",
)

completion = client.chat.completions.create(
    model="meta/llama-3.1-8b",
    messages=[{"role": "user", "content": "Say hello in five words"}],
)
print(completion.choices[0].message.content)

JavaScript

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://multitudes.xyz/v1",
  apiKey: "acta_sk_…",
});

const completion = await client.chat.completions.create({
  model: "meta/llama-3.1-8b",
  messages: [{ role: "user", content: "Say hello in five words" }],
});
console.log(completion.choices[0].message.content);

Image generation

curl https://multitudes.xyz/v1/images/generations \
  -H "Authorization: Bearer acta_sk_…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "black-forest-labs/flux.1-schnell",
    "prompt": "a lighthouse at dawn, aerial view",
    "size": "1024x1024"
  }'

Endpoints

Endpoint	Notes
GET /v1/models	Lists every active model with its slug, modality and live per-unit pricing. No request body.
POST /v1/chat/completions	OpenAI-compatible chat. Send `model` and `messages`; the endpoint returns a completion object. To stream server-sent events, pass `"stream": true`.
POST /v1/images/generations	Send `model`, `prompt` and optional `size`; returns generated image data in the OpenAI images format.
POST /v1/videos/generations	Returns a job id immediately. Poll `GET /v1/videos/generations/:id` until `status` is `completed`. Priced per second of output.
POST /v1/messages	Anthropic-compatible, including tools and streaming. Auth via `x-api-key` works too. `POST /v1/messages/count_tokens` returns an input-token estimate.

For the selected model, Acta orders eligible suppliers by recent failures, session continuity, routing economics, and configured priority. After a qualifying failure, Acta can try another eligible supplier.

Agent harnesses

Tools that support the Anthropic Messages API and honor ANTHROPIC_BASE_URL can send requests through Acta. Use an active model slug from GET /v1/models:

# Claude Code on any Acta model
ANTHROPIC_BASE_URL=https://multitudes.xyz \
ANTHROPIC_API_KEY=acta_sk_… \
claude --model "meta/llama-3.1-8b"

Request headers

Header	Effect
X-Acta-Session	Use one id per conversation or agent session. Acta keeps requests on the same healthy supplier when possible, which can preserve provider-side cache eligibility without guaranteeing a cache hit.
X-Acta-Workload	Add a consistent attribution label such as `support-bot` or `ci-agent`. Console usage views group tagged requests by this value; untagged usage remains ownerless.

Spending limits & policy

Each key can carry a monthly spending limit, a calendar-month hard cap that returns 402 insufficient_quota after the limit, and an access policy. Allowed-model violations return 403 permission_error; blocked providers are removed from routing. Set both when creating a key in the console.

Cached-token pricing

When an upstream reports cached input tokens, Acta bills those tokens at 10% of the model's published input rate. Recorded cache usage appears in console usage views.

Errors

Status	Meaning
401 authentication_error	Missing or invalid API key. Check the `Authorization: Bearer` header.
402 insufficient_quota	Out of credits. Verify your email for the $5 credit or add credits in the console.
403 permission_error	The key's policy does not allow this model. Adjust the key policy in the console.
404 not_found	Unknown model. List valid slugs with `GET /v1/models`.
429 rate_limit_exceeded	The key reached its request limit. Wait and retry with exponential backoff.
502 upstream_error	The upstream supplier failed. Retry safely; the router fails over where possible.

Credits

You get $5 of free credit after verifying your email. Language models are priced per token and image models per image. Live prices appear in the public model catalog at GET /v1/models.