Embeddings

POST /v1/embeddings is drop-in compatible with OpenAI’s Embeddings API. Point an OpenAI client at the gateway, keep your code, and pay from the same credit balance as every other endpoint. Embeddings consume input tokens only — there is no generated output — so they are billed on the input rate alone.

Models

Model	Max input tokens	Dimensions	Input / 1M
`openai/text-embedding-3-small`	8,192	1,536	$0.02
`openai/text-embedding-3-large`	8,192	3,072	$0.13

Discover them at runtime instead of hardcoding: GET /v1/models returns output_modality on every entry, and embedding marks the ones this endpoint serves.

curl https://api.impossibl.com/v1/models \
  | jq '.data[] | select(.output_modality == "embedding") | .id'

Embed one string

curl https://api.impossibl.com/v1/embeddings \
  -H "Authorization: Bearer imp-rt-..." \
  -H 'content-type: application/json' \
  -d '{
    "model": "openai/text-embedding-3-small",
    "input": "the quick brown fox"
  }'

{
  "object": "list",
  "model": "openai/text-embedding-3-small",
  "data": [
    { "object": "embedding", "index": 0, "embedding": [0.0023, -0.0091, "..."] }
  ],
  "usage": { "prompt_tokens": 4, "total_tokens": 4 }
}

Embed a batch

Pass an array. Results come back in request order, and index records each vector’s position in your input — so you can zip them straight back onto your records.

curl https://api.impossibl.com/v1/embeddings \
  -H "Authorization: Bearer imp-rt-..." \
  -H 'content-type: application/json' \
  -d '{
    "model": "openai/text-embedding-3-small",
    "input": ["first document", "second document", "third document"]
  }'

Large batches are split into multiple upstream calls automatically and billed as one request. Each individual string must fit the model’s max input tokens, and a single request is capped at 300,000 tokens across all values.

OpenAI SDK

from openai import OpenAI

client = OpenAI(api_key="imp-rt-...", base_url="https://api.impossibl.com/v1")

res = client.embeddings.create(
    model="openai/text-embedding-3-small",
    input=["first document", "second document"],
)
print(len(res.data[0].embedding))  # 1536

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "imp-rt-...",
  baseURL: "https://api.impossibl.com/v1",
});

const res = await client.embeddings.create({
  model: "openai/text-embedding-3-small",
  input: ["first document", "second document"],
});
console.log(res.data[0].embedding.length); // 1536

Shorter vectors

dimensions truncates the vector, trading a little accuracy for storage and index size. Both text-embedding-3-* models support it.

curl https://api.impossibl.com/v1/embeddings \
  -H "Authorization: Bearer imp-rt-..." \
  -H 'content-type: application/json' \
  -d '{
    "model": "openai/text-embedding-3-large",
    "input": "the quick brown fox",
    "dimensions": 256
  }'

Billing does not change: you pay for input tokens, not for vector width.

Compact transport

encoding_format: "base64" returns each vector as base64-encoded little-endian float32 instead of a JSON number array. Same numbers, far fewer bytes on the wire. The OpenAI SDKs decode it for you; decoding by hand is four lines:

import base64, struct

raw = base64.b64decode(res.data[0].embedding)
vector = list(struct.unpack(f"<{len(raw) // 4}f", raw))

Errors

Embedding models are served only by this endpoint, and this endpoint serves only embedding models. Cross the streams and you get a 400 naming the right destination:

{
  "error": {
    "message": "openai/gpt-5.4 is not an embedding model. Use /v1/chat/completions.",
    "type": "invalid_request_error"
  }
}

Pre-tokenized input (arrays of integers) is not supported — send strings. See Errors for the full status table.

Get started

Core concepts

Using the API

Models

Embed one string

Embed a batch

OpenAI SDK

Shorter vectors

Compact transport

Errors

​Models

​Embed one string

​Embed a batch

​OpenAI SDK

​Shorter vectors

​Compact transport

​Errors

Models

Embed one string

Embed a batch

OpenAI SDK

Shorter vectors

Compact transport

Errors