cURL
curl --request POST \
--url https://nano-gpt.com/api/v1/embeddings \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"input": "<string>",
"model": "text-embedding-3-small",
"encoding_format": "float",
"dimensions": 256,
"user": "<string>"
}
'import requests
url = "https://nano-gpt.com/api/v1/embeddings"
payload = {
"input": "<string>",
"model": "text-embedding-3-small",
"encoding_format": "float",
"dimensions": 256,
"user": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
input: '<string>',
model: 'text-embedding-3-small',
encoding_format: 'float',
dimensions: 256,
user: '<string>'
})
};
fetch('https://nano-gpt.com/api/v1/embeddings', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://nano-gpt.com/api/v1/embeddings",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'input' => '<string>',
'model' => 'text-embedding-3-small',
'encoding_format' => 'float',
'dimensions' => 256,
'user' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://nano-gpt.com/api/v1/embeddings"
payload := strings.NewReader("{\n \"input\": \"<string>\",\n \"model\": \"text-embedding-3-small\",\n \"encoding_format\": \"float\",\n \"dimensions\": 256,\n \"user\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://nano-gpt.com/api/v1/embeddings")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"input\": \"<string>\",\n \"model\": \"text-embedding-3-small\",\n \"encoding_format\": \"float\",\n \"dimensions\": 256,\n \"user\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://nano-gpt.com/api/v1/embeddings")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"input\": \"<string>\",\n \"model\": \"text-embedding-3-small\",\n \"encoding_format\": \"float\",\n \"dimensions\": 256,\n \"user\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"object": "list",
"data": [
{
"object": "embedding",
"index": 0,
"embedding": [
123
]
}
],
"model": "text-embedding-3-small",
"usage": {
"prompt_tokens": 8,
"total_tokens": 8
}
}{
"error": 123,
"message": "<string>"
}Endpoint Examples
Embeddings
Create embeddings for text using OpenAI-compatible and alternative embedding models
POST
/
v1
/
embeddings
cURL
curl --request POST \
--url https://nano-gpt.com/api/v1/embeddings \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"input": "<string>",
"model": "text-embedding-3-small",
"encoding_format": "float",
"dimensions": 256,
"user": "<string>"
}
'import requests
url = "https://nano-gpt.com/api/v1/embeddings"
payload = {
"input": "<string>",
"model": "text-embedding-3-small",
"encoding_format": "float",
"dimensions": 256,
"user": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
input: '<string>',
model: 'text-embedding-3-small',
encoding_format: 'float',
dimensions: 256,
user: '<string>'
})
};
fetch('https://nano-gpt.com/api/v1/embeddings', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://nano-gpt.com/api/v1/embeddings",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'input' => '<string>',
'model' => 'text-embedding-3-small',
'encoding_format' => 'float',
'dimensions' => 256,
'user' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://nano-gpt.com/api/v1/embeddings"
payload := strings.NewReader("{\n \"input\": \"<string>\",\n \"model\": \"text-embedding-3-small\",\n \"encoding_format\": \"float\",\n \"dimensions\": 256,\n \"user\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://nano-gpt.com/api/v1/embeddings")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"input\": \"<string>\",\n \"model\": \"text-embedding-3-small\",\n \"encoding_format\": \"float\",\n \"dimensions\": 256,\n \"user\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://nano-gpt.com/api/v1/embeddings")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"input\": \"<string>\",\n \"model\": \"text-embedding-3-small\",\n \"encoding_format\": \"float\",\n \"dimensions\": 256,\n \"user\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"object": "list",
"data": [
{
"object": "embedding",
"index": 0,
"embedding": [
123
]
}
],
"model": "text-embedding-3-small",
"usage": {
"prompt_tokens": 8,
"total_tokens": 8
}
}{
"error": 123,
"message": "<string>"
}Overview
Create embeddings for text using OpenAI-compatible and alternative embedding models. NanoGPT supports 20+ embedding models (and this list changes over time); useGET /api/v1/embedding-models for the source-of-truth list.
Available Models
OpenAI Models
text-embedding-3-small- 1536 dimensions, $0.02/1M tokens - Most cost-effective with dimension reduction supporttext-embedding-3-large- 3072 dimensions, $0.13/1M tokens - Highest performance with dimension reduction supporttext-embedding-ada-002- 1536 dimensions, $0.10/1M tokens - Legacy model
Alternative Models
Multilingual:BAAI/bge-m3- 1024 dimensions, $0.01/1M tokens - Multilingual supportjina-clip-v1- 768 dimensions, $0.04/1M tokens - Multimodal CLIP embeddings
BAAI/bge-base-en-v1.5- 768 dimensions, $0.01/1M tokens - English (base)BAAI/bge-large-en-v1.5- 1024 dimensions, $0.01/1M tokens - English optimizedBAAI/bge-large-zh-v1.5- 1024 dimensions, $0.01/1M tokens - Chinese optimizedjina-embeddings-v2-base-en- 768 dimensions, $0.05/1M tokens - Englishjina-embeddings-v2-base-de- 768 dimensions, $0.05/1M tokens - Germanjina-embeddings-v2-base-zh- 768 dimensions, $0.05/1M tokens - Chinesejina-embeddings-v2-base-es- 768 dimensions, $0.05/1M tokens - Spanish
BAAI/bge-reranker-large- 1024 dimensions, $0.01/1M tokens - Rerankerjina-embeddings-v2-base-code- 768 dimensions, $0.05/1M tokens - Code embeddingsBaichuan-Text-Embedding- 1024 dimensions, $0.088/1M tokensnetease-youdao/bce-embedding-base_v1- 1024 dimensions, $0.02/1M tokenszhipu-embedding-2- 1024 dimensions, $0.07/1M tokensQwen/Qwen3-Embedding-0.6B- 1024 dimensions, $0.01/1M tokens - Supports dimension reductionQwen/Qwen3-Embedding-4B- 1536 dimensions, $0.03/1M tokens - Supports dimension reductionQwen/Qwen3-Embedding-8B- 1536 dimensions, $0.05/1M tokens - Supports dimension reductionjina-embeddings-v3- 1024 dimensions, $0.10/1M tokensjina-embeddings-v4- 2048 dimensions, $0.10/1M tokensgemini-embedding-001- 3072 dimensions, $0.15/1M tokensdoubao-embedding-large-text-240915- 4096 dimensions, $0.10/1M tokens
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
input | string or array | Yes | Single text string or array of up to 2048 strings to embed |
model | string | Yes | ID of the embedding model to use |
encoding_format | string | No | Format for embeddings: "float" (default) or "base64" |
dimensions | integer | No | Reduce embedding dimensions (only for supported models) |
user | string | No | Optional identifier for tracking usage |
Response Format
{
"object": "list",
"data": [
{
"object": "embedding",
"index": 0,
"embedding": [0.023, -0.012, 0.045, ...]
}
],
"model": "text-embedding-3-small",
"usage": {
"prompt_tokens": 8,
"total_tokens": 8
}
}
Code Examples
Python with OpenAI SDK
from openai import OpenAI
# Initialize client pointing to NanoGPT
client = OpenAI(
api_key="YOUR_NANOGPT_API_KEY",
base_url="https://nano-gpt.com/api/v1"
)
# Create embedding
response = client.embeddings.create(
input="Your text to embed",
model="text-embedding-3-small"
)
# Access the embedding
embedding = response.data[0].embedding
print(f"Embedding dimensions: {len(embedding)}")
JavaScript/TypeScript
import OpenAI from 'openai';
// Initialize client pointing to NanoGPT
const openai = new OpenAI({
apiKey: 'YOUR_NANOGPT_API_KEY',
baseURL: 'https://nano-gpt.com/api/v1'
});
// Create embedding
const response = await openai.embeddings.create({
input: "Your text to embed",
model: "text-embedding-3-small"
});
// Access the embedding
const embedding = response.data[0].embedding;
console.log(`Embedding dimensions: ${embedding.length}`);
cURL
curl https://nano-gpt.com/api/v1/embeddings \
-H "Authorization: Bearer YOUR_NANOGPT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"input": "Your text to embed",
"model": "text-embedding-3-small"
}'
Batch Processing
# Process multiple texts in a single request
texts = [
"First text to embed",
"Second text to embed",
"Third text to embed"
]
response = client.embeddings.create(
input=texts, # Pass array of strings
model="text-embedding-3-small"
)
# Access embeddings by index
for i, data in enumerate(response.data):
print(f"Text {i}: {len(data.embedding)} dimensions")
Dimension Reduction
For models that support it (text-embedding-3-small, text-embedding-3-large, Qwen/Qwen3-Embedding-0.6B, Qwen/Qwen3-Embedding-4B, Qwen/Qwen3-Embedding-8B):
# Reduce dimensions to 256 for faster similarity comparisons
response = client.embeddings.create(
input="Your text to embed",
model="text-embedding-3-small",
dimensions=256 # Reduce from 1536 to 256
)
Use Cases
Semantic Search
import numpy as np
from sklearn.metrics.pairwise import cosine_similarity
# Create embeddings for your documents
documents = ["Document 1 text", "Document 2 text", "Document 3 text"]
doc_embeddings = []
for doc in documents:
response = client.embeddings.create(input=doc, model="text-embedding-3-small")
doc_embeddings.append(response.data[0].embedding)
# Create embedding for search query
query = "Search query text"
query_response = client.embeddings.create(input=query, model="text-embedding-3-small")
query_embedding = query_response.data[0].embedding
# Calculate similarities
similarities = cosine_similarity([query_embedding], doc_embeddings)[0]
# Find most similar documents
top_matches = np.argsort(similarities)[::-1][:3]
for idx in top_matches:
print(f"Document {idx}: {similarities[idx]:.3f} similarity")
RAG (Retrieval Augmented Generation)
# 1. Embed and store your knowledge base
knowledge_base = [
{"text": "Fact 1...", "embedding": None},
{"text": "Fact 2...", "embedding": None},
]
for item in knowledge_base:
response = client.embeddings.create(
input=item["text"],
model="text-embedding-3-small"
)
item["embedding"] = response.data[0].embedding
# 2. For a user query, find relevant context
user_query = "What is...?"
query_response = client.embeddings.create(
input=user_query,
model="text-embedding-3-small"
)
query_embedding = query_response.data[0].embedding
# 3. Find most relevant facts
# relevant_facts = find_similar_texts(query_embedding, knowledge_base, top_k=3)
# 4. Use retrieved context with chat completion
chat_response = client.chat.completions.create(
model="gpt-4",
messages=[
{"role": "system", "content": f"Context: {relevant_facts}"},
{"role": "user", "content": user_query}
]
)
Best Practices
Model Selection
- General English text: Use
text-embedding-3-smallfor best price/performance - Maximum accuracy: Use
text-embedding-3-large - Multilingual: Use
BAAI/bge-m3or language-specific Jina models - Code: Use
jina-embeddings-v2-base-code - Budget-conscious: Use BAAI models at $0.01/1M tokens
Performance Optimization
- Batch requests: Send up to 2048 texts in a single request
- Use dimension reduction: Reduce dimensions for faster similarity calculations when exact precision isn’t critical
- Cache embeddings: Store computed embeddings to avoid re-processing identical texts
- Choose appropriate models: Don’t use 3072-dimension models if 768 dimensions suffice
Cost Optimization
- Monitor token usage: Track the
usagefield in responses - Use smaller models: Start with
text-embedding-3-smallbefore upgrading - Implement caching: Avoid re-embedding identical content
- Batch processing: Reduce API call overhead
Rate Limits
Rate limits vary by endpoint and account. See Rate Limits.Error Handling
The API returns standard HTTP status codes and OpenAI-compatible error responses: See also: Error Handling.{
"error": {
"message": "Invalid model specified",
"type": "invalid_request_error",
"param": "model",
"code": null
}
}
401: Invalid or missing API key400: Invalid request parameters429: Rate limit exceeded500: Server error
Authorizations
bearerAuthapiKeyAuth
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
application/json
Parameters for creating embeddings
Text to embed - single string or array of up to 2048 strings
ID of the embedding model to use
Example:
"text-embedding-3-small"
Format for embeddings
Available options:
float, base64 Reduce embedding dimensions (only for supported models)
Example:
256
Optional identifier for tracking usage