Api.Airforce
API REFERENCE

Sohbet tamamlamaları

Tek bir API’den 100’den fazla modelde sohbet yanıtları oluşturun. OpenAI Chat Completions, Anthropic Messages ve Anthropic Responses ile uyumludur.

Airforce, aynı model kümesi üzerinden hem OpenAI Chat Completions hem de Anthropic Messages wire formatlarını konuşur. Halihazırda kullandığınız SDK'yi seçin ve yalnızca base URL'i değiştirin — Claude dışı modeller her iki yüzeyin arkasında şeffaf bir şekilde iletilir.

Bu sayfa kimlik doğrulamayı, her iki yüzey için request ve response şekillerini, streaming'i, tool calling'i, vision'ı, akıl yürütmeyi ve prompt caching'i kapsar. Yeni mi başladınız? Aşağıdaki temel örnekle başlayın, bir çağrıyı çalıştırın, sonra çalışınca üzerine streaming, tool'lar veya caching ekleyin.

Kimlik doğrulama

Her isteğin bir Bearer belirtecine (Airforce API anahtarınız) ihtiyacı vardır. Anthropic x-api-key başlık da kabul edilir /v1/messages SDK uyumluluğu için.

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

POST /v1/chat/completions

OpenAI uyumlu Sohbet Tamamlamaları. Yetkili ile çalışır openai Geçersiz kılarak SDK base_url ile https://api.airforce/v1.

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

Talep gövdesi

ParameterTypeRequiredDescription
modelstringRequiredModel kimliği. Kullanılabilir kimlikleri keşfetmek için GET /v1/models komutunu kullanın.
messagesarrayRequiredKonuşma geçmişi. Her girişte { role: "system" | "user" | "assistant" | "tool", content } bulunur. İçerik, bir string veya içerik blokları dizisidir (görüntü, aşağıya bakın).
max_tokensintegerOptionalOluşturulacak maksimum jeton sayısı. Modelin max_output_tokens değeriyle sınırlıdır.
temperaturefloatOptionalÖrnekleme sıcaklığı, 0–2. Düşük daha deterministiktir. Varsayılan, yukarı akış sağlayıcısına bağlıdır.
top_pfloatOptionalÇekirdek örneklemesi. Hem sıcaklık hem de top_p kullanın, ikisini birden kullanmayın.
streambooleanOptionalDoğru olduğunda yanıt, Sunucu Tarafından Gönderilen Olayların akışıdır. Aşağıdaki "Akış" konusuna bakın.
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 }. Kullanım her zaman son akış parçasına dahil edilir; bu alan OpenAI uyumluluğu için kabul edilir ancak kapatılamaz.
stopstring | arrayOptional4'e kadar durdurma dizisi. Bir tanesi üretildiği anda nesil durur.
toolsarrayOptionalModelin çağırabileceği işlev tanımları. Aşağıdaki "Araç çağırma" konusuna bakın.
tool_choicestring | objectOptionalBelirli bir çağrıyı zorlamak için "auto" (varsayılan), "none" veya { type: "function", function: { name } }.
response_formatobjectOptional{ type: "json_object" } modeli geçerli JSON yaymaya zorlar. Desteklemeyen modeller için yoksayılır.
reasoning_effortstringOptionalOpenAI o1/o3 tarzı muhakeme derinliği: "low" | "medium" | "high". Bkz. "Akıl yürütme ve düşünme".
thinkingstring | objectOptionalSağlayıcılar arası düşünme anahtarı. "on" | "off" | "auto" veya Anthropic şekli { type: "enabled", budget_tokens: N }. Bkz. "Akıl yürütme ve düşünme".
thinking_budgetintegerOptionalModelin mantık izlemesi için belirteç sınırı (sağlayıcı bir tane ortaya çıkardığında).
ignore_defaultsbooleanOptionalBu istek için kullanıcının model başına kayıtlı varsayılan parametrelerini (kontrol panelinde yapılandırılmış) atlayın.

Temel örnek

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

Tepki şekli

ParameterTypeRequiredDescription
idstringOptionalKararlı tamamlama kimliği, ör. "chatcmpl-abc123".
objectstringOptionalAkışlı olmayanlar için "chat.completion", akışlı olanlar için "chat.completion.chunk".
createdintegerOptionalUnix zaman damgası (saniye).
modelstringOptionalİstenen model kimliğinin yankısı.
choicesarrayOptionalTamamlama adayları dizisi: [{ index, message: { role, content, tool_calls? }, bitiş_nedeni }].
choices[].finish_reasonstringOptional"stop" | "length" | "tool_calls" | "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 model bir akıl yürütme izi ürettiğinde ayarlanır. Cache alanları upstream prompt-caching bilgisi döndürdüğünde görünür: prompt_tokens_details.cached_tokens cache okumalarını raporlar (OpenAI standardı), cache_creation_input_tokens yazmaları toplar, ve cache_creation.ephemeral_5m_input_tokens / ephemeral_1h_input_tokens TTL bazlı dağılımı verir.
{
  "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
  }
}

Muhakeme ve düşünme

Genişletilmiş akıl yürütmeyi destekleyen modeller, normal çıktının yanı sıra bir düşünme izini de ortaya çıkarır. Airforce, üç farklı yukarı yönlü konvansiyonu, her yerde işe yarayan tek bir kanonik parametre seti halinde normalleştirir.

Kontrol etmek supports_reasoning: true bir model üzerinde GET /v1/models Bu parametreleri hangi kimliklerin kabul ettiğini bilmek için.

Muhakeme desteğine sahip modeller

· live

Kanonik parametreler

ParameterTypeRequiredDescription
reasoning_effortstringOptional"low" | "medium" | "high". OpenAI o1/o3, GPT-5 muhakeme modelleri ve bunlara eşlenen herhangi bir yönlendirici.
thinkingstring | objectOptionalHızlı bir geçiş için "on" | "off" | "auto" veya Anthropic’in yerel şekli için { type: "enabled", budget_tokens: N }. Claude genişletilmiş düşünme, Gemini düşünme ve DeepSeek muhakemesiyle eşleşir.
thinking_budgetintegerOptionalModelin görünür çıktı yaymadan önce harcayabileceği maksimum jeton miktarı. budget_tokens'ı yansıtır.

Muhakeme çabası (OpenAI tarzı)

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

Genişletilmiş düşünme (Anthropic tarzı)

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

Muhakeme izinin kendisi şu şekilde görünür: choices[0].message.reasoning (OpenAI şekli) veya thinking bloke etmek content (Anthropic biçimi). Muhakeme belirteçleri faturalandırılır ve raporlanır usage.completion_tokens_details.reasoning_tokens.

Bu completion_tokens_details.reasoning_tokens dökümü yalnızca üst akış sağlayıcısı bunu raporladığında mevcuttur. Stream edilen bir yanıtta iz, chunk başına delta.reasoning_content üzerinde gelir.


Görüş ve görüntü girişi

Şunlara sahip modeller: supports_vision: true İçerik blokları olarak gömülü görselleri kabul edin. Ya genel bir URL ya da bir base64 veri URL'si çalışır; boyut sınırları yukarı akış modeline bağlıdır.

Görüş desteğine sahip modeller

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

Araç çağırma

Şunlara sahip modeller: supports_tools: true tanımladığınız işlevleri çağırabilir. Model bir döndürür tool_calls sıralamak; aramayı çalıştırırsınız ve ardından sonucu geri gönderirsiniz. tool mesaj.

Araç çağırma desteğine sahip modeller

· live

Rica etmek

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

Araç çağrısıyla yanıt

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

Araç sonucunun takibi

{
  "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.


Akış

Ayarlamak stream: true Kısmi tamamlamaları Sunucu Tarafından Gönderilen Olaylar olarak almak için. Her olay, akışsız yanıtla aynı şekle sahip bir JSON öbeğidir; ancak message şununla değiştirilir: delta. Akış şununla bitiyor: 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}
  }'

Tel formatı

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 uyumlu Mesajlar API'si. Resmi @anthropic-ai/sdk ayarlayarak baseURL ile https://api.airforce. OpenAI/Google/etc'ye iletir. Claude olmayan modeller için şeffaf bir şekilde.

POSThttps://api.airforce/v1/messages

Talep gövdesi

ParameterTypeRequiredDescription
modelstringRequiredModel Kimliği (Anthropic formatında veya yönlendirilmiş takma ad).
messagesarrayRequiredHer giriş: { role: "user" | "assistant", content: string | array }.
max_tokensintegerRequiredAnthropic tarafından gerekli. Yanıt için belirteç sınırı.
systemstring | arrayOptionalSistem istemi. Önbelleğe alınmış önek bölümlerini işaretlemek için { type: "text", text, cache_control? } bloklarından oluşan bir dizi iletin. Bkz. "İstemi önbelleğe alma".
temperaturefloatOptional0–1.
top_pfloatOptionalÇekirdek örneklemesi.
top_kintegerOptionalÖrnekleme havuzunu en iyi K jetonlarıyla sınırlayın.
stop_sequencesarrayOptional4'e kadar durdurma dizisi.
streambooleanOptionaltrue olduğunda, Anthropic tarzı SSE olay akışını yayar (bkz. "Akış").
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.
toolsarrayOptionalAnthropic araç tanımları: { name, description, input_schema }. Yanıt tool_use içerik blokları içerebilir.
tool_choiceobjectOptional{ type: "auto" | "any" | "tool", name? }.
thinkingobjectOptionalAnthropic genişletilmiş düşünme: { type: "enabled", budget_tokens: N }.

Örnek

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

Tepki şekli

ParameterTypeRequiredDescription
idstringOptionalMesaj kimliği, ör. "msg_01ABCxyz".
typestringOptionalHer zaman "message".
rolestringOptionalHer zaman "assistant".
contentarrayOptionalİçerik blokları dizisi: { type: "text" | "tool_use" | "thinking", … }.
modelstringOptionalİstenilen modelin yankısı.
stop_reasonstringOptional"end_turn" | "max_tokens" | "stop_sequence" | "tool_use".
usageobjectOptional{ input_tokens, output_tokens, cache_read_input_tokens?, cache_creation_input_tokens?, cache_creation? }. Cache alanları prompt caching kullanıldığında görünür. cache_creation.ephemeral_5m_input_tokens ve ephemeral_1h_input_tokens TTL bazlı yazma dağılımını verir.

Etkinliklerin akışı

Anthropic SSE, tek seferlik JSON parçaları yerine adlandırılmış olayları kullanır. Her olayın hem bir event: isim ve bir data: JSON yükü.

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.


İstemi önbelleğe alma

Açık /v1/messages Claude modellerinde, bir öneki ileterek önbelleğe alınmış olarak işaretleyin system önbelleğe alınmış segmentin taşındığı bir blok dizisi olarak cache_control: { type: "ephemeral" }. Aynı önekle başlayan sonraki istekler, daha ucuz önbellek okuma hızından ücret alır. Şunlara sahip modeller: supports_caching: true içinde /v1/models bunu destekleyin.

Hızlı önbelleğe alma özelliğine sahip modeller

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

Cache sayıları yanıtta nasıl raporlanır

Cache token sayıları her formatın yerel biçiminde geçirilir, böylece SDK'lar (openai, @anthropic-ai/sdk, @google/genai) bunları özel kod olmadan okur. Değer sıfır olduğunda alanlar atlanır, cache'lenmemiş yanıtları yalın tutar.

/v1/chat/completions (OpenAI şekli)

"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 şekli)

"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 şekli)

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

Önbellekleme nerede geçerli

Açık cache_control işaretleri Claude modelleri için /v1/messages ve /v1/chat/completions üzerinde dikkate alınır — bunları system veya message içerik bloklarına koyun. Diğer birçok sağlayıcı (OpenAI ailesi, DeepSeek, Gemini) otomatik önbellekler: işaret göndermezsiniz ve yeterince uzun bir önek yeniden kullanıldığında yanıtta yalnızca cached_tokens görürsünüz.

Önbellek süresi: 5 dakika veya 1 saat

Önbelleğe alınmış bir önek varsayılan olarak 5 dakika yaşar ve her isabet sayacı yeniler. Daha uzun yaşayan bir önek için işarete ttl: "1h" ekleyin. Yanıt her TTL’yi cache_creation altında ayrı ayrı bildirir.

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

Örnek: önce yazma, sonra okuma

Tam olarak aynı isteği iki kez gönderin (yukarıdaki önbellek örneği). Öneki ilk gören çağrı tek seferlik bir önbellek yazması öder; TTL içindeki özdeş çağrılar çok daha ucuz önbellek okumasını öder.

İlk çağrı — önbellek yazma (usage alıntısı):

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

TTL içinde ikinci özdeş çağrı — önbellek okuma:

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

Sınırlar ve maliyet

  • Claude, önbelleğe alınabilir minimum bir önek gerektirir (yaklaşık 1024 token; bazı modellerde daha fazla). Daha kısa önekler basitçe önbelleğe alınmaz.
  • İstek başına en fazla 4 önbellek kırılma noktası ve önbelleğe alınan önek çağrılar arasında bayt bayt aynı olmalıdır — tek karakterlik bir değişiklik bile önbelleği ıskalar.
  • Önbellek yazmaları normal girdiden daha pahalıdır (5m ≈ 1,25×, 1h ≈ 2×); okumalar çok daha ucuzdur (≈ 0,1×). Her modelin önbellek fiyatlarını fiyatlandırma sayfasında görün.

POST /v1/responses

Durum bilgili konuşmalar için OpenAI Responses-API yüzeyi. Aynı Bearer/x-api-key kimlik doğrulaması. Cache sayıları input_tokens_details.cached_tokens (okuma) artı düz cache_creation_input_tokens + cache_creation.ephemeral_* (yazmalar) olarak görünür, /v1/chat/completions ile eşitlik için.

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.


Hatalar

Airforce, her iki uç nokta için standart HTTP durum kodlarını ve tek tip bir hata zarfını döndürür.

ParameterTypeRequiredDescription
400invalid_request_errorOptionalHatalı biçimlendirilmiş JSON, gerekli alan eksik, bilinmeyen model.
401invalid_request_error / auth_requiredOptionalEksik veya geçersiz API anahtarı.
402insufficient_quotaOptionalModel, etkin bir abonelik veya pozitif bir Pay-as-you-Go bakiyesi gerektirir.
403model_access_denied / insufficient_scopeOptionalPlan veya anahtar başına izinler bu isteği reddediyor.
404model_not_foundOptionalİstenen model mevcut değil veya ona erişiminiz yok.
429rate_limit_errorOptionalTalep oranı veya günlük jeton sınırı aşıldı.
503api_error / moderation_unavailableOptionalİstenen sağlayıcının tüm yukarı akış anahtarları başarısız oldu.
{
  "error": {
    "message": "The requested model does not exist or you do not have access to it.",
    "type": "model_not_found",
    "param": null,
    "code": "404"
  }
}

Açıklayıcı slug, type içindedir. code, HTTP durumunun string biçimidir (örn. "404") ve param, parametre aralığı doğrulama hataları dışında null'dur; bu hatalarda sorun çıkaran parametreyi adlandırır.

Modelleri keşfedin

Model kimliklerinin ve yetenek işaretlerinin (vizyon, araçlar, akıl yürütme, önbellekleme, bağlam uzunluğu,…) tam listesine şu adresten bakın: /docs/api/models.

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