Api.Airforce
API REFERENCE

Chatin valmistuminen

Luo chat-vastauksia yli 100 malliin yhdestä API:sta. Drop-in on yhteensopiva OpenAI Chat Completions, Anthropic Messages ja Anthropic Responses kanssa.

Airforce ymmärtää sekä OpenAI Chat Completions- että Anthropic Messages -wire-formaatit samalla mallijoukolla. Valitse SDK, jota jo käytät, ja muuta vain base URL — muut kuin Claude-mallit välitetään läpinäkyvästi kummankin rajapinnan takana.

Tämä sivu käsittelee autentikoinnin, molempien rajapintojen request- ja response-muodot, streamingin, tool callingin, visionin, päättelyn ja prompt cachingin. Uusi täällä? Aloita alla olevasta perusesimerkistä, saa yksi kutsu toimimaan ja lisää sitten streaming, toolit tai caching, kun se toimii.

Todennus

Jokainen pyyntö tarvitsee Bearer-tunnuksen (Airforce API -avaimesi). Anthropic x-api-key otsikko on myös hyväksytty /v1/messages SDK-yhteensopivuuden vuoksi.

Authorization: Bearer sk-air-YOUR_API_KEY
# alt for /v1/messages:
x-api-key: sk-air-YOUR_API_KEY

POST /v1/chat/completions

OpenAI-yhteensopivat Chat Completions. Toimii virallisen openai SDK ohittamalla base_url kohtaan https://api.airforce/v1.

POSThttps://api.airforce/v1/chat/completions

Pyynnön runko

ParameterTypeRequiredDescription
modelstringRequiredMallin tunnus. Käytä GET /v1/models löytääksesi käytettävissä olevat tunnukset.
messagesarrayRequiredKeskusteluhistoria. Jokaisella merkinnällä on { role: "system" | "user" | "assistant" | "tool", content }. Sisältö on merkkijono tai taulukko sisältölohkoja (vision, katso alla).
max_tokensintegerOptionalLuotavien tunnuksien enimmäismäärä. Rajattu mallin max_output_tokeniin.
temperaturefloatOptionalNäytteenottolämpötila, 0–2. Alempi on deterministisempi. Oletusarvo riippuu ylävirran toimittajasta.
top_pfloatOptionalYdinnäytteenotto. Käytä joko lämpötilaa tai top_p:tä, ei molempia.
streambooleanOptionalKun tosi, vastaus on palvelimen lähettämien tapahtumien virta. Katso "Striimaus" alla.
modelsarrayOptionalFallback models (max 3), e.g. ["deepseek-v3.2", "gpt-4o-mini"]. If every channel of the primary model fails, each candidate is tried in order. You are billed for — and response.model reports — the model that actually answered. Unknown or plan-gated candidates are skipped. With the OpenAI SDK pass it via extra_body.
transformsarrayOptionalPrompt transforms. Supported: ["middle-out"] — when the conversation overflows the model's context window, whole messages are dropped from the middle (system prompts, the first message and the most recent turns are kept), so long roleplay or agent histories keep working instead of erroring. Opt-in; off by default.
stream_optionsobjectOptional{ include_usage: boolean }. Käyttö sisältyy aina suoratoiston viimeiseen osaan; tämä kenttä hyväksytään OpenAI-yhteensopivuuden vuoksi, mutta sitä ei voi poistaa käytöstä.
stopstring | arrayOptionalJopa 4 pysäytysjaksoa. Sukupolvi pysähtyy heti, kun sellainen on valmistettu.
toolsarrayOptionalToimintojen määritelmät, joita malli voi kutsua. Katso "Työkalun kutsuminen" alla.
tool_choicestring | objectOptional"auto" (oletus), "ei mikään" tai { type: "function", function: { name } } pakottaaksesi tietyn kutsun.
response_formatobjectOptional{ type: "json_object" } pakottaa mallin lähettämään kelvollisen JSONin. Ohitetaan malleissa, jotka eivät tue sitä.
reasoning_effortstringOptionalOpenAI o1/o3-tyylinen päättelyn syvyys: "matala" | "keskikokoinen" | "korkea". Katso "Päättely ja ajattelu".
thinkingstring | objectOptionalTarjoajien välinen ajattelukytkin. "päällä" | "pois päältä" | "auto" tai Anthropic-shape { type: "enabled", budget_tokens: N }. Katso "Päättely ja ajattelu".
thinking_budgetintegerOptionalToken cap mallin päättelyjäljelle (kun toimittaja paljastaa sellaisen).
ignore_defaultsbooleanOptionalOhita käyttäjän tallentamat mallikohtaiset oletusparametrit (määritetty kojelaudassa) tälle pyynnölle.

Perusesimerkki

curl https://api.airforce/v1/chat/completions \
  -H "Authorization: Bearer sk-air-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.1-chat",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is the capital of France?"}
    ],
    "max_tokens": 200,
    "temperature": 0.7
  }'

Vastauksen muoto

ParameterTypeRequiredDescription
idstringOptionalVakaa valmistumistunnus, esim. "chatcmpl-abc123".
objectstringOptional"chat.completion" ei-suoratoistolle, "chat.completion.chunk" suoratoistolle.
createdintegerOptionalUnix-aikaleima (sekuntia).
modelstringOptionalKaiku pyydetystä mallitunnuksesta.
choicesarrayOptionalJoukko valmistumisehdokkaita: [{ index, message: { role, content, tool_calls? }, lopetussyy }].
choices[].finish_reasonstringOptional"pysäytys" | "pituus" | "työkalukutsut" | "content_filter".
usageobjectOptional{ prompt_tokens, completion_tokens, total_tokens, completion_tokens_details?, prompt_tokens_details?, cache_creation_input_tokens?, cache_creation? }. completion_tokens_details.reasoning_tokens asetetaan kun malli tuotti päättelyjäljen. Välimuistikentät näkyvät kun upstream palautti prompt-välimuistitietoja: prompt_tokens_details.cached_tokens raportoi välimuistiluvut (OpenAI-standardi), cache_creation_input_tokens summaa kirjoitukset, ja cache_creation.ephemeral_5m_input_tokens / ephemeral_1h_input_tokens antavat TTL-jaon.
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "gpt-5.1-chat",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "The capital of France is Paris."
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 8,
    "total_tokens": 28
  }
}

Pohdintaa & ajattelua

Laajennettua päättelyä tukevat mallit paljastavat ajattelujäljen tavallisen tulosteen rinnalla. Airforce normalisoi kolme erilaista ylävirran yleissopimusta yhdeksi kanonisten parametrien joukoksi, jotka toimivat kaikkialla.

Tarkista supports_reasoning: true mallissa sisään GET /v1/models tietää, mitkä tunnukset hyväksyvät nämä parametrit.

Mallit päättelyn tuella

· live

Kanoniset parametrit

ParameterTypeRequiredDescription
reasoning_effortstringOptional"matala" | "keskikokoinen" | "korkea". OpenAI o1/o3-, GPT-5-päättelymallit ja kaikki niihin liittyvät reitittimet.
thinkingstring | objectOptional"päällä" | "pois päältä" | "auto" nopeaa vaihtoa varten tai { type: "enabled", budget_tokens: N } Anthropic-natiivimuotoa varten. Kartoittaa Clauden laajennettua ajattelua, Gemini-ajattelua ja DeepSeek-päättelyä.
thinking_budgetintegerOptionalEnimmäismäärä merkkiä, jonka malli voi käyttää päättelyyn ennen näkyvän tulosteen lähettämistä. Peilaa budget_tokens.

Päättelytyö (OpenAI-tyyli)

curl https://api.airforce/v1/chat/completions \
  -H "Authorization: Bearer sk-air-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "o3-mini",
    "messages": [{"role": "user", "content": "Prove the Pythagorean theorem."}],
    "reasoning_effort": "high"
  }'

Laajennettu ajattelu (Anthropic-tyyli)

curl https://api.airforce/v1/chat/completions \
  -H "Authorization: Bearer sk-air-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4.6",
    "messages": [{"role": "user", "content": "Plan a 7-day Italy trip."}],
    "thinking": {"type": "enabled", "budget_tokens": 4000}
  }'

Itse päättelyn jälki näkyy choices[0].message.reasoning (OpenAI-muoto) tai kuten thinking blokkaa sisään content (Anthropic-muoto). Perustelut laskutetaan ja raportoidaan usage.completion_tokens_details.reasoning_tokens.

Tämä completion_tokens_details.reasoning_tokens -erittely on mukana vain, kun upstream-palveluntarjoaja raportoi sen. Streamatussa vastauksessa jäljitys saapuu kentässä delta.reasoning_content per chunk.


Vision ja kuvan syöttö

Mallit, joissa supports_vision: true hyväksyä sisältölohkoiksi upotetut kuvat. Joko julkinen URL-osoite tai base64-tieto-URL toimii; kokorajoitukset riippuvat alkupään mallista.

Näkötuella varustetut mallit

· live
curl https://api.airforce/v1/chat/completions \
  -H "Authorization: Bearer sk-air-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.1-chat",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "What is in this image?"},
        {"type": "image_url", "image_url": {"url": "https://example.com/cat.jpg"}}
      ]
    }]
  }'

Työkalun kutsuminen

Mallit, joissa supports_tools: true voi kutsua määrittämiäsi toimintoja. Malli palauttaa a tool_calls joukko; soitat puhelun ja lähetät sitten tuloksen takaisin a tool viesti.

Mallit, joissa on työkalukutsutuki

· live

Pyytää

curl https://api.airforce/v1/chat/completions \
  -H "Authorization: Bearer sk-air-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.1-chat",
    "messages": [{"role": "user", "content": "What is the weather in Paris?"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get current weather for a location",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string", "description": "City name"}
          },
          "required": ["location"]
        }
      }
    }],
    "tool_choice": "auto"
  }'

Vastaa työkalukutsulla

{
  "id": "chatcmpl-abc123",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "call_1",
        "type": "function",
        "function": {
          "name": "get_weather",
          "arguments": "{\"location\":\"Paris\"}"
        }
      }]
    },
    "finish_reason": "tool_calls"
  }]
}

Seuranta työkalun tuloksella

{
  "model": "gpt-5.1-chat",
  "messages": [
    {"role": "user", "content": "What is the weather in Paris?"},
    {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "call_1",
        "type": "function",
        "function": {"name": "get_weather", "arguments": "{\"location\":\"Paris\"}"}
      }]
    },
    {"role": "tool", "tool_call_id": "call_1", "content": "{\"temp_c\": 14, \"sky\": \"cloudy\"}"}
  ]
}

Structured outputs

Set response_format to make the model return JSON. Two modes are supported:

  • { "type": "json_object" } — the response is a single valid JSON value.
  • { "type": "json_schema", "json_schema": { "name", "schema", "strict" } } — the model is steered to produce JSON that matches your JSON Schema.
curl https://api.airforce/v1/chat/completions \
  -H "Authorization: Bearer sk-air-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.1-chat",
    "messages": [{"role": "user", "content": "Extract the city and country: I live in Paris, France."}],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "location",
        "schema": {
          "type": "object",
          "properties": { "city": {"type": "string"}, "country": {"type": "string"} },
          "required": ["city", "country"]
        }
      }
    }
  }'

Reliability: even when a model wraps its answer in prose or a markdown code fence, Airforce extracts the JSON payload so you always receive parseable content. If no valid JSON can be recovered, the original text is returned unchanged — so the guarantee never makes a response worse. This applies to non-streamed responses; streamed responses are passed through unchanged.


Suoratoisto

Sarja stream: true vastaanottaa osittaisia ​​suorituksia palvelimen lähettäminä tapahtumina. Jokainen tapahtuma on yksi JSON-pala, jolla on sama muoto kuin suoratoistetulla vastauksella, paitsi message korvataan delta. Virta päättyy data: [DONE].

curl https://api.airforce/v1/chat/completions \
  -H "Authorization: Bearer sk-air-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.1-chat",
    "messages": [{"role": "user", "content": "Write a haiku about Berlin."}],
    "stream": true,
    "stream_options": {"include_usage": true}
  }'

Langallinen muoto

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1710000000,"model":"gpt-5.1-chat","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1710000000,"model":"gpt-5.1-chat","choices":[{"index":0,"delta":{"content":"Cold "},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1710000000,"model":"gpt-5.1-chat","choices":[{"index":0,"delta":{"content":"stone "},"finish_reason":null}]}


data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1710000000,"model":"gpt-5.1-chat","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":12,"completion_tokens":17,"total_tokens":29}}

data: [DONE]

POST /v1/messages

Anthropic-yhteensopiva Messages API. Toimii virallisen @anthropic-ai/sdk asettamalla baseURL kohtaan https://api.airforce. Edelleenlähetys OpenAI/Google/etc. läpinäkyvästi muille kuin Claude-malleille.

POSThttps://api.airforce/v1/messages

Pyynnön runko

ParameterTypeRequiredDescription
modelstringRequiredMallin tunnus (Anthropic-muoto tai reititetty alias).
messagesarrayRequiredJokainen merkintä: { role: "user" | "assistant", content: string | array }.
max_tokensintegerRequiredAnthropicin vaatima. Token cap vastaukselle.
systemstring | arrayOptionalJärjestelmäkehote. Välitä taulukko { type: "text", text, cache_control? } lohkot merkitsevät välimuistissa olevat etuliitesegmentit. Katso "Kehote välimuistiin".
temperaturefloatOptional0–1.
top_pfloatOptionalYdinnäytteenotto.
top_kintegerOptionalRajoita näytteenottopooli top-K tokeneihin.
stop_sequencesarrayOptionalJopa 4 pysäytysjaksoa.
streambooleanOptionalKun tosi, lähettää Anthropic-tyylisen SSE-tapahtumavirran (katso "Streaming").
fallbacksarrayOptionalFallback models (max 3) in Anthropic form: [{"model": "gpt-4o-mini"}]. If every channel of the primary model fails, each candidate is tried in order; you are billed for — and the response model field reports — the model that actually answered. A plain models string array is accepted too.
toolsarrayOptionalAnthropicin työkalumääritelmät: { name, description, input_schema }. Vastaus voi sisältää tool_use-sisältölohkoja.
tool_choiceobjectOptional{ type: "auto" | "any" | "tool", name? }.
thinkingobjectOptionalAnthropicin laajennettu ajattelu: { type: "enabled", budget_tokens: N }.

Esimerkki

curl https://api.airforce/v1/messages \
  -H "x-api-key: sk-air-YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4.6",
    "max_tokens": 256,
    "system": "You are a helpful assistant.",
    "messages": [
      {"role": "user", "content": "Hello, Claude!"}
    ]
  }'

Vastauksen muoto

ParameterTypeRequiredDescription
idstringOptionalViestitunnus, esim. "msg_01ABCxyz".
typestringOptionalAina "viesti".
rolestringOptionalAina "avustaja".
contentarrayOptionalSisältölohkojen taulukko: { type: "text" | "tool_use" | "thinking", … }.
modelstringOptionalKaiku pyydetystä mallista.
stop_reasonstringOptional"end_turn" | "max_tokens" | "stop_sequence" | "työkalun_käyttö".
usageobjectOptional{ input_tokens, output_tokens, cache_read_input_tokens?, cache_creation_input_tokens?, cache_creation? }. Välimuistikentät näkyvät kun prompt-välimuistia käytettiin. cache_creation.ephemeral_5m_input_tokens ja ephemeral_1h_input_tokens antavat kirjoitusjaon TTL-kohtaisesti.

Streaming tapahtumia

Anthropic SSE käyttää nimettyjä tapahtumia kertaluonteisten JSON-palojen sijaan. Jokaisessa tapahtumassa on sekä event: nimi ja a data: JSON-hyötykuorma.

event: message_start
data: {"type":"message_start","message":{"id":"msg_01","role":"assistant","content":[],"model":"claude-sonnet-4.6","stop_reason":null,"usage":{"input_tokens":12,"output_tokens":1}}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello"}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":17}}

event: message_stop
data: {"type":"message_stop"}

POST /v1/messages/count_tokens

Anthropic-compatible token counting. Send the same system / messages / tools you would pass to /v1/messages and get an input-token estimate back without running the model — nothing is billed.

POSThttps://api.airforce/v1/messages/count_tokens
curl https://api.airforce/v1/messages/count_tokens \
  -H "x-api-key: sk-air-YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4.6",
    "system": "You are a helpful assistant.",
    "messages": [{"role": "user", "content": "Hello, Claude!"}]
  }'

# → {"input_tokens": 34}

The count is a fast character-based estimate (about 4 characters per token) over system, messages and tools — close enough for context-budget checks, not an exact tokenizer run.


Nopea välimuisti

Päällä /v1/messages Claude-malleissa, merkitse etuliite välimuistiin siirtämällä system joukkona lohkoja, joissa välimuistissa oleva segmentti kuljettaa cache_control: { type: "ephemeral" }. Myöhemmät pyynnöt, jotka alkavat samalla etuliitteellä, veloittavat halvemman välimuistin lukuhinnan. Mallit, joissa supports_caching: true sisään /v1/models tukea tätä.

Mallit, joissa on nopea välimuisti

· live
{
  "model": "claude-sonnet-4.6",
  "max_tokens": 1024,
  "system": [
    {"type": "text", "text": "You are a senior staff engineer at Airforce."},
    {
      "type": "text",
      "text": "<repository-snapshot>...</repository-snapshot>",
      "cache_control": {"type": "ephemeral"}
    }
  ],
  "messages": [
    {"role": "user", "content": "Where is rate limiting enforced?"}
  ]
}

Miten välimuistilukemat raportoidaan vastauksessa

Välimuistitokenien lukemat välitetään kunkin muodon natiivimuodossa, joten SDK:t (openai, @anthropic-ai/sdk, @google/genai) lukevat ne ilman mukautettua koodia. Kentät jätetään pois kun arvo on nolla, pitäen ei-välimuistivastaukset kevyinä.

/v1/chat/completions (OpenAI-muoto)

"usage": {
  "prompt_tokens": 2104,
  "completion_tokens": 147,
  "total_tokens": 2251,
  "prompt_tokens_details": { "cached_tokens": 1980 },
  "cache_creation_input_tokens": 124,
  "cache_creation": {
    "ephemeral_5m_input_tokens": 124,
    "ephemeral_1h_input_tokens": 0
  }
}

/v1/messages (Anthropic-muoto)

"usage": {
  "input_tokens": 2104,
  "output_tokens": 147,
  "cache_read_input_tokens": 1980,
  "cache_creation_input_tokens": 124,
  "cache_creation": {
    "ephemeral_5m_input_tokens": 124,
    "ephemeral_1h_input_tokens": 0
  }
}

/v1beta/.../generateContent (Gemini-muoto)

"usageMetadata": {
  "promptTokenCount": 2104,
  "candidatesTokenCount": 147,
  "totalTokenCount": 2251,
  "cachedContentTokenCount": 1980
}

Missä välimuistitus pätee

Eksplisiittiset cache_control-merkinnät huomioidaan /v1/messages- ja /v1/chat/completions-rajapinnoissa Claude-malleille — laita ne system- tai message-sisältölohkoihin. Monet muut tarjoajat (OpenAI-perhe, DeepSeek, Gemini) välimuistittavat automaattisesti: et lähetä merkintöjä, ja näet vain cached_tokens vastauksessa, kun riittävän pitkää etuliitettä käytetään uudelleen.

Välimuistin kesto: 5 minuuttia tai 1 tunti

Välimuistitettu etuliite elää oletuksena 5 minuuttia, ja ajastin nollautuu joka osumalla. Pidempään elävää etuliitettä varten lisää ttl: "1h" merkintään. Vastaus raportoi kunkin TTL:n erikseen cache_creation-kohdassa.

"cache_control": { "type": "ephemeral", "ttl": "1h" }

Esimerkki: ensin kirjoitus, sitten luku

Lähetä täsmälleen sama pyyntö kahdesti (yllä oleva välimuistiesimerkki). Ensimmäinen etuliitteen näkevä kutsu maksaa kertaluonteisen välimuistikirjoituksen; identtiset kutsut TTL:n sisällä maksavat paljon halvemman välimuistiluvun.

Ensimmäinen kutsu — välimuistikirjoitus (usage-ote):

"usage": {
  "input_tokens": 2104,
  "output_tokens": 12,
  "cache_creation_input_tokens": 1980,
  "cache_read_input_tokens": 0
}

Toinen identtinen kutsu TTL:n sisällä — välimuistiluku:

"usage": {
  "input_tokens": 2104,
  "output_tokens": 12,
  "cache_creation_input_tokens": 0,
  "cache_read_input_tokens": 1980
}

Rajat ja kustannus

  • Claude vaatii vähimmäisetuliitteen välimuistille (noin 1024 tokenia; joillekin malleille enemmän). Lyhyempiä etuliitteitä ei yksinkertaisesti välimuistiteta.
  • Enintään 4 välimuistin katkaisukohtaa pyyntöä kohden, ja välimuistitetun etuliitteen on oltava tavulleen identtinen kutsujen välillä — yhdenkin merkin muutos ohittaa välimuistin.
  • Välimuistikirjoitukset maksavat enemmän kuin tavallinen syöte (5m ≈ 1,25×, 1h ≈ 2×); luvut maksavat paljon vähemmän (≈ 0,1×). Katso kunkin mallin välimuistihinnat hinnoittelusivulta.

POST /v1/responses

OpenAI Responses-API tilallisille keskusteluille. Sama Bearer/x-api-key todennus. Välimuistilukemat näkyvät input_tokens_details.cached_tokens (luku) sekä litteä cache_creation_input_tokens + cache_creation.ephemeral_* (kirjoitukset) /v1/chat/completions pariteetilla.

POSThttps://api.airforce/v1/responses

POST /v1beta/models/{model}:generateContent

Google Gemini-compatible endpoint. Works with the official @google/genai SDK and the Gemini CLI by pointing the base URL at https://api.airforce/v1beta. Any routed model works — requests are translated to and from the native Gemini shape, and the model is taken from the URL path (not the body).

POSThttps://api.airforce/v1beta/models/{model}:generateContent

Authentication

Pass your Airforce API key any of the three ways Google clients use:

# 1) query parameter (Google default)
?key=sk-air-YOUR_API_KEY

# 2) header
x-goog-api-key: sk-air-YOUR_API_KEY

# 3) bearer token
Authorization: Bearer sk-air-YOUR_API_KEY

Request body

ParameterTypeRequiredDescription
contentsarrayRequiredConversation turns. Each: { role: "user" | "model", parts: [...] }. A part is { text }, { functionCall: { name, args } }, or { functionResponse: { name, response } }. "model" is Gemini's term for the assistant role.
systemInstructionobjectOptionalSystem prompt: { parts: [{ text }] }.
generationConfigobjectOptional{ temperature, maxOutputTokens, topP, stopSequences } — mapped to the canonical sampling parameters.
toolsarrayOptionalTool definitions: [{ functionDeclarations: [{ name, description, parameters }] }]. functionDeclarations are flattened across entries.
toolConfigobjectOptionalTool-choice control: { functionCallingConfig: { mode: "AUTO" | "ANY" | "NONE" } }. ANY forces a call, NONE disables tools.

Example

curl "https://api.airforce/v1beta/models/gemini-3.1-pro:generateContent" \
  -H "x-goog-api-key: sk-air-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "What is the capital of France?"}]}
    ],
    "systemInstruction": {"parts": [{"text": "You are a helpful assistant."}]},
    "generationConfig": {"temperature": 0.7, "maxOutputTokens": 256}
  }'

Response shape

ParameterTypeRequiredDescription
candidatesarrayOptionalGenerated turns: [{ content: { role: "model", parts }, finishReason, index }]. Only the first candidate is populated.
candidates[].finishReasonstringOptional"STOP" | "MAX_TOKENS" | "SAFETY" | "OTHER".
usageMetadataobjectOptional{ promptTokenCount, candidatesTokenCount, totalTokenCount, cachedContentTokenCount? }. cachedContentTokenCount appears when the upstream reported a cache read.
modelVersionstringOptionalEcho of the requested model.
{
  "candidates": [{
    "content": {
      "role": "model",
      "parts": [{"text": "The capital of France is Paris."}]
    },
    "finishReason": "STOP",
    "index": 0
  }],
  "usageMetadata": {
    "promptTokenCount": 16,
    "candidatesTokenCount": 8,
    "totalTokenCount": 24
  },
  "modelVersion": "gemini-3.1-pro"
}

POST /v1beta/models/{model}:streamGenerateContent

Streaming uses the :streamGenerateContent action and returns Server-Sent Events. Each data: line is a full Gemini-shaped chunk (not a delta object); the final chunk carries usageMetadata.

data: {"candidates":[{"content":{"role":"model","parts":[{"text":"The capital"}]},"index":0}],"modelVersion":"gemini-3.1-pro"}

data: {"candidates":[{"content":{"role":"model","parts":[{"text":" is Paris."}]},"index":0}],"modelVersion":"gemini-3.1-pro"}

data: {"candidates":[{"content":{"role":"model","parts":[]},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":16,"candidatesTokenCount":8,"totalTokenCount":24}}

List models

The catalog is also exposed in Gemini Model-resource shape so Google clients can enumerate models.

curl https://api.airforce/v1beta/models

Notes: the base URL is https://api.airforce/v1beta (or /v1), not Google's host. The model name comes from the URL path, not the request body. Only the first candidate is returned, and a subset of Gemini fields is translated — safetySettings and cachedContent are currently ignored. Billing, rate limits and smart routing apply exactly as on /v1/chat/completions.


Virheet

Airforce palauttaa normaalit HTTP-tilakoodit ja yhtenäisen virheenkuoren molemmille päätepisteille.

ParameterTypeRequiredDescription
400invalid_request_errorOptionalVäärin muotoiltu JSON, pakollinen kenttä puuttuu, malli tuntematon.
401invalid_request_error / auth_requiredOptionalPuuttuva tai virheellinen API-avain.
402insufficient_quotaOptionalMalli vaatii aktiivisen tilauksen tai positiivisen Pay-as-you-Go-saldon.
403model_access_denied / insufficient_scopeOptionalSuunnitelman tai avainkohtaiset käyttöoikeudet estävät tämän pyynnön.
404model_not_foundOptionalPyydettyä mallia ei ole olemassa tai sinulla ei ole siihen pääsyä.
429rate_limit_errorOptionalPyyntökorko tai päiväkohtainen token cap ylitetty.
503api_error / moderation_unavailableOptionalKaikki pyydetyn palveluntarjoajan ylävirran avaimet epäonnistuivat.
{
  "error": {
    "message": "The requested model does not exist or you do not have access to it.",
    "type": "model_not_found",
    "param": null,
    "code": "404"
  }
}

Kuvaileva slug on kentässä type. code on HTTP-tila merkkijonona (esim. "404"), ja param on null paitsi parametrin arvoalueen validointivirheissä, joissa se nimeää virheellisen parametrin.

Tutustu malleihin

Katso täydellinen luettelo mallin tunnuksista ja niiden ominaisuuslipuista (näkemys, työkalut, päättely, välimuisti, kontekstin pituus jne.) osoitteessa /docs/api/models.

curl https://api.airforce/v1/models \
  -H "Authorization: Bearer sk-air-YOUR_API_KEY"