Api.Airforce
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

ParameterTypeRequiredDescription
modelstringRequiredEmbedding model ID — e.g. "text-embedding-3-small". See "Available models" below.
inputstring | arrayRequiredThe 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_formatstringOptional"float" (default) returns each vector as an array of numbers; "base64" returns it as a base64-packed string. Forwarded to the provider.
dimensionsintegerOptionalOptional reduced output dimensionality, for models that support it (the text-embedding-3 family). Omit to get the model's native size.
userstringOptionalOptional 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

ParameterTypeRequiredDescription
objectstringOptionalAlways "list".
dataarrayOptionalOne entry per input item: { object: "embedding", index, embedding }. The order matches your input array.
data[].embeddingarray | stringOptionalThe vector — an array of floats, or a base64 string when encoding_format is "base64".
modelstringOptionalThe embedding model that answered.
usageobjectOptional{ 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.

ParameterTypeRequiredDescription
text-embedding-3-small1536 dimsOptionalFast, low-cost general-purpose embeddings. The usual default for RAG and semantic search.
text-embedding-3-large3072 dimsOptionalHigher-quality embeddings for when retrieval accuracy matters more than cost.
text-embedding-ada-0021536 dimsOptionalLegacy model, kept for drop-in compatibility with existing indexes.

嵌入模型

…· live

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))

Rerank

根据查询为一组文档打分,并按相关性排序返回。在向量检索之后使用,让最匹配的结果排在最前。

POSThttps://api.airforce/v1/rerank

Rerank 模型

…· live
ParameterTypeRequiredDescription
modelstringRequiredRerank model ID. See the live list below.
querystringRequiredThe search query the documents are scored against.
documentsarrayRequiredUp to 1,000 documents: plain strings, or objects with a text field. Forwarded unchanged.
top_nintegerOptionalReturn only the n most relevant documents. All when omitted.
return_documentsbooleanOptionalInclude each document in its result, not only its index.
max_chunks_per_docintegerOptionalSplit long documents into at most this many chunks (model-specific; ignored where unsupported).
overlap_tokensintegerOptionalToken overlap between chunks (model-specific).
userstringOptionalYour end-user identifier, forwarded for abuse monitoring.
curl https://api.airforce/v1/rerank \
  -H "Authorization: Bearer sk-air-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "BAAI/bge-reranker-v2-m3",
    "query": "How do I rotate an API key?",
    "documents": [
      "Billing runs pay-as-you-go on input tokens.",
      "Create a new key in the dashboard, switch your app to it, then delete the old key.",
      "Embeddings return one vector per input string."
    ],
    "top_n": 2
  }'

响应结构

{
  "results": [
    { "index": 1, "relevance_score": 0.97 },
    { "index": 0, "relevance_score": 0.08 }
  ],
  "usage": { "total_tokens": 64 }
}

index 指向你的 documents 数组中的位置。响应体是模型提供方的原样回答,因此少数模型的用量字段名称不同。仅按输入 token 计费。