API reference

Every route of the Albastov API, with its parameters, responses and errors.

The API reference documents every route of the Albastov API at https://api.albastov.com/v1: parameters, headers, responses and error codes. Authentication, errors and rate limits apply to every route and have a page each.

Quick example

GET /v1/models lists the chat models with their state; the request needs a key with the scope llm and loads no model.

curl

curl https://api.albastov.com/v1/models -H "Authorization: Bearer $ALBASTOV_API_KEY"

Python

import os
from openai import OpenAI

client = OpenAI(base_url="https://api.albastov.com/v1", api_key=os.environ["ALBASTOV_API_KEY"])
print([m.id for m in client.models.list().data])

JavaScript

const res = await fetch("https://api.albastov.com/v1/models", {
  headers: { Authorization: `Bearer ${process.env.ALBASTOV_API_KEY}` },
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log((await res.json()).data.map((m) => m.id));

The response, shortened to one model without its facts:

JSON

{
  "object": "list",
  "data": [
    {
      "id": "qwen3.8-27b",
      "object": "model",
      "created": 1793304723,
      "loaded": true,
      "state": "loaded",
      "context_length": 150000,
      "capabilities": {"parallel": true, "thinking": true, "vision": false, "max_parallel": 64}
    }
  ]
}

What you can build

Authentication

API keys, their scopes and the Authorization header.

Errors

Error shapes, status codes, key errors and retry rules.

Rate limits

Call, token, size and wait limits, with the error each returns.

Chat completions

POST /v1/chat/completions parameters, headers, response and errors.

List models

GET /v1/models response fields and errors.

Speech

POST /v1/audio/speech, an audio file of the text in a built-in or saved voice.

Transcriptions

POST /v1/audio/transcriptions, the transcript of an audio file.

Voices

Saved voices: list, create, design, read, change, copy and delete.

Media jobs

Speech and transcription jobs, the wait for a result and the model list.

Uploads

POST /v1/media/uploads, an audio or image file stored on the account.

Samples

GET /v1/media/samples, one sample clip per speech and transcription model.

Dictation

Live dictation sessions, tickets and the WebSocket.

Events

Publish, list, stream and dismiss events, and receive webhooks.

Docs

The documentation as JSON, as markdown, as llms.txt and its images.

Status

GET /v1/status, the state of the API and of each product, with 90 days of history.

Key concepts

Base URL: https://api.albastov.com/v1. Request and response bodies are JSON, except audio files and multipart uploads where a route says so.
Authentication: Authorization: Bearer $ALBASTOV_API_KEY. An account key abk_ opens the routes of its scopes: llm, media:read, media:generate, dictation, events:publish and events:read.
Errors: Every JSON error body carries a code and a message. Branch on the HTTP status and code; the message text may change.
Rate limits: An account key makes 60 calls per minute and 5,000 per 24 hours by default; a call over the limit fails with 429 rate_limited. Retry-After is in seconds.
Request ids: Every response carries an X-Request-Id header. Include the value in a bug report.
Versioning: Every route path starts with /v1. A breaking change to a stable route appears in the changelog before release; every change to a beta route gets a changelog line; an experimental route may change without notice.

Next steps

Quick start

A key, a first chat completion and a first speech file.

Changelog

Every change to the Albastov API, newest first.

Overview

The products, their statuses and the conventions every route follows.