API REFERENCE

Embeddings

Turn text into vectors for semantic search, clustering, classification, and RAG. OpenAI-compatible — works with the official openai SDK by pointing it at api.airforce.

Authentication

Every request needs a Bearer token (your Airforce API key).

Authorization: Bearer sk-air-YOUR_API_KEY

POST /v1/embeddings

OpenAI-compatible Embeddings. Works with the official openai SDK by overriding base_url to https://api.airforce/v1.

POSThttps://api.airforce/v1/embeddings

Request body

Parameter	Type	Required	Description
model	string	Required	Embedding model ID — e.g. "text-embedding-3-small". See "Available models" below.
input	string \| array	Required	The text to embed. Either a single string, or an array of strings to embed in one request — one vector is returned per item, in the same order.
encoding_format	string	Optional	"float" (default) returns each vector as an array of numbers; "base64" returns it as a base64-packed string. Forwarded to the provider.
dimensions	integer	Optional	Optional reduced output dimensionality, for models that support it (the text-embedding-3 family). Omit to get the model's native size.
user	string	Optional	Optional opaque end-user identifier, passed through for abuse monitoring.

Example

curl https://api.airforce/v1/embeddings \
  -H "Authorization: Bearer sk-air-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-small",
    "input": "The quick brown fox jumps over the lazy dog"
  }'

Response

Parameter	Type	Required	Description
object	string	Optional	Always "list".
data	array	Optional	One entry per input item: { object: "embedding", index, embedding }. The order matches your input array.
data[].embedding	array \| string	Optional	The vector — an array of floats, or a base64 string when encoding_format is "base64".
model	string	Optional	The embedding model that answered.
usage	object	Optional	{ prompt_tokens, total_tokens }. Embeddings have no completion, so total_tokens equals prompt_tokens and you are billed on input only.

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.0023064255, -0.009327292, 0.015797347, "…"]
    }
  ],
  "model": "text-embedding-3-small",
  "usage": { "prompt_tokens": 9, "total_tokens": 9 }
}

Pass an array of strings as input to embed many texts in a single call — the data array comes back in the same order, and you are billed for the combined token count.

Available models

Request any of these by its ID in the model field. Each one is served from a pool of upstream providers with automatic failover, so a single provider hiccup does not fail your request.

Parameter	Type	Required	Description
text-embedding-3-small	1536 dims	Optional	Fast, low-cost general-purpose embeddings. The usual default for RAG and semantic search.
text-embedding-3-large	3072 dims	Optional	Higher-quality embeddings for when retrieval accuracy matters more than cost.
text-embedding-ada-002	1536 dims	Optional	Legacy model, kept for drop-in compatibility with existing indexes.
gemini-embedding-001	3072 dims	Optional	Google's general-purpose embedding model.

Billing is pay-as-you-go on input tokens only (embeddings have no completion). The per-million-token price is shown on each model's page and on your dashboard usage log; tiny requests round down to a fraction of a cent.

Using the OpenAI SDK

Point the official openai client at api.airforce and call embeddings.create as usual.

from openai import OpenAI

client = OpenAI(
    api_key="sk-air-YOUR_API_KEY",
    base_url="https://api.airforce/v1",
)

resp = client.embeddings.create(
    model="text-embedding-3-small",
    input=["First document", "Second document"],
)

for item in resp.data:
    print(item.index, len(item.embedding))