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
- Authenticate with an API key that has chats write permission (
chats.write.selfor equivalent). - Send
POST https://devs.ai/api/v1/embeddingswith a supported embeddingmodelandinput. - 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
| Model | Custom dimensions | Max dimensions |
|---|---|---|
text-embedding-3-small | Yes | 1536 |
text-embedding-3-large | Yes | 3072 |
text-embedding-ada-002 | No (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"
}
| Field | Required | Notes |
|---|---|---|
model | Yes | One of the embedding model ids above |
input | Yes | Text, batch of texts, or token ids (see limits above) |
encoding_format | No | float (default) or base64 |
dimensions | No | Only for text-embedding-3-*; must stay within that model’s max |
user | No | OpenAI 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.
Related topics
- Using APIs — authentication, scopes, and general REST usage.
- Threadless completions — OpenAI-compatible chat completions without persistent threads.
- API tutorial — build a small client against the chat APIs.