API Documentation

🌟 RzenEmbed API

RzenEmbed is an OpenAI-compatible multimodal embedding service. It extracts deep semantic features from text, images, video, and visual documents containing both text and images, returning normalized embedding vectors.

Vector specifications and flexible configuration

An embedding is a one-dimensional array of floating-point values, with each value representing one semantic feature dimension:

Default output: 2,048 dimensions for optimal retrieval accuracy
On-demand truncation: choose 256, 512, 768, or 1,024 dimensions with minimal accuracy loss and substantially lower storage and retrieval compute costs
Lossless quantization: native int8 quantization further reduces storage without affecting retrieval quality

Core capabilities andUse cases

RzenEmbed maps text, images, video, and visual documents into one cross-modal semantic space. Vectors from every modality can be matched directly, extending beyond the limits of conventional unimodal embedding models.

RzenEmbed follows instructions to focus semantic representation on a user’s intent. It supports same-modality, cross-modal, and mixed multimodal retrieval for complex enterprise knowledge scenarios, including multilingual retrieval in English and Chinese. It is a foundation for enterprise multimodal RAG, intelligent knowledge bases, and recommendation systems.

🚀 Request Method Request method

Send text and image data with POST to receive embedding features.

    # python
    import requests
    url = "https://api.research.360.cn/v1/embeddings"
    resp = requests.post(url=url,...)

    # curl
    curl -X 'POST' 'https://api.research.360.cn/v1/embeddings'

🔐 Request headers

HTTP request headers provide metadata the server uses to process a request, including client information, content type, and caching directives.

🔑 Authorization

string Required HTTPS request header

UsesBearer <token> authentication, where token is your authentication token.

    header = {"Authorization":"Bearer your_key",...} # python
    -H 'Authorization:Bearer your_key'  # curl

💾 accept

string Required HTTPS request header

The MIME types the client can process, indicating the expected response format, such as application/json.

    header = {"accept": "application/json",...} # python
    -H 'accept: application/json'  # curl

📪 Content-Type

string Required HTTPS request header

Specifies the format of data sent by the client, such as application/json.

    header = {"Content-Type": "application/json",...} # python
    -H 'Content-Type: application/json'  # curl

🎰 Complete header example

Python script

    header = {
        "accept": "application/json",
        "Content-Type": "application/json",
        "Authorization":"Bearer your_key"
    }

curl command

    curl -X 'POST' 'https://api.research.360.cn/v1/embeddings'
        -H 'accept: application/json'
        -H 'Content-Type: application/json'
        -H 'Authorization:Bearer your_key'

📥 Request Body

The HTTPS request body carries data from the client to the server. Its format and media type are defined by the Content-Type header.

For this service, the body is required and must be a JSON string.

1️⃣ model

string Required

Model used by this service. One model is currently available: RzenEmbed . ```python request_body = {"model": "RzenEmbed",...} # python


---

### 2️⃣ dimensions

`int` &nbsp; <span style="color:Coral">Optional</span>

Requested output dimension. This integer defaults to 2,048 and supports 256, 512, 768, 1,024, 1,536, or 2,048.

```python
    request_body = {"dimensions": 1024,...} # python

3️⃣ instruction

string Optional

Instruction used to guide the model. Use a clear instruction for best accuracy. Default: "Represent the user's input."

    request_body = {"instruction": "Represent the user's input.",...} # python

4️⃣ texts

list of strings Optional

Multimodal text input. Only one text item is allowed.

    request_body = {"texts": ["find apples"],...} # python

5️⃣ images

list of strings Optional

Multimodal image input. Only one image is allowed.

    # image URL input
    request_body = {"images": ["https://xxxx.png"],...} # python

    # base64 image input
    import os
    import base64
    def image_to_base64(image_path):
        with open(image_path, "rb") as f:
            img_data = f.read()
            base64_str = base64.b64encode(img_data).decode("utf-8")
            ext = os.path.splitext(image_path)[1].lower()
            return f"data:image/{ext[1:]};base64,{base64_str}"
    image_path = "/data/images/demo.png"
    image_base64 = image_to_base64(image_path)
    request_body = {"images": [image_base64],...} # python

6️⃣ video

list of strings Optional

Multimodal video input represented by 2–64 frames, each provided as a URL or base64-encoded image.

    request_body = {"video": ["","",],...} # python

🎰 Complete request body example

Python script

import uuid
from openai import OpenAI

client = OpenAI(base_url="https://api.research.360.cn/v1", api_key="your_key")

response = client.embeddings.create(
    model="RzenEmbed",
    input=[],
    dimensions=2048,
    extra_body={
        "request_id": str(uuid.uuid4()),
        "texts": ["two apples"],
        "instruction": "Find me an everyday image that matches the given caption:",
        "images": ["https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen-VL/assets/demo.jpeg"],
    },
)
print(response)

response = client.embeddings.create(
    model="RzenEmbed",
    input=[],
    dimensions=2048,
    extra_body={
        "request_id": str(uuid.uuid4()),
        "instruction": "Find me an everyday video that matches the given caption:",
        "video": [
          "https://p0.ssl.qhimg.com/d/inn/20b6511288e3/Catch_med_5/10000.jpg",
          "https://p0.ssl.qhimg.com/d/inn/20b6511288e3/Catch_med_5/10001.jpg",
          "https://p0.ssl.qhimg.com/d/inn/20b6511288e3/Catch_med_5/10002.jpg"
          ],
    },
)
print(response)

curl command

    curl -X 'POST' 'https://api.research.360.cn/v1/embeddings'
        -H 'accept: application/json'
        -H 'Content-Type: application/json'
        -H 'Authorization:Bearer your_key'
        -d '{
            "model": "RzenEmbed",
            "request_id":"5fe3f69f-e4df-47c9-8ceb-c5c3cbe65daf",
            "dimensions":2048,
            "instruction": "Find me an everyday image that matches the given caption:",
            "texts": ["two apples"],
            "images": ["https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen-VL/assets/demo.jpeg"]
            }'

    curl -X 'POST' 'https://api.research.360.cn/v1/embeddings'
        -H 'accept: application/json'
        -H 'Content-Type: application/json'
        -H 'Authorization:Bearer your_key'
        -d '{
            "model": "RzenEmbed",
            "request_id":"5fe3f69f-e4df-47c9-8ceb-c5c3cbe65daf",
            "dimensions":2048,"instruction": "Find me an everyday image that matches the given caption:",
            "video": [
                "https://p0.ssl.qhimg.com/d/inn/20b6511288e3/Catch_med_5/10000.jpg",
                "https://p0.ssl.qhimg.com/d/inn/20b6511288e3/Catch_med_5/10001.jpg"
                ]
            }'

📤 Response

✅ context

code int: 0 Indicates success
messages string : "OK" Indicates success
timestamp long long : timestamp

{
  "context": { "code": 0, "message": "OK", "timestamp": 1769589915 },
  "data": {
    "data": [
      {
        "embedding": [-0.07196125388145447, -0.0329570434987545, 0.0068786488845944405],
        "index": 0,
        "object": "embedding"
      }
    ],
    "model": "RzenEmbed",
    "object": "list",
    "usage": {
      "prompt_tokens": 1761,
      "total_tokens": 1761
    },
    "message": "success",
    "response_status": 0,
    "request_id": "b978be6f-151d-4758-9fdc-b25e19019801"
  }
}

✅ data

Within resp["data"], the data, model, object, and usage fields follow the OpenAI embeddings response format. Other fields are described below.

1️⃣ `request_id`

string

Unique service request identifier generated with UUIDv4."id": "2691733a-d172-4b20-8aab-4ecfeb089141"

2️⃣ `response_status`

int

Embedding request status code: 0 indicates success; any nonzero value indicates failure.

3️⃣ `message`

string

Embedding request status message: success indicates a successful request; any other value indicates failure.

🎰 Complete response example

{
  "context": { "code": 0, "message": "OK", "timestamp": 1769589915 },
  "data": {
    "data": [
      {
        "embedding": [-0.07196125388145447, -0.0329570434987545, 0.0068786488845944405],
        "index": 0,
        "object": "embedding"
      }
    ],
    "model": "RzenEmbed",
    "object": "list",
    "usage": {
      "prompt_tokens": 1761,
      "total_tokens": 1761
    },
    "message": "success",
    "response_status": 0,
    "request_id": "b978be6f-151d-4758-9fdc-b25e19019801"
  }
}

🔧 Image-Text-Video Similarity Calculation

After obtaining embedding vectors, the following similarity calculations are supported:

text-to-text similarity
text-to-image similarity
text-to-video similarity
image-to-image similarity
image-to-video similarity
video-to-video similarity

using standard cosine similarity.

    import torch

    image_features = torch.tensor(image_embeddings["float"])
    text_features  = torch.tensor(text_embeddings["float"])

    probs = image_features @ text_features.T
    print(probs.shape)
    print("Label probs:", probs)

Cosine similarity ranges from -1 to +1.

Single-text embedding

Single-image embedding

Single-video embedding

Mixed image–text embedding

Copy

Response

Copy

Sign in required

🌟 RzenEmbed API

Vector specifications and flexible configuration

Core capabilities andUse cases

🚀 Request Method Request method

🔐 Request headers

🔑 Authorization

💾 accept

📪 Content-Type

🎰 Complete header example

📥 Request Body

1️⃣ model

3️⃣ instruction

4️⃣ texts

5️⃣ images

6️⃣ video

🎰 Complete request body example

📤 Response

✅ context

✅ data

1️⃣ request_id

2️⃣ response_status

3️⃣ message

🎰 Complete response example

🔧 Image-Text-Video Similarity Calculation

1️⃣ `request_id`

2️⃣ `response_status`

3️⃣ `message`