API-dokumentaatio

Osoite ja avain

• OpenAI-muotohttps://app.aivantage.fi/v1
• Anthropic-muotohttps://app.aivantage.fi

OpenAI-kirjastot käyttävät osoitetta, jonka lopussa on /v1. Anthropic-kirjastot ja Claude Code lisäävät polun itse, joten niille annetaan osoite ilman /v1:tä.

Avain luodaan portaalissa sovellukselle, ja se näytetään vain kerran. Lähetä se otsakkeessa Authorization: Bearer <AIVANTAGE_KEY> tai x-api-key: <AIVANTAGE_KEY>. Kumpikin otsake käy kumpaankin muotoon. Väärä tai poistettu avain palauttaa 401 invalid_api_key.

Rajapinnan virheviestit ovat aina englanniksi.

Rajapinnat

Mallit

Vastauksen model-kentässä on malli, joka vastasi (aivantage/<id>). Jos sovellus on portaalissa lukittu yhteen malliin, pyyntö menee sille. Jos lukko hylkää muut mallit, toisen mallin pyyntö palauttaa 409 app_model_locked.

Suoratoisto, työkalut ja kuvat

Suoratoisto (stream: true)

Työkalut (function calling)

Kuvat

Tietosuojasuodatin ei lue kuvia, joten kuva on aina tarkastamaton liite. Jos politiikka estää tarkastamattomat liitteet, pyyntö estetään ennen kuin mitään lähtee: 403 privacy_blocked, syy attachment_not_inspected.

Otsakkeet

Pyynnössä

Vastauksessa

Virheet

OpenAI-muodossa virheen syy on kentässä error.code ja luokka kentässä error.type: routing_error, policy_blocked, privacy_blocked, invalid_request_error tai billing_error.

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

Anthropic-muodossa (/v1/messages) tyyppi tulee HTTP-tilasta Anthropicin tapaan, ja koodi on viestin lopussa hakasulkeissa. Tila 503 no_healthy_instance palautetaan muodossa 529 overloaded_error, jotta kirjastot yrittävät uudelleen. Kun palveluntarjoaja itse hylkää pyynnön, sen oma virhe palautetaan sellaisenaan.

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

Uudelleenyritys kannattaa tiloissa 429 (odota Retry-After), 502 ja 503. Muut 4xx-virheet johtuvat pyynnöstä tai asetuksista, eikä sama pyyntö onnistu uudelleen.

Nopeusrajat (429 rate_limit_exceeded)

Muoto on sama kuin palveluntarjoajien rajoissa: error.type on requests tai tokens, error.code on rate_limit_exceeded ja reitittimen oma syy on kentässä error.reason: tenant_rate_requests, tenant_rate_tokens, tenant_concurrency.

Tietosuojaesto (privacy_blocked)

Estetty pyyntö ei lähde millekään mallille. Kenttä error.privacy kertoo syyn (reason), selityksen suomeksi ja englanniksi (message_fi, message_en) sekä kohdat (violations), ei koskaan estettyjä arvoja.

Jos ohitusta pyydettiin mutta sitä ei hyväksytty, kenttä error.privacy.override kertoo syyn:

• key_not_allowed Politiikka ei salli tämän avaimen ohittaa estoa.
• reason_not_allowed Peruste ei ole politiikan sallittujen listalla.
• type_not_overridable Tätä tunnistetyyppiä ei saa ohittaa.

Ei tuettu

Reititin palvelee vain yllä luetellut rajapinnat. Esimerkiksi upotukset, kuvien luonti ja puhe eivät ole käytettävissä: /v1/embeddings, /v1/images/*, /v1/audio/*, /v1/files, /v1/batches, /v1/fine_tuning/*, /v1/moderations, /v1/completions, /v1/assistants, /v1/realtime.

Tuntematon /v1-polku palauttaa tilan 404 ja tuetut rajapinnat:

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

Esimerkit

Korvaa <AIVANTAGE_KEY> sovelluksen avaimella. Sovelluksen sivulla portaalissa on samat esimerkit sovelluksen malleilla sekä Claude Coden ja LangChainin asetukset.

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": "Hei!"}],
)
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: "Hei!" }],
});
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": "Hei!"}],
)
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": "Hei!"}]}'

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": "Hei!"}]}'

Testaa toiminnot

Näillä pyynnöillä tarkistat, että kukin toiminto toimii. Anna ensin sovelluksen avain muuttujaan: export AIVANTAGE_API_KEY=…

Suojan Naamioi, Vain oma kapasiteetti ja Estä, liitteiden esto ja Suvereniteetti ovat käytössä, kun palvelu on aktivoitu. Pilotissa Suoja vain kirjaa.

Avain ja mallilista

Tarkistaa, että avain toimii ja mitkä mallit sovellus saa käyttää.

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

Mitä pitäisi näkyä: Tila 200. Listassa on aivantage/auto, jonka kentässä aivantage.cascade ovat porrastuksen askeleet, ja jokainen sovellukselle sallittu malli. Mallin kenttä aivantage.class kertoo, missä se ajetaan (own on AIvantagen oma kapasiteetti, muut eu, us ja cn), ja aivantage.jurisdictions maat.

Väärä avain

Tarkistaa, että väärällä avaimella ei pääse sisään.

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

Mitä pitäisi näkyä: Tila 401, error.code on invalid_api_key.

Porrastus

Tarkistaa, että porrastus valitsee mallin ja vastaa.

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?"}]}'

Mitä pitäisi näkyä: Tila 200. Kentässä model on malli, joka vastasi (aivantage/<id>), ja se on yksi mallilistan aivantage/auto-kohdan cascade-malleista. Helppo kysymys menee yleensä ensimmäiselle askeleelle. Otsake x-aivantage-request-id on sama kuin kenttä id, ja samalla tunnisteella pyyntö näkyy portaalin pyyntölokissa. Kentässä usage ovat laskutettavat tokenit.

Lukittu malli

Tarkistaa, että pyyntö menee juuri pyydetylle mallille. Vaihda malliksi jokin tunniste mallilistalta.

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"}]}'

Mitä pitäisi näkyä: Tila 200, ja kentässä model on pyydetty malli. Malli, jota listalla ei ole, palauttaa 404 model_not_found.

Anthropic-muoto

Tarkistaa, että Anthropic-kirjastojen rajapinta toimii samalla avaimella.

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"}]}'

Mitä pitäisi näkyä: Tila 200. Vastaus on Anthropicin muodossa (type on message), ja kentässä model on malli, joka vastasi (aivantage/<id>).

Suoratoisto

Tarkistaa, että vastaus tulee SSE-paloina.

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."}]}'

Mitä pitäisi näkyä: Rivejä data: {…}, joissa object on chat.completion.chunk ja joka palassa sama id ja model. Viimeisenä tulee pala, jossa on usage, ja sitten data: [DONE].

Suoja: henkilötunnus

Tarkistaa, mitä Suoja tekee henkilötunnukselle. Malli kirjoittaa tunnisteen merkki kerrallaan, joten vastauksesta näkee, mitä malli sai. Asetus: Portaalin Suoja-sivulla Henkilötunnus-rivin toimenpide.

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"}]}'

Suvereniteetti

Tarkistaa, että pyyntö ajetaan Suomessa. Toista pyyntö ilman henkilötunnusta ja vertaa. Asetus: Sovelluksen Suvereniteetti. Kriittiset Suomeen vaatii, että henkilötunnus on Kriittiset tiedot -listalla.

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"}]}'

Tarkastamaton liite

Tarkistaa, että kuva, jota Suoja ei voi lukea, ei lähde mallille. Asetus: Suoja-sivun Edistyneet asetukset, Liitteet: Estä pyyntö.

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="}}]}]}'

Mitä pitäisi näkyä: Tila 403. error.code on privacy_blocked ja error.privacy.reason attachment_not_inspected.

Nopeusraja

Tarkistaa, että raja pysäyttää ryöpyn. Mallia aivantage/rajatesti ei ole, joten pyynnöt eivät kuluta tokeneita.

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

Mitä pitäisi näkyä: Tulosteessa on rivi 429 ja loput 404. Yksittäisessä 429-vastauksessa error.code on rate_limit_exceeded, error.reason tenant_rate_requests ja otsakkeissa Retry-After ja x-ratelimit-limit-requests.

Tuntematon rajapinta

Tarkistaa, että rajapinta, jota AIvantage ei palvele, kertoo sen.

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"}'

Mitä pitäisi näkyä: Tila 404, error.code on endpoint_not_supported, ja viestissä luetellaan tuetut rajapinnat.