API REFERENCE

Universelle Parameter

Header, Auth-Schemata, Error-Envelopes und Konventionen die für jeden Endpoint gelten.

Authentifizierung

Alle Endpoints benötigen einen Airforce API-Key. Generiere einen im Dashboard unter API Keys. Keys beginnen mit 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.).

Beispiele

# 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"

Optionale Request-Header

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.

Response-Header

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.

Reasoning & Thinking (endpointübergreifend)

Modelle mit supports_reasoning: true akzeptieren überall die gleichen kanonischen Parameter wo sie auftauchen (aktuell /v1/chat/completions und /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.

Modelle mit Reasoning-Support

…· live

Siehe Chat-Completions → Reasoning für vollständige Beispiele.

Streaming-Konvention

Endpoints die stream: true akzeptieren, antworten mit Content-Type: text/event-stream und senden Server-Sent Events. Das Wire-Format hängt vom Endpoint ab:

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.

Fehler-Envelope

Jede Fehler-Response nutzt dieselbe JSON-Form. Der HTTP-Statuscode reflektiert die Fehlerklasse.

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

Rate-Limits & Retries

Limits werden pro API-Key durchgesetzt. Wenn eines überschritten wird, kommt 429:

Per-second request throttle (plan-dependent).
Daily token cap on free / pay-as-you-go plans.
Pro-Key Credit-Limit, wenn du eines im Dashboard setzt.
Concurrent video tasks (typically 4 in flight).

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

Idempotenz

Generierungs-Endpoints (Chat, Image, Audio, Video) sind nicht idempotent — jeder Call produziert eine frische Response und wird einzeln abgerechnet. Für deterministische Ergebnisse setze einen festen seed wo unterstützt (Image / Audio / einige Chat-Modelle). Lang laufende Async-Endpoints (/v1/video/generations) geben eine task_id zurück die du gefahrlos weiter pollen kannst.

Endpoint-Übersicht

Jeder öffentliche Endpoint auf einen Blick.

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.