Embeddings and rerank

Search over your own documents usually takes two steps: embeddings find the passages close to a question, and rerank puts the best of them first. Both samples below are files we run against the service before publishing.

Embeddings

# Embeddings for search and retrieval.
curl -sS "${OCEANTOKEN_BASE_URL:-https://api.oceantoken.ai/v1}/embeddings" \
  -H "Authorization: Bearer $OCEANTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "baai/bge-m3",
    "input": "The lighthouse keeper rowed out before dawn."
  }'

POST /v1/embeddings follows OpenAI's Embeddings API, so client.embeddings.create() works with the base URL changed.

Field	What it does
model	The ID of an embedding model.
input	A string, or a list of strings to embed in one request.
dimensions	A shorter vector, on models that offer it, such as openai/text-embedding-3-small.
encoding_format	float (default) or base64, on models that offer it.

The answer has one vector per input, in the same order, under data[].embedding, and usage.prompt_tokens.

• Batch your texts: one request with a list of inputs is faster and simpler than one request each.
• Use the same model for your documents and for the questions you search with. Vectors from different models cannot be compared.
• Embeddings are charged per input token.

response = client.embeddings.create(
    model="openai/text-embedding-3-small",
    input=["Refunds take 10 days.", "Shipping takes 3 days."],
)
vectors = [item.embedding for item in response.data]

Rerank

# Rerank: order documents by how well they answer the query. Cohere's request
# shape; the answer lists each document's index with its relevance score.
curl -sS --fail-with-body "${OCEANTOKEN_BASE_URL:-https://api.oceantoken.ai/v1}/rerank" \
  -H "Authorization: Bearer $OCEANTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cohere/rerank-v3.5",
    "query": "How long do refunds take?",
    "documents": [
      "Shipping takes three to five working days.",
      "Refunds reach your card within 10 days of the return arriving.",
      "Gift cards cannot be exchanged for cash."
    ],
    "top_n": 2
  }'

POST /v1/rerank follows Cohere's rerank request: model, the ID of a rerank model, query, documents as a list of strings, and optionally top_n, how many to return. The answer lists the documents by relevance, best first:

{
  "results": [
    {"index": 1, "relevance_score": 0.92},
    {"index": 0, "relevance_score": 0.08}
  ],
  "meta": {"billed_units": {"search_units": 1}}
}

index is the document's position in your list. Rerank is charged per search unit, the number in meta.billed_units.search_units (How you are charged).

Next

• With the Vercel AI SDK: Embeddings.
• Prices for every embedding and rerank model are on oceantoken.ai.