tencent cloud

LLM Service TokenHub

DocumentationLLM Service TokenHubAPI Integration GuideEmbedding Model

Embedding Model

Download
Focus Mode
Font Size
Last updated: 2026-07-09 19:33:28

Overview

Embedding models can convert input content such as text and images into vector representations. They are suitable for scenarios including semantic search, similarity calculation, text clustering, text classification, and cross-modal search.
TokenHub supports calling embedding models through APIs. The embedding models launched this time include text embedding models and multimodal embedding models.

Prerequisites

You have registered a Tencent Cloud account and activated the TokenHub service.
You have obtained the API Key in the TokenHub console.
You have installed the SDK for your programming language, or you can make HTTP requests directly.

Supported Models

Model Type
model Parameter Value
Output Dimension
Context Length
Recommended Scenario
Text Embedding Model
kinfra-text-embedding-0.6b
1024
32k
Large-scale text retrieval, latency-sensitive, cost-sensitive scenarios
Text Embedding Model
kinfra-text-embedding-4b
2560
32k
High-quality text search, deep semantic understanding scenarios
Multimodal EmbeddingModel
kinfra-vl-embedding-2b
2048
32k
Multimodal online search, video search, response-speed-first scenarios
Multimodal EmbeddingModel
kinfra-vl-embedding-8b
4096
32k
High-precision multimodal search, accuracy-first scenarios
Note:
All the above models support over 30 mainstream languages, including Chinese, English, Japanese, Korean, French, German, Russian, Portuguese, Spanish, and more.

Text Embedding

The text embedding API is used to convert text into vector representations. This API is compatible with the request and response structures of the OpenAI Embeddings API.

API address

POST https://tokenhub-intl.tencentcloudmaas.com/v1/embeddings

Request Parameters

Parameter
Type
Required
Description
model
String
Yes
The service ID. You can view it on the online inference service page. The service ID of a platform default service is the same as the model name; the service ID of a custom service is in the format ep-xxxxxxxx.
input
String or Array
Yes
The input text. It supports passing a single text string or an array of text strings. A single text string must not exceed 2000 characters. It is recommended that a single request contain no more than 128 text strings.
encoding_format
String
No
The vector encoding format. Only float is supported, and the default value is float.
dimensions
Integer
No
The output vector dimension is determined by the model and cannot be customized. The kinfra-text-embedding-0.6b model always outputs 1024 dimensions, and the kinfra-text-embedding-4b model always outputs 2560 dimensions.

Request Example

cURL
Python
Node.js
Go
Java
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/embeddings' \\
  -H 'Authorization: Bearer YOUR_API_KEY' \\
  -H 'Content-Type: application/json' \\
  -d '{
    "model": "kinfra-text-embedding-0.6b",
    Tencent Cloud TokenHub is a one-stop AI large model service platform.
    "encoding_format": "float"
  }'
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://tokenhub-intl.tencentcloudmaas.com/v1"
)

response = client.embeddings.create(
    model="kinfra-text-embedding-0.6b",
    input="Tencent Cloud TokenHub is a one-stop AI large model service platform.",
    encoding_format="float"
)

print(response.data[0].embedding)
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://tokenhub-intl.tencentcloudmaas.com/v1'
});

async function main() {
  const response = await client.embeddings.create({
    model: 'kinfra-text-embedding-0.6b',
    input: 'Tencent Cloud TokenHub is a one-stop AI large model service platform.',
    encoding_format: 'float'
  });

  console.log(response.data[0].embedding);
}

main();
package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

func main() {
    body, err := json.Marshal(map[string]interface{}{
        "model":           "kinfra-text-embedding-0.6b",
        "input": "Tencent Cloud TokenHub is a one-stop AI large model service platform.",
        "encoding_format": "float",
    })
    if err != nil {
        panic(err)
    }

    req, err := http.NewRequest("POST",
        "https://tokenhub-intl.tencentcloudmaas.com/v1/embeddings",
        bytes.NewBuffer(body))
    if err != nil {
        panic(err)
    }
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    data, err := io.ReadAll(resp.Body)
    if err != nil {
        panic(err)
    }
    fmt.Println(string(data))
}
import okhttp3.*;
import com.google.gson.Gson;
import java.util.*;

public class TextEmbeddingQuickStart {
    public static void main(String[] args) throws Exception {
        Map<String, Object> body = new HashMap<>();
        body.put("model", "kinfra-text-embedding-0.6b");
        body.put("input", "Tencent Cloud TokenHub is a one-stop AI large model service platform.");
        body.put("encoding_format", "float");

        Request request = new Request.Builder()
            .url("https://tokenhub-intl.tencentcloudmaas.com/v1/embeddings")
            .header("Authorization", "Bearer YOUR_API_KEY")
            .header("Content-Type", "application/json")
            .post(RequestBody.create(new Gson().toJson(body), MediaType.parse("application/json")))
            .build();

        try (Response response = new OkHttpClient().newCall(request).execute()) {
            System.out.println(response.body().string());
        }
    }
}

Batch Input Example

The following example shows how to pass in multiple texts for batch vectorization:
cURL
Python
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/embeddings' \\
  -H 'Authorization: Bearer YOUR_API_KEY' \\
  -H 'Content-Type: application/json' \\
  -d '{
    "model": "kinfra-text-embedding-0.6b",
    "input": ["What is RAG?", "Embedding models are used for semantic search models are used for semantic search.", "TokenHub is a one-stop AI large model service platform."]
  }'
response = client.embeddings.create(
    model="kinfra-text-embedding-0.6b",
    input=["What is RAG?", "Embedding models are used for semantic search.", "TokenHub is a one-stop AI large model service platform."]
)

for item in response.data:
    print(f"index={item.index}, dim={len(item.embedding)}")

Response Example

The following example only shows the response structure. Vector values and token counts are subject to the actual returned results.
{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.0123, -0.0456, 0.0789]
    }
  ],
  "model": "kinfra-text-embedding-0.6b",
  "usage": {
    "prompt_tokens": 10,
    "total_tokens": 10,
    "prompt_tokens_details": {
      "text_tokens": 10,
      "image_tokens": 0,
      "video_tokens": 0
    }
  }
}

Response Parameters

Basic Fields:
Parameter
Type
Description
object
String
Fixed as list
model
String
The model ID used for this request
data
Array
List of vector results
data[].object
String
Fixed as embedding
data[].index
Integer
The index of the input content within the request array
data[].embedding
Array
An array of vectors in floating-point format
usage field:
Parameter
Type
Description
usage.prompt_tokens
Integer
The total number of tokens consumed by the input content
usage.total_tokens
Integer
The total number of tokens consumed by this request
usage.prompt_tokens_details
Object
Input token details (segmented by modality in multimodal scenarios)
usage.prompt_tokens_details.text_tokens
Integer
The number of tokens consumed by text input
usage.prompt_tokens_details.image_tokens
Integer
The number of tokens consumed by image input
usage.prompt_tokens_details.video_tokens
Integer
The number of tokens consumed by video input

Multimodal Embedding

The multimodal embedding API is used to convert text, images, and videos into vector representations. It supports passing text, images, and videos in a single request, making it suitable for cross-modal search and multimodal semantic search scenarios.

API address

POST https://tokenhub-intl.tencentcloudmaas.com/v1/embeddings/multimodal

Request Parameters

Parameter
Type
Required
Description
model
String
Yes
The service ID. You can view it on the online inference service page. The service ID of a platform default service is the same as the model name; the service ID of a custom service is in the format ep-xxxxxxxx.
input
Array
Yes
A list of multimodal inputs. The element types supported are text, image_url, and video_url.
input[].type
String
Yes
The input type. Valid values: text, image_url, and video_url.
input[].text
String
No
The text content. Fill in this field when type is text.
input[].image_url
Object
No
The image URL object. Fill in this field when type is image_url.
input[].image_url.url
String
No
The image URL or base64 content.
input[].video_url
Object
No
The video URL object. Fill in this field when type is video_url.
input[].video_url.url
String
No
The video URL or base64 content.
instructions
String
No
The inference prompt. If not provided, the system generates a default value based on the input modality.
encoding_format
String
No
The vector encoding format. Only float is supported, and the default value is float.
dimensions
Integer
No
The output vector dimension is determined by the model and cannot be customized. The kinfra-vl-embedding-2b model always outputs 2048 dimensions, and the kinfra-vl-embedding-8b model always outputs 4096 dimensions.

Use Limits

Limit
Description
Multimodal Input Types
Only the following three types are supported: text, image_url, and video_url.
Image format
Supported formats include JPEG, PNG, WEBP, BMP, TIFF, and others.
Minimum image pixel quantity
4,096 (approximately 64 x 64)
Maximum image pixel quantity
1,843,200 (approximately 1280 x 1440)
Video format
Supported formats include MP4, AVI, and MOV.
Maximum total video pixel quantity
7,864,320
Maximum video sampling frame quantity
64
Video fps
Default: 1.0
Multimodal sequence length
The maximum sequence length is 32,768 tokens.
Vector normalization
Default L2 normalization
Encoding format.
Only float is supported; base64 is not supported.

Request Example

The following example shows text, images, and videos being passed in a single request. The model fuses content from multiple modalities into a single vector, which can be used for scenarios such as cross-modal search, video search, and multimodal semantic matching.
cURL
Python
Node.js
Go
Java
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/embeddings/multimodal' \\
  -H 'Authorization: Bearer YOUR_API_KEY' \\
  -H 'Content-Type: application/json' \\
  -d '{
    "model": "kinfra-vl-embedding-2b",
    "input": [
      {"type": "text", "text": "A white cat sits by the window."},
      {"type": "image_url", "image_url": {"url": "https://example.com/cat.png"}},
      {"type": "video_url", "video_url": {"url": "https://media.w3.org/2010/05/sintel/trailer.mp4"}}
    ],
    "instructions": "Generate vectors suitable for cross-modal search.",
    "encoding_format": "float"
  }'
import requests

url = "https://tokenhub-intl.tencentcloudmaas.com/v1/embeddings/multimodal"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "model": "kinfra-vl-embedding-2b",
    "input": [
        {"type": "text", "text": "A white cat sits by the window."},
        {"type": "image_url", "image_url": {"url": "https://example.com/cat.png"}},
        {"type": "video_url", "video_url": {"url": "https://media.w3.org/2010/05/sintel/trailer.mp4"}}
    ],
    "instructions": "Generate vectors suitable for cross-modal search.",
    "encoding_format": "float"
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())
async function main() {
  const response = await fetch('https://tokenhub-intl.tencentcloudmaas.com/v1/embeddings/multimodal', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      model: 'kinfra-vl-embedding-2b',
      input: [
        { type: 'text', text: 'A white cat sits by the window.' },
        { type: 'image_url', image_url: { url: 'https://example.com/cat.png' } },
        { type: 'video_url', video_url: { url: 'https://media.w3.org/2010/05/sintel/trailer.mp4' } }
      ],
      instructions: 'Generate vectors suitable for cross-modal search.',
      encoding_format: 'float'
    })
  });

  console.log(await response.json());
}

main();
package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

func main() {
    body, err := json.Marshal(map[string]interface{}{
        "model": "kinfra-vl-embedding-2b",
        "input": []map[string]interface{}{
            {"type": "text", "text": "A white cat sits by the window."},
            {"type": "image_url", "image_url": map[string]string{"url": "https://example.com/cat.png"}},
            {"type": "video_url", "video_url": map[string]string{"url": "https://media.w3.org/2010/05/sintel/trailer.mp4"}},
        },
        "instructions": "Generate vectors suitable for cross-modal search.",
        "encoding_format": "float",
    })
    if err != nil {
        panic(err)
    }

    req, err := http.NewRequest("POST",
        "https://tokenhub-intl.tencentcloudmaas.com/v1/embeddings/multimodal",
        bytes.NewBuffer(body))
    if err != nil {
        panic(err)
    }
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    data, err := io.ReadAll(resp.Body)
    if err != nil {
        panic(err)
    }
    fmt.Println(string(data))
}
import okhttp3.*;
import com.google.gson.Gson;
import java.util.*;

public class MultimodalEmbeddingQuickStart {
    public static void main(String[] args) throws Exception {
        Map<String, Object> body = new HashMap<>();
        body.put("model", "kinfra-vl-embedding-2b");

        List<Map<String, Object>> inputList = new ArrayList<>();
        inputList.add(Map.of("type", "text", "text", "A white cat sits by the window."));
        inputList.add(Map.of("type", "image_url", "image_url", Map.of("url", "https://example.com/cat.png")));
        inputList.add(Map.of("type", "video_url", "video_url", Map.of("url", "https://media.w3.org/2010/05/sintel/trailer.mp4")));
        body.put("input", inputList);
        body.put("instructions", "Generate vectors suitable for cross-modal search.");
        body.put("encoding_format", "float");

        Request request = new Request.Builder()
            .url("https://tokenhub-intl.tencentcloudmaas.com/v1/embeddings/multimodal")
            .header("Authorization", "Bearer YOUR_API_KEY")
            .header("Content-Type", "application/json")
            .post(RequestBody.create(new Gson().toJson(body), MediaType.parse("application/json")))
            .build();

        try (Response response = new OkHttpClient().newCall(request).execute()) {
            System.out.println(response.body().string());
        }
    }
}

Response Example

The following example only shows the response structure. Vector values and token counts are subject to the actual returned results.
Note:
The multimodal embedding API fuses the text, images, and videos from a single request into one vector. The data array in the response contains one vector result, and the index is fixed at 0.
{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.0123, -0.0456, 0.0789]
    }
  ],
  "model": "kinfra-vl-embedding-2b",
  "usage": {
    "prompt_tokens": 1057,
    "total_tokens": 1057,
    "prompt_tokens_details": {
      "text_tokens": 12,
      "image_tokens": 1045,
      "video_tokens": 0
    }
  }
}

Response Parameters

Basic Fields:
Parameter
Type
Description
object
String
Fixed as list
model
String
The model ID used for this request
data
Array
A list of vector results containing one fused vector
data[].object
String
Fixed as embedding
data[].index
Integer
Fixed as 0
data[].embedding
Array
An array of vectors in floating-point format
usage field:
Parameter
Type
Description
usage.prompt_tokens
Integer
The total number of tokens consumed by the input content
usage.total_tokens
Integer
The total number of tokens consumed by this request
usage.prompt_tokens_details
Object
Input token details, segmented by modality
usage.prompt_tokens_details.text_tokens
Integer
The number of tokens consumed by text input
usage.prompt_tokens_details.image_tokens
Integer
The number of tokens consumed by image input
usage.prompt_tokens_details.video_tokens
Integer
The number of tokens consumed by video input

Usage Recommendations

When batch processing is performed, it is recommended to control the number and length of inputs per request to avoid an excessively large request body.
In a production environment, it is recommended to pre-generate vectors for documents, images, or videos and store them in Tencent Cloud VectorDB. During querying, only the query vector needs to be generated to perform similarity search.

Pricing

The billing method and pricing for embedding models are subject to the model pricing documentation. For more information, see Model Pricing.

Application Example

Text Semantic Search

The following example demonstrates how to implement semantic search using a text embedding model: first, generate vectors for knowledge base documents; then, generate a vector for the user query; finally, match the most relevant documents via cosine similarity. This approach is suitable for scenarios such as intelligent Q&A, knowledge base search, and FAQ matching.
import numpy as np
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://tokenhub-intl.tencentcloudmaas.com/v1"
)

def cosine_similarity(a, b):
    denominator = np.linalg.norm(a) * np.linalg.norm(b)
    if denominator == 0:
        return 0
    return np.dot(a, b) / denominator

documents = [
    "Artificial Intelligence is a branch of Computer Science."
    "Machine Learning is an important method for achieving Artificial Intelligence."
    "Deep Learning is a subfield of Machine Learning."
]

# Generate Document Vectors
doc_resp = client.embeddings.create(
    model="kinfra-text-embedding-0.6b",
    input=documents
)
doc_embeddings = [item.embedding for item in doc_resp.data]

# Generate Query Vectors
query_resp = client.embeddings.create(
    model="kinfra-text-embedding-0.6b",
    input="What is AI?"
)
query_embedding = query_resp.data[0].embedding

# Calculate Similarity and Sort
similarities = [
    (i, cosine_similarity(query_embedding, doc_emb))
    for i, doc_emb in enumerate(doc_embeddings)
]
similarities.sort(key=lambda x: x[1], reverse=True)

for i, score in similarities:
    print(f"Similarity: {score:.3f} | Document: {documents[i]}")

Image and Video token Conversion

The multimodal embedding model converts images and videos into visual tokens and returns the corresponding usage in the response's usage.prompt_tokens_details.image_tokens and usage.prompt_tokens_details.video_tokens.

Image token Conversion

The number of image tokens is determined by the image resolution. The system first scales the image to within the pixel range supported by the model, and then calculates it according to the following rules:
1. Segment the image into patches of 28 x 28 pixels.
2. Merge patches in a 2 x 2 pattern.
3. The number of merged patches equals the number of image tokens.
The calculation formula is as follows:
h_patches = floor(Height / 28)
w_patches = floor(Width / 28)
h_merge = floor(h_patches / 2)
w_merge = floor(w_patches / 2)
image_tokens = h_merge × w_merge
Image Size
Calculation Process
image_tokens
512 x 512
18 x 18 patches, merged into 9 x 9.
81
1024 x 1024
36 x 36 patches, merged into 18 x 18.
324
1280 x 720
45 x 25 patches, merged into 22 x 12.
264
Note:
Images are first scaled to within the pixel range supported by the model. The actual number of tokens is determined by the usage.prompt_tokens_details.image_tokens in the API response.

Video token Conversion

The number of video tokens is determined jointly by the sampling frame rate and the number of image tokens per frame. The system first samples the video according to the frame rate, and then calculates each frame based on the image token rules.
The calculation method is as follows:
The number of sampled frames N = min(video duration (seconds) × fps, max_frames)
video_tokens ≈ N × tokens_per_frame
Among them:
Parameter
Description
fps
Sampling frame rate, default: 1.0
max_frames
Maximum sampling frame quantity, currently 64.
tokens_per_frame
The number of tokens calculated per frame according to the image token rule.
Note:
The resolution of each video frame is constrained by total_pixels / N. The actual number of tokens is determined by the usage.prompt_tokens_details.video_tokens in the API response.

Model Performance

Text Embedding Model (CMTEB)

Model
Parameter Count
Mean(Task)
Mean(Type)
Category
Clustering
Pairwise Classification
Reranking
Searching
STS
kinfra-text-embedding-0.6b
0.6B
66.64
67.83
71.46
68.60
76.84
64.16
71.01
54.88
kinfra-text-embedding-4b
4B
72.63
73.95
75.55
78.15
83.29
68.26
77.02
61.41

Multimodal Embedding Model

Model
Parameter quantity
MSCOCO_t2i
VisualNews_t2i
WebQA
EDIS
VisDial
Wiki-SS-NQ
Image-Text Search mean
MMEB-V2
kinfra-vl-embedding-2b
2B
0.70
0.60
0.87
0.80
0.69
0.53
0.698
69.82
kinfra-vl-embedding-8b
8B
0.76
0.67
0.90
0.89
0.87
0.68
0.795
75.26

Reference Documentation

Language Model Invocation Overview
TokenHub Console
Model Pricing
Previous Topic: Responses API Compatibility ModeNext Topic: CodeBuddy Code

Help and Support

Was this page helpful?

Help us improve! Rate your documentation experience in 5 mins.

Feedback