Reference / API

# API reference

Generated from approved schemas. OpenAI-compatible paths are served in parallel with native ones.

## Inference

Chat-shaped routes share one pipeline: the same routing, evidence and charge.

`POST` `/v1/chat/completions` `inference:invoke`

OpenAI-compatible chat completion, streaming or buffered, with a yelno object carrying attempts, usage units and cost. [Reference →](https://yelno.ai/docs/quickstart)

`POST` `/v1/responses` `inference:invoke`

OpenAI Responses shape — input items and instructions — translated to the same canonical request. Server-side state (previous_response_id) is not held; resend the full input.

`POST` `/v1/messages` `inference:invoke`

Anthropic-compatible messages, translated to the same canonical request and routed the same way.

`POST` `/v1/mcp` `per tool`

Yelno as an MCP server (Streamable HTTP): list_models, chat, get_usage and get_balance, each listed only when your key carries its scope. [Reference →](https://yelno.ai/docs/mcp)

`POST` `/v1/a2a` `inference:invoke`

Agent2Agent JSON-RPC: message/send, message/stream, tasks/get, tasks/cancel. The Agent Card is at /.well-known/agent-card.json. [Reference →](https://yelno.ai/docs/a2a)

## Model APIs

One route per model type beyond chat. Each JSON response carries yelno with the request id, provider, model, endpoint and charge.

`POST` `/v1/images/generations` `inference:invoke`

Generate images from a prompt; returns base64 images with their media type. [Reference →](https://yelno.ai/docs/images)

`POST` `/v1/videos` `inference:invoke`

Create an asynchronous video job; answers 202 with a vid_… id to poll. [Reference →](https://yelno.ai/docs/videos)

`GET` `/v1/videos/{id}` `inference:invoke`

The job's status (pending, in_progress, completed, failed, cancelled, expired), refreshed from the provider. [Reference →](https://yelno.ai/docs/videos)

`GET` `/v1/videos/{id}/content` `inference:invoke`

The finished video as video/mp4. Only the organization that created the job can read it. [Reference →](https://yelno.ai/docs/videos)

`POST` `/v1/audio/speech` `inference:invoke`

Text-to-speech; the body is the audio, the evidence is in X-Request-Id and Yelno-* headers. [Reference →](https://yelno.ai/docs/speech)

`POST` `/v1/audio/transcriptions` `inference:invoke`

Speech-to-text from a multipart file or base64 JSON, up to 25 MB. [Reference →](https://yelno.ai/docs/transcriptions)

`POST` `/v1/embeddings` `inference:invoke`

Embeddings in the OpenAI shape (input string or list), with usage and the charge in yelno. [Reference →](https://yelno.ai/docs/embeddings)

`POST` `/v1/rerank` `inference:invoke`

Rank documents by relevance to a query. [Reference →](https://yelno.ai/docs/rerank)

`POST` `/v1/decisions` `inference:invoke`

Typed answers to named questions about a piece of content. [Reference →](https://yelno.ai/docs/decisions)

`GET` `/v1/realtime?model=…` `inference:invoke`

WebSocket session in the OpenAI Realtime protocol, for models their provider serves directly; the final price arrives in a yelno.session event. [Reference →](https://yelno.ai/docs/realtime)

## Catalog

What your organization can route to, with every model's type.

`GET` `/v1/models` `catalog:read`

Models your organization's policy can route to: id, modalities, output_modalities, operations, context window, max output tokens.

`GET` `/v1/models/{model_id}` `catalog:read`

One model — including voices for a text-to-speech model — or 404 when it is not available to your organization.

## Fine-tuning

Train a supported open model on your data and serve it on a dedicated endpoint billed per GPU-hour while it runs. Off until your organization turns on allow_fine_tuning.

`POST` `/v1/files` `key:create`

Upload a JSON Lines dataset with purpose=fine-tune; validated on upload, the report comes back. [Reference →](https://yelno.ai/docs/fine-tuning-api#files)

`POST` `/v1/fine_tuning/estimate` `usage:read`

The estimate and the wallet hold for a job, without starting it. [Reference →](https://yelno.ai/docs/fine-tuning-api#estimate)

`POST` `/v1/fine_tuning/jobs` `key:create`

Create a job (OpenAI-compatible, Idempotency-Key supported); also list, retrieve, events, checkpoints and cancel. [Reference →](https://yelno.ai/docs/fine-tuning-api#jobs)

`POST` `/v1/fine_tuning/endpoints` `key:create`

Deploy a fine-tuned model on dedicated hardware with auto-stop; also list, update, start, stop and delete. [Reference →](https://yelno.ai/docs/fine-tuning-api#endpoints)

`GET` `/v1/fine_tuning/hardware?model=` `usage:read`

Hardware a model can run on, with its final price per hour. [Reference →](https://yelno.ai/docs/fine-tuning-api#hardware)

## Management

Under /api/v1 with a session bearer token; X-Yelno-Organization selects among your memberships.

`GET` `/api/v1/usage/requests/{request_id}` `usage:read`

Full request trail: state, attempts, usage events, ratings, reservation and journals.

`GET` `/api/v1/usage` `usage:read`

Requests, tokens and customer cost, bucketed by day, hour, model, project or state.

`GET` `/api/v1/wallet` `wallet:read`

Purchased, promotional, consumed, held and available balances, in nanos.

`PUT` `/api/v1/organizations/{organization_id}/policy` `policy:update`

The routing policy every request is evaluated against: require_zdr, max_retention_days, allowed_regions, provider and model allow/block lists, allow_byok. Send version for optimistic concurrency.

`POST` `/api/v1/keys` `key:create`

Mint an API key (yk_live_… or yk_test_…). The plaintext is returned once and never again.

## Conventions

Generated from approved schemas, with human guidance layered on: idempotency, retry semantics, partial streams, provider differences, usage finality, and rate limits. Base URL `https://yelno.ai/v1` · gateway calls authenticate with `Authorization: Bearer yk_live_…`, accept an optional `Idempotency-Key`, and every response carries `X-Request-Id`. The management API lives under `/api/v1` with a session bearer token — the full list is served at `/openapi.json`.

Source: https://yelno.ai/docs/api