API REFERENCE

Yleiset parametrit

Otsikot, todennusmallit, virheenkuoret ja käytännöt, jotka koskevat kaikkia päätepisteitä.

Todennus

Kaikki päätepisteet vaativat Airforce API-avaimen. Luo sellainen alla olevassa kojelautassa API-avaimet. Avaimet alkavat sk-air-.

Parameter	Type	Required	Description
Authorization	string	Required	Bearer sk-air-YOUR_API_KEY. Accepted on every endpoint.
x-api-key	string	Optional	Alternative auth header. Accepted on /v1/messages and /v1/responses for Anthropic SDK compatibility.
anthropic-version	string	Optional	Required when using /v1/messages with the @anthropic-ai/sdk. Use "2023-06-01".
Content-Type	string	Optional	application/json for body posts. multipart/form-data for endpoints that accept file uploads (transcriptions, voice cloning, etc.).

Esimerkkejä

# Standard
curl https://api.airforce/v1/chat/completions \
  -H "Authorization: Bearer sk-air-YOUR_API_KEY" \
  …

# Anthropic SDK style (only on /v1/messages, /v1/responses)
curl https://api.airforce/v1/messages \
  -H "x-api-key: sk-air-YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  …

# Multipart upload (file endpoints)
curl https://api.airforce/v1/audio/transcriptions \
  -H "Authorization: Bearer sk-air-YOUR_API_KEY" \
  -F "[email protected]" \
  -F "model=whisper-1"

Valinnaiset pyyntöotsikot

Parameter	Type	Required	Description
X-Request-ID	string	Optional	Echoed in the response. Send your own correlation ID and we forward it through to logs and intercept records.
User-Agent	string	Optional	Helpful for debugging. Logged with every request.

Vastauksen otsikot

Parameter	Type	Required	Description
X-Request-ID	string	Optional	Server-generated request ID. Quote this when filing a support ticket.
X-Cost-Cents	integer	Optional	Cost of the request in cents (4 decimals of precision). Present on completed billing-relevant calls.
X-Tokens-Prompt / X-Tokens-Completion	integer	Optional	Token counts for chat / messages calls.
X-Cache-Hit	string	Optional	"5m" / "1h" / "miss" on Anthropic-style cached calls.

Päättely ja ajattelu (ristipäätepiste)

Mallit, joissa supports_reasoning: true hyväksyä samat kanoniset parametrit kaikkialla, missä ne esiintyvät (tällä hetkellä /v1/chat/completions ja /v1/messages).

Parameter	Type	Required	Description
reasoning_effort	string	Optional	"low" \| "medium" \| "high". OpenAI o-series / GPT-5 reasoning models only — has no effect on Claude. Use `thinking_budget` for Anthropic budget control.
thinking	string \| object	Optional	"on" / "off" / "auto" for a quick toggle, or { type: "enabled", budget_tokens: N } Anthropic shape. Both forms accepted, both normalised to the upstream's native shape.
thinking_budget	integer	Optional	Maximum tokens spent reasoning before visible output starts. Maps to budget_tokens (Anthropic) and thinking_budget (Gemini).
ignore_defaults	boolean	Optional	Bypass your saved per-model defaults for this single request. Useful when a saved default (e.g. thinking on) is overriding the value you sent.

Mallit päättelyn tuella

…· live

Katso Chatin loppuun saattaminen → perustelut täydellisiä esimerkkejä varten.

Suoratoistosopimus

Päätepisteet, jotka hyväksyvät stream: true vastata kanssa Content-Type: text/event-stream ja lähettää palvelimen lähettämiä tapahtumia. Langan muoto riippuu päätepisteestä:

Parameter	Type	Required	Description
/v1/chat/completions	OpenAI SSE	Optional	data: {…JSON chunk…}, terminated by data: [DONE].
/v1/messages	Anthropic SSE	Optional	Named events: message_start, content_block_start, content_block_delta, content_block_stop, message_delta, message_stop.
/v1/images/generations (sse: true)	OpenAI-shape SSE	Optional	Single data: event with the full response, then [DONE]. Useful for long-running image jobs to keep the connection alive.
/v1/video/tasks/:id/stream	progress SSE	Optional	Periodic { progress, status } events for in-flight video tasks. Stream closes once the task is done.

Virhekuori

Jokainen virhevastaus käyttää samaa JSON-muotoa. HTTP-tilakoodi kuvastaa vikaluokkaa.

Parameter	Type	Required	Description
error.message	string	Optional	Human-readable message safe to display.
error.type	string	Optional	Machine-readable category. See table below.
error.code	string	Optional	Specific identifier when applicable, e.g. "model_not_found".
error.param	string	Optional	Field name that failed validation, when relevant.

Parameter	Type	Required	Description
400	invalid_request	Optional	Malformed JSON, unknown field, validation failed.
401	authentication_error	Optional	Missing or invalid API key.
403	permission_error	Optional	Plan or per-key restriction blocks this request.
404	not_found	Optional	Unknown resource (model, task ID, voice ID).
413	payload_too_large	Optional	Upload exceeds size limit (200 MB for voice samples, etc.).
429	rate_limit	Optional	Per-second throttle, daily token cap, or balance exhausted.
500	internal_error	Optional	Unexpected. Quote the X-Request-ID when reporting.
503	upstream_error	Optional	Every key for the requested provider is failing right now. Retry with a different model or wait.

{
  "error": {
    "message": "Model 'gpt-99' not found.",
    "type": "invalid_request",
    "param": "model",
    "code": "model_not_found"
  }
}

Hintarajoitukset ja uudelleenyritykset

Rajoitukset pakotetaan API-avaimeen. Minkä tahansa niistä ylittäminen palaa 429:

Per-second request throttle (plan-dependent).
Daily token cap on free / pay-as-you-go plans.
Avainkohtainen luottoraja, kun asetat sen koontinäkymässä.
Concurrent video tasks (typically 4 in flight).

Retry with exponential backoff on 429 and 503. Don't retry on 4xx other than 429.

Idempotenssi

Sukupolven päätepisteet (chat, kuva, ääni, video) eivät ole idempotentteja – jokainen puhelu tuottaa uuden vastauksen ja laskutetaan itsenäisesti. Determinististen tulosten saamiseksi aseta kiinteä siemen, jos sitä tuetaan (kuva / ääni / jotkin chat-mallit). Pitkäaikaiset async-päätepisteet (/v1/video/generations) palauttavat task_id:n, jonka voit tehdä uudelleenkyselyn turvallisesti.

Päätepisteen kartta

Jokainen julkinen päätepiste yhdellä silmäyksellä.

Parameter	Type	Required	Description
POST /v1/chat/completions	chat	Optional	OpenAI Chat Completions. See /docs/api/chat.
POST /v1/messages	chat	Optional	Anthropic Messages. See /docs/api/chat.
POST /v1/responses	chat	Optional	Anthropic Responses (stateful). See /docs/api/chat.
GET /v1/models	models	Optional	List available models. See /docs/api/models.
POST /v1/images/generations	image	Optional	Generate / edit images. See /docs/api/media.
POST /v1/audio/speech	audio	Optional	Text-to-speech. See /docs/api/audio.
POST /v1/audio/music	audio	Optional	Music generation.
POST /v1/audio/sound-effects	audio	Optional	SFX generation.
POST /v1/audio/transcriptions	audio	Optional	Speech-to-text.
POST /v1/audio/audio-isolation	audio	Optional	Voice isolation / noise removal.
POST /v1/audio/voice-changer	audio	Optional	Speech-to-speech voice conversion.
POST /v1/audio/dubbing	audio	Optional	Async multi-language dubbing.
GET /v1/audio/voices	audio	Optional	Catalog of TTS voices.
POST /v1/voices/clone	voice	Optional	Clone a custom voice. See /docs/api/audio#voice-cloning.
GET /v1/voices/library	voice	Optional	List your cloned voices.
POST /v1/video/generations	video	Optional	Async video generation. See /docs/api/video.
GET /v1/video/tasks/:id	video	Optional	Poll a video task.