API documentation

Address and key

• OpenAI formathttps://app.aivantage.fi/v1
• Anthropic formathttps://app.aivantage.fi

OpenAI libraries use the address ending in /v1. Anthropic libraries and Claude Code add the path themselves, so give them the address without /v1.

You create the key for an application in the portal, and it is shown only once. Send it in the header Authorization: Bearer <AIVANTAGE_KEY> or x-api-key: <AIVANTAGE_KEY>. Either header works with either format. A wrong or revoked key returns 401 invalid_api_key.

API error messages are always in English.

Endpoints

Models

The response's model field names the model that answered (aivantage/<id>). If the application is locked to one model in the portal, the request goes to it. If the lock rejects other models, a request for another model returns 409 app_model_locked.

Streaming, tools and images

Streaming (stream: true)

Tools (function calling)

Images

The privacy filter does not read images, so an image is always an uninspected attachment. If the policy blocks uninspected attachments, the request is refused before anything is sent: 403 privacy_blocked, reason attachment_not_inspected.

Headers

In the request

In the response

Errors

In the OpenAI format the reason is in error.code and the class in error.type: routing_error, policy_blocked, privacy_blocked, invalid_request_error or billing_error.

{"error": {"message": "The model is not allowed by the tenant's policy.",
           "type": "policy_blocked", "code": "model_not_allowed",
           "request_id": "req_…"}}

In the Anthropic format (/v1/messages) the type follows the HTTP status as in Anthropic's API, and the code is at the end of the message in square brackets. 503 no_healthy_instance is returned as 529 overloaded_error so that the SDKs retry. When the provider itself refuses the request, its own error is returned unchanged.

{"type": "error",
 "error": {"type": "permission_error",
           "message": "The model is not allowed by the tenant's policy. [model_not_allowed]"},
 "request_id": "req_…"}

Retry on 429 (wait for Retry-After), 502 and 503. Other 4xx errors come from the request or the settings, and the same request will not succeed on retry.

Rate limits (429 rate_limit_exceeded)

The shape is the same as the providers' rate limits: error.type is requests or tokens, error.code is rate_limit_exceeded, and the router's own reason is in error.reason: tenant_rate_requests, tenant_rate_tokens, tenant_concurrency.

Privacy block (privacy_blocked)

A blocked request is not sent to any model. The error.privacy field gives the reason (reason), an explanation in Finnish and English (message_fi, message_en) and the locations (violations), never the blocked values.

If an override was requested but not accepted, the error.privacy.override field gives the reason:

• key_not_allowed The policy does not let this key override the block.
• reason_not_allowed The reason is not on the policy's list of allowed reasons.
• type_not_overridable This identifier type may not be overridden.

Not supported

The router serves only the endpoints listed above. For example embeddings, image generation and audio are not available: /v1/embeddings, /v1/images/*, /v1/audio/*, /v1/files, /v1/batches, /v1/fine_tuning/*, /v1/moderations, /v1/completions, /v1/assistants, /v1/realtime.

An unknown /v1 path returns 404 and the supported endpoints:

{"error": {"message": "POST /v1/embeddings is not supported by AIvantage. Supported: …",
           "type": "invalid_request_error", "param": null,
           "code": "endpoint_not_supported"}}

Examples

Replace <AIVANTAGE_KEY> with the application's key. The application's page in the portal has the same examples with its models, plus the Claude Code and LangChain settings.

from openai import OpenAI

client = OpenAI(
    base_url="https://app.aivantage.fi/v1",
    api_key="<AIVANTAGE_KEY>",
)
resp = client.chat.completions.create(
    model="aivantage/auto",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(resp.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://app.aivantage.fi/v1",
  apiKey: "<AIVANTAGE_KEY>",
});
const resp = await client.chat.completions.create({
  model: "aivantage/auto",
  messages: [{ role: "user", content: "Hello!" }],
});
console.log(resp.choices[0].message.content);

import anthropic

client = anthropic.Anthropic(
    base_url="https://app.aivantage.fi",
    api_key="<AIVANTAGE_KEY>",
)
msg = client.messages.create(
    model="aivantage/auto",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
)
print(msg.content[0].text)

curl https://app.aivantage.fi/v1/chat/completions \
  -H "Authorization: Bearer <AIVANTAGE_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"model": "aivantage/auto", "messages": [{"role": "user", "content": "Hello!"}]}'

curl https://app.aivantage.fi/v1/messages \
  -H "x-api-key: <AIVANTAGE_KEY>" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model": "aivantage/auto", "max_tokens": 256, "messages": [{"role": "user", "content": "Hello!"}]}'

Test the features

These requests check that each feature works. First put the app's key in a variable: export AIVANTAGE_API_KEY=…

Shield's Mask, Own capacity only and Block, attachment blocking and Sovereignty are in use once the service is activated. During the pilot Shield only logs.

Key and model list

Checks that the key works and which models the app may use.

curl -s https://app.aivantage.fi/v1/models \
  -H "Authorization: Bearer $AIVANTAGE_API_KEY"

What you should see: Status 200. The list has aivantage/auto, whose aivantage.cascade field holds the cascade steps, and every model the app may use. A model's aivantage.class field tells where it runs (own is AIvantage's own capacity, the others eu, us and cn), and aivantage.jurisdictions the countries.

Wrong key

Checks that a wrong key is refused.

curl -s https://app.aivantage.fi/v1/models \
  -H "Authorization: Bearer vaara-avain"

What you should see: Status 401, error.code is invalid_api_key.

Cascade

Checks that the cascade picks a model and answers.

curl -si https://app.aivantage.fi/v1/chat/completions \
  -H "Authorization: Bearer $AIVANTAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"aivantage/auto","messages":[{"role":"user","content":"Vastaa yhdellä sanalla: mikä on Suomen pääkaupunki?"}]}'

What you should see: Status 200. The model field holds the model that answered (aivantage/<id>), one of the cascade models of aivantage/auto in the model list. An easy question usually goes to the first step. The x-aivantage-request-id header equals the id field, and the request shows in the portal's request log under that id. The usage field holds the billed tokens.

Locked model

Checks that the request goes to exactly the requested model. Use a model id from the model list.

curl -s https://app.aivantage.fi/v1/chat/completions \
  -H "Authorization: Bearer $AIVANTAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"aivantage/gpt-luna","messages":[{"role":"user","content":"Sano pelkkä: ok"}]}'

What you should see: Status 200, and the model field holds the requested model. A model not on the list returns 404 model_not_found.

Anthropic format

Checks that the Anthropic libraries' API works with the same key.

curl -s https://app.aivantage.fi/v1/messages \
  -H "x-api-key: $AIVANTAGE_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model":"aivantage/auto","max_tokens":50,"messages":[{"role":"user","content":"Sano pelkkä: ok"}]}'

What you should see: Status 200. The answer is in Anthropic's format (type is message), and the model field holds the model that answered (aivantage/<id>).

Streaming

Checks that the answer arrives as SSE chunks.

curl -sN https://app.aivantage.fi/v1/chat/completions \
  -H "Authorization: Bearer $AIVANTAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"aivantage/auto","stream":true,"messages":[{"role":"user","content":"Laske yhdestä viiteen."}]}'

What you should see: Lines data: {…} where object is chat.completion.chunk, with the same id and model in every chunk. Last comes a chunk with usage, then data: [DONE].

Shield: personal identity code

Checks what Shield does with a personal identity code. The model writes the code one character at a time, so the answer shows what the model received. Setting: The action on the Personal identity code row of the portal's Shield page.

curl -s https://app.aivantage.fi/v1/chat/completions \
  -H "Authorization: Bearer $AIVANTAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"aivantage/auto","messages":[{"role":"user","content":"Kirjoita tämä tunniste merkki kerrallaan välilyönnein erotettuna, ei muuta: 131052-308T"}]}'

Sovereignty

Checks that the request runs in Finland. Repeat the request without the identity code and compare. Setting: The app's Sovereignty. Critical in Finland needs the personal identity code on the Critical data list.

curl -s https://app.aivantage.fi/v1/chat/completions \
  -H "Authorization: Bearer $AIVANTAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"aivantage/auto","messages":[{"role":"user","content":"Henkilötunnus 131052-308T. Sano pelkkä: ok"}]}'

Uninspected attachment

Checks that an image Shield cannot read does not reach a model. Setting: Shield page, Advanced settings, Attachments: Block the request.

curl -s https://app.aivantage.fi/v1/chat/completions \
  -H "Authorization: Bearer $AIVANTAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"aivantage/auto","messages":[{"role":"user","content":[{"type":"text","text":"Mitä kuvassa on?"},{"type":"image_url","image_url":{"url":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII="}}]}]}'

What you should see: Status 403. error.code is privacy_blocked and error.privacy.reason attachment_not_inspected.

Rate limit

Checks that the limit stops a burst. The model aivantage/rajatesti does not exist, so the requests use no tokens.

seq 800 | xargs -P 50 -I{} curl -s -o /dev/null -w '%{http_code}\n' https://app.aivantage.fi/v1/chat/completions \
  -H "Authorization: Bearer $AIVANTAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"aivantage/rajatesti","messages":[{"role":"user","content":"hei"}]}' | sort | uniq -c

What you should see: The output has a 429 line and the rest 404. A single 429 response has error.code rate_limit_exceeded, error.reason tenant_rate_requests and the headers Retry-After and x-ratelimit-limit-requests.

Unknown endpoint

Checks that an endpoint AIvantage does not serve says so.

curl -s https://app.aivantage.fi/v1/embeddings \
  -H "Authorization: Bearer $AIVANTAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"aivantage/auto","input":"hei"}'

What you should see: Status 404, error.code is endpoint_not_supported, and the message lists the supported endpoints.