Skip to main content

Embeddings API

Devs.ai exposes an OpenAI-compatible embeddings endpoint at POST /api/v1/embeddings. Point an OpenAI client at {your host}/api/v1 and call embeddings.create the same way you would against OpenAI.

Use this when you need vector embeddings for search, clustering, or other retrieval workflows outside of chat threads. Usage is metered with the rest of your organization’s AI spend (chat balance), with your organization’s markup applied.

How it works​

  1. Authenticate with an API key that has chats write permission (chats.write.self or equivalent).
  2. Send POST https://devs.ai/api/v1/embeddings with a supported embedding model and input.
  3. Receive an OpenAI-style response with one embedding per input, in input order.

Embedding models appear on GET /api/v1/models. They are not chat-picker models.

Supported models​

ModelCustom dimensionsMax dimensions
text-embedding-3-smallYes1536
text-embedding-3-largeYes3072
text-embedding-ada-002No (omit dimensions)1536 (fixed)

Basic usage​

Single string​

curl -X POST https://devs.ai/api/v1/embeddings \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "text-embedding-3-small",
"input": "The food was delicious and the waiter was friendly.",
"encoding_format": "float"
}'

Batch of strings​

input can be an array of up to 2048 strings (or token-id arrays). Each input is limited to 8191 tokens.

curl -X POST https://devs.ai/api/v1/embeddings \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "text-embedding-3-small",
"input": ["First document", "Second document"]
}'

OpenAI client​

Set the client base URL to your host’s /api/v1 path:

import OpenAI from "openai";

const client = new OpenAI({
apiKey: process.env.TOKEN,
baseURL: "https://devs.ai/api/v1",
});

const response = await client.embeddings.create({
model: "text-embedding-3-small",
input: "The food was delicious and the waiter was friendly.",
});

Request format​

{
"model": "text-embedding-3-small",
"input": "string, string[], token ids, or token-id arrays",
"encoding_format": "float",
"dimensions": 1536,
"user": "optional string — accepted for client compatibility, not used for billing"
}
FieldRequiredNotes
modelYesOne of the embedding model ids above
inputYesText, batch of texts, or token ids (see limits above)
encoding_formatNofloat (default) or base64
dimensionsNoOnly for text-embedding-3-*; must stay within that model’s max
userNoOpenAI client compatibility only

Authorization: API key with chats write scope. See Using APIs.

Idempotency: Send an Idempotency-Key header (up to 191 characters) so a retry of the same request is not charged twice.

Billing​

Prompt tokens for embeddings are billed on the chat balance at the published embedding rate. Prepaid plans are checked before the provider is called; if the balance is denied, the provider is not called. Post-paid plans are metered. Activity for these calls can appear under Usage & Billing for organizations on dollar-based billing.

⌘J