Embeddings
Generate vector embeddings for search, clustering, classification, and RAG.
Endpoint
POST /v1/embeddingsThe OpenAI-compatible Embeddings API turns text into vectors. Use any OpenAI SDK client pointed at the Yunxin base URL.
Request
{
"model": "model-id",
"input": "The quick brown fox jumps over the lazy dog.",
"encoding_format": "float"
}Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
model | string | Yes | Embedding model ID (query GET /v1/models?type=embedding). |
input | string / array | Yes | A string, an array of strings, or — on natively multimodal models — media and part groups (see Multimodal input). |
encoding_format | string | No | float (default) or base64. |
dimensions | integer | No | Output dimensionality, if the model supports it. |
Response
{
"object": "list",
"data": [
{
"object": "embedding",
"index": 0,
"embedding": [0.0023, -0.0091, 0.0152]
}
],
"model": "model-id",
"usage": {
"prompt_tokens": 10,
"total_tokens": 10
}
}Examples
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["YUNXIN_API_KEY"],
base_url="https://api.yuhuanstudio.com/v1",
)
response = client.embeddings.create(
model="model-id",
input="The quick brown fox jumps over the lazy dog.",
)
print(len(response.data[0].embedding))Batch embeddings
Pass an array to input to embed many texts in one request. Results align by index:
response = client.embeddings.create(
model="model-id",
input=[
"First document text",
"Second document text",
"Third document text",
],
)
for item in response.data:
print(f"Index {item.index}: {len(item.embedding)} dimensions")Multimodal input
Natively multimodal embedding models (such as gemini-embedding-2) map text, images, audio, video and
documents into one vector space, so an image and the sentence describing it can be compared directly.
Media is addressed in three ways, anywhere a string is accepted:
| Form | Example |
|---|---|
| Data URI | data:image/png;base64,iVBORw0… |
| Object storage | gs://bucket/clip.mp4 |
| File API handle | files/abc123 |
Anything else stays text — including a bare https:// URL, which is embedded as the literal string.
response = client.embeddings.create(
model="gemini-embedding-2",
input=[
"a golden retriever running on a beach",
"data:image/png;base64,iVBORw0KGgo…",
],
)
# → two vectors in the same space; compare them with cosine similarityTo combine several parts into a single vector, wrap them in a nested array:
response = client.embeddings.create(
model="gemini-embedding-2",
input=[["a golden retriever running on a beach", "data:image/png;base64,iVBORw0KGgo…"]],
)
# → one vector describing the text and the image togetherChat-style content parts work too, if that is what your SDK produces:
{
"model": "gemini-embedding-2",
"input": [{ "type": "image_url", "image_url": { "url": "data:image/png;base64,iVBORw0KGgo…" } }]
}Text-only models reject media with a provider_feature_not_supported error rather than embedding the
text and discarding the image — a silently text-only vector would be indistinguishable from a correct one.
Reducing dimensions
When a model supports it, request a smaller vector with dimensions to save storage and speed up
similarity search:
response = client.embeddings.create(
model="model-id",
input="Vector databases store embeddings.",
dimensions=512,
)Available models
Embedding models and their dimensions vary by provider. Discover what's live at runtime:
curl "https://api.yuhuanstudio.com/v1/models?type=embedding" \
-H "Authorization: Bearer $YUNXIN_API_KEY"Check each model's record via GET /v1/models/{model_id} for its native dimensions
and whether the dimensions parameter is supported.
Use cases
- Semantic search — rank documents by similarity to a query.
- Clustering — group related texts.
- Classification — categorize by comparing against labeled examples.
- RAG — retrieve relevant context for generation pipelines.
How is this guide?