API Documentation

🌟 FG-CLIP Embedding API

This service extracts semantic features from input text or images and returns the corresponding embedding vectors.

An embedding is a list of n floating-point values, each representing one feature dimension. For this model version, n=768. Check the documentation when newer versions are released.

Embeddings can power text or image classifiers, semantic search, and recommendations so results reflect meaning rather than surface-level features.

A key advantage of FG-CLIP embeddings is fine-grained retrieval: use bbox to extract local features from a specified image region and text_box_flag to extract local features from the corresponding text.

Global image features: a feature vector representing the complete image.
Local image features represent content within a user-specified region. FG-CLIP extracts discriminative local features comparable to global-image representations, overcoming the global-only limitation of conventional methods.

API-1 通用Embedding 接口协议

🚀 Request Method Request method

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

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

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

🔐 Request headers

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

💾 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"
    }

curl command

    curl -X 'POST' 'https://api.research.360.cn/models/interface'
        -H 'accept: application/json'
        -H 'Content-Type: application/json'

📥 Request Body

The HTTP 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️⃣ `request_id`

string

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

2️⃣ model

string Required

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


---

### 3️⃣ input_type

`string` &nbsp; <span style="color:Coral">Required</span>

Specifies the input type sent to the service.

Allowed values:

- `text`: Use text as the input for this embedding request;
- `image`: Use images as the input for this embedding request.

```python
    request_body = {"input_type": "image",...} # python
    request_body = {"input_type": "text",...} # python

4️⃣ embedding_types

list of strings Required

Specifies the embedding data type to return. One or more of the following values are accepted; selecting a single type is recommended.

Allowed values:

float: Return FLOAT32 embedding vectors;
int8: Return INT8 embedding vectors;
uint8: Return UINT8 embedding vectors.

    request_body = {"embedding_types": ["float","int8","uint8"],...} # python

5️⃣ texts

list of strings Optional

A list of text inputs to embed.

Supports up to 32 text inputs per request. Each input can contain up to 196 tokens. Text exceeding the limit is truncated according to thetruncateparameter described in the truncate section below.

The text embedding service routes inputs under 64 tokens to the short-text model and inputs from 64 to 196 tokens to the long-text model.

When input_type is image, texts must be an empty list or omitted.

    text_inputs = ["an apple","a pikachu"]
    request_body = {
        "model": "fg-clip",
        "input_type": "text",
        "embedding_types": ["float"],
        "texts": text_inputs,
        ...
        } # python

6️⃣ images

list of strings Optional

Provide a list of up to 32 images for embedding.

The image list accepts image_url input["https://xxx.jpg",""]or base64-encoded image data["data:image/png;base64,base64_str",""]. URL input currently requires HTTP or HTTPS, a domain name rather than an IP address, and a filename ending injpg|jpeg|png|bmp.

When input_type is text, images must be an empty list or omitted.

    # image URL input
    image_inputs = ["https://xxxx.png","https://xxxx.jpg",]
    request_body = {
        "model": "fg-clip",
        "input_type": "image",
        "embedding_types": ["float"],
        "images": image_inputs,
        ...
        } # python

    # base64 image input
    import os
    import base64
    def batch_images_to_base64(folder_path):
        result = []
        # Map supported image formats to MIME types
        mime_types = {'.jpg': 'jpeg', '.jpeg': 'jpeg', '.png': 'png'}
        for filename in os.listdir(folder_path):
            filepath = os.path.join(folder_path,  filename)
            # Check whether the file is an image
            if not os.path.isfile(filepath):
                continue
            # Get the file extension and convert it to lowercase
            ext = os.path.splitext(filename)[1].lower()
            if ext not in mime_types:
                continue
            # Read and encode the file
            with open(filepath, 'rb') as f:
                img_data = f.read()
                base64_str = base64.b64encode(img_data).decode('utf-8')
                data_uri = f"data:image/{mime_types[ext]};base64,{base64_str}"
                result.append(data_uri)
    images_path = "/data/images/"
    images_base64 = batch_images_to_base64("/data/chenchuang/images")
    images_base64 = images_base64[:32]
    request_body = {
        "model": "fg-clip",
        "input_type": "image",
        "embedding_types": ["float"],
        "images": images_base64,
        ...
        } # python

7️⃣ truncate

strings Optional

The default isnone. none and start specify how the API handles text longer than 196 tokens when input_type is text.

start: Truncate from the beginning at the maximum token limit.
none: Do not truncate; return an error when the limit is exceeded. This is the default.

Whenstartthe leading content is discarded until the remaining input fits the model’s maximum token length.

    request_body = {
        "model": "fg-clip",
        "input_type": "text",
        "embedding_types": ["float"],
        "texts": text_inputs,
        "truncate": "none",
        ...
        } # python

    request_body = {"truncate": "start",...} # python

8️⃣ image_boxes

three-dimensional list of float Optional

The default is[]. When input_type="image", use this field to request local image features for fine-grained retrieval. Each image supports multiple boxes, and each box contains four floating-point values. When the request parameter isimage_boxes, returned embeddings correspond one-to-one with each image box. For example, when image_boxes is [[[x1,y1,w1,h1],[x2,y2,w2,h2]],[[x3,y3,w3,h3]]]and the input images are ["image1_url","image2_url"], and the returned embedding shape is 3*dim, the embeddings are ordered as image1_box1, image1_box2, and image2_box3.

Bounding-box coordinate reference

The diagram above shows how to define a box: choose a top-left point (x, y), then specify width w and height h as [x, y, w, h]. For an image of width W and height H, x+w must be no greater than W and y+h no greater than H. Box order must correspond to image order.


    boxes_info = [[[52.0,399.0,412.0,340.0]],...]
    request_body = {
        "model": "fg-clip",
        "input_type": "image",
        "embedding_types": ["float"],
        "images": image_inputs,
        "image_boxes":boxes_info,
        ...
        } # python

9️⃣ text_box_flag

Boolean Optional

The default isFalse. Use this field to request local text features for fine-grained retrieval when input_type="text".

    request_body = {
        "text_box_flag":True,
        ...
        } # python

🎰 Complete request body example

Python script

    text_body = {
        "model": "fg-clip",
        "input_type": input_type,
        "embedding_types": embedding_types,
        "texts": texts,
        "truncate": truncate, ## optional
        "text_box_flag":text_box_flag ## optional
    }

    image_body = {
        "model": "fg-clip",
        "input_type": input_type,
        "embedding_types": embedding_types,
        "images": images,
        "image_boxes":boxes_info ## optional
    }

curl command

    curl -X 'POST' 'https://api.research.360.cn/generate_embedding'
        -H 'accept: application/json'
        -H 'Content-Type: application/json'
        -d '{
            "model": "fg-clip",
            "input_type": "text",
            "embedding_types": ["float"],
            "texts": ["an apple","two apples"],
            "truncate": "start",
            "text_box_flag": false
        }'

    curl -X 'POST' 'https://api.research.360.cn/generate_embedding'
        -H 'accept: application/json'
        -H 'Content-Type: application/json'
        -d '{
            "model": "fg-clip",
            "input_type": "image",
            "embedding_types": ["float"],
            "images": ["https://xxxx.png","https://xxxx.jpg"],
            "image_boxes": [[7.03, 16.76, 149.32, 94.87]]
        }'

📤 Response

✅ context

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

{ "context": { "code": 0, "message": "OK", "timestamp": 1753086217 } }

✅ data

1️⃣ `request_id`

string

and the input parameterrequest_idmatch and are unique."request_id": "2691733a-d172-4b20-8aab-4ecfeb089141"

2️⃣ `embeddings`

object or null

Object containing embedding vectors in different data types. Seeembedding_types

The length of each embedding-type array matches the originaltexts/imagesarray length.

When the request parameter is input_type="text" && text_box_flag == True , emdedding["float"] returns the dense feature vector for long text.

When the request parameter is input_type="image" && len(image_boxes) == len(images), emdedding["float"] returns local features for the corresponding image box.

{
  "embeddings": {
    "float": [
      [
        0.01062996219843626, 0.026321588084101677, -0.0231630802154541,
        -0.0043367426842451096, 0.026321588084101677, -0.0231630802154541,
        ......
      ]
    ]
  }
}

Show 3 properties

`float`

list of lists of doubles or null

List of FLOAT32 embedding features.

`int8`

list of lists of integers or null

List of INT8 embedding features, with values from -128 to 127.

`uint8`

list of lists of integers or null

List of UINT8 embedding features, with values from 0 to 255.

3️⃣ `texts`

list of strings or null

Returns the length of each text item in the request.

{ "texts": ["275", "52", "50", "255"] }

4️⃣ `images`

list of objects or null

Returns dimension information for each input image.

{
  "images": [
    { "width": 1024, "height": 1542, "format": "JPEG", "bit_depth": 24 }
  ]
}

Show 4 properties

`width`

long

Image width in pixels.

`height`

long

Image height in pixels.

`format`

string

Image color format.

`bit_depth`

long

Image bit depth.

5️⃣ `meta`

object or null

Returns billing information for the request.

{
  "meta": {
    "api_version": { "version": "2.0.1" },
    "billed_units": {
      "images": 32,
      "input_tokens": 25600,
      "output_tokens": 0
    }
  }
}

Show 4 properties

`api_version`

object or null

`billed_units`

object or null

Show 3 properties

`images`

double or null

Number of billed images.

`input_tokens`

double or null

Number of billed input text tokens.

`output_tokens` . Defaults to `0`

double or null

Number of billed output text tokens. Output text tokens are always 0. Billing is based on the billed image count and billed input text tokens.

6️⃣ `created`

string or null Returns the time at which request processing began, formatted as%Y-%m-%d %H:%M:%S.%f

{ "created": "2025-07-10 10:23:24.946" }

🎰 Complete response example

{
  "context": { "code": 0, "message": "OK", "timestamp": 1753086217 },
  "data": {
    "id": "2691733a-d172-4b20-8aab-4ecfeb089141",
    "embeddings": {
      "float": [
        [
          0.01062996219843626, 0.026321588084101677, -0.0231630802154541,
          -0.0043367426842451096, 0.026321588084101677, -0.0231630802154541,
          ......
        ]
      ]
    },
    "texts": ["275", "52", "50", "255"],
    "images": [
      { "width": 1024, "height": 1542, "format": "JPEG", "bit_depth": 24 }
    ],
    "meta": {
      "api_version": { "version": "2.0.1" },
      "billed_units": {
        "images": 32,
        "input_tokens": 25600,
        "output_tokens": 0
      },
      "latencys": []
    },
    "created": "2025-07-10 10:23:24.946"
  }
}

API 2: OpenAI-compatible embedding protocol

from openai import OpenAI

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

response = client.embeddings.create(
    model="fg-clip",
    input=["xxxx"],
    encoding_format="float",
    extra_body={
        "request_id":" ",
        "input_type": "image",
        "truncate": "start",
        "image_boxes":[],
        "text_box_flag":False
    }
)

Resquest

model: see above
input is equivalent to the field described above: textsandimages
encoding_format supports onlyfloat
extra_body
- request_id: see above
- input_type: see above
- truncate: see above
- image_boxes: see above
- text_box_flag: see above

Response

follow the OpenAI CreateEmbeddingResponsetype

🔧 Image-Text Similarity Calculation

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

text-to-text similarity
text-to-image similarity
image-to-image 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. To normalize it to the range 0 to 1, use the following calculation:

import numpy as np

def logits(image_features, text_features):
    # Compute the matrix product of text and image features
    logits_per_text = np.matmul(text_features, image_features.T)

    # Scale factor and bias
    logit_scale = np.array([4.7500])
    logit_bias  = np.array([-16.7500])

    # Apply the scale and bias
    logits_per_text = logits_per_text * np.exp(logit_scale) + logit_bias

    # Transpose to obtain image logits
    logits_per_image = logits_per_text.T

    # Apply the sigmoid function
    sims_matrix = 1 / (1 + np.exp(-logits_per_image))
    sims_matrix = np.squeeze(sims_matrix, axis=-1)

    return sims_matrix

Text input

Image input

Copy

Response

Copy

Sign in required

🌟 FG-CLIP Embedding API

API-1 通用Embedding 接口协议

🚀 Request Method Request method

🔐 Request headers

💾 accept

📪 Content-Type

🎰 Complete header example

📥 Request Body

1️⃣ request_id

2️⃣ model

4️⃣ embedding_types

5️⃣ texts

6️⃣ images

7️⃣ truncate

8️⃣ image_boxes

9️⃣ text_box_flag

🎰 Complete request body example

📤 Response

✅ context

✅ data

1️⃣ request_id

2️⃣ embeddings

float

int8

uint8

3️⃣ texts

4️⃣ images

width

height

format

bit_depth

5️⃣ meta

api_version

billed_units

images

input_tokens

output_tokens . Defaults to 0

6️⃣ created

🎰 Complete response example

API 2: OpenAI-compatible embedding protocol

Resquest

Response

🔧 Image-Text Similarity Calculation

1️⃣ `request_id`

1️⃣ `request_id`

2️⃣ `embeddings`

`float`

`int8`

`uint8`

3️⃣ `texts`

4️⃣ `images`

`width`

`height`

`format`

`bit_depth`

5️⃣ `meta`

`api_version`

`billed_units`

`images`

`input_tokens`

`output_tokens` . Defaults to `0`

6️⃣ `created`