SiliconFlow
API REFERENCE

Create a Rerank

Reranks documents by relevance to a query. Supports text, image, and video content.

POST
/rerank

Authorization

AuthorizationBearer <token>required

Set the header 'Authorization: Bearer {your API key}' for authentication

In: header

Header Parameters

X-Trace-Idstring

Request trace ID. You can pass a custom value to mark the request; if omitted, the platform generates one automatically. For troubleshooting, either this value or the x-siliconcloud-trace-id in the response header can be provided.

traceparentstring

The W3C Trace Context standard tracing header. When present, the platform uses its trace-id part as the tracing identifier of the request.

Request Body

modelstringrequired

Corresponding Model Name. To better enhance service quality, we will make periodic changes to the models provided by this service, including but not limited to model on/offlining and adjustments to model service capabilities. We will notify you of such changes through appropriate means such as announcements or message pushes where feasible. For a complete list of available models, please check the Models.

Example"BAAI/bge-reranker-v2-m3"
querystringrequired

The search query. Length must be ≥ 1.

Length1 <= length
Example"Apple"
documentsstring | arrayrequired

The list of documents to be ranked. Supports the following formats:

  • A single text string
  • An array of text strings At least 1 document is required.

Item: A single document item in the rerank input list.

instructionstring

The instruction for the reranker. Only supported by Qwen/Qwen3-Reranker-8B, Qwen/Qwen3-Reranker-4B, Qwen/Qwen3-Reranker-0.6B. Length must be ≥ 1.

Length1 <= length
Example"Please rerank the documents based on the query."
top_ninteger

Number of most relevant documents or indices to return. Must be ≥ 1.

Range1 <= value
Example4
return_documentsboolean

If false, the response does not include document text; if true, it includes the input document text. Default is false.

max_chunks_per_docinteger

Maximum number of chunks generated from within a document. Long documents are divided into multiple chunks for calculation, and the highest score among the chunks is taken as the document's score. Only BAAI/bge-reranker-v2-m3, Pro/BAAI/bge-reranker-v2-m3, netease-youdao/bce-reranker-base_v1 support this field. Must be ≥ 1, default is 1024.

Default1024
Range1 <= value
overlap_tokensinteger

Number of token overlaps between adjacent chunks when documents are chunked. Only BAAI/bge-reranker-v2-m3, Pro/BAAI/bge-reranker-v2-m3, netease-youdao/bce-reranker-base_v1 support this field. Must be between 0 and 80.

Rangevalue <= 80
modelstringrequired

The model name for multimodal reranking. Support models: Qwen/Qwen3-VL-Reranker-8B

Example"Qwen/Qwen3-VL-Reranker-8B"
querystring | objectrequired

The search query. Supports text string or content object.

  • Text query: a plain string
  • Image query: {"image": "https://example.com/image.jpg"} or base64

Length must be ≥ 1.

documentsarray<string | object | object>required

The list of documents to be ranked. Each item can be a text string or a content object.

  • Text document: a plain string
  • Text object: {"text": "document text"}
  • Image object: {"image": "https://example.com/image.jpg"} or base64

At least 1 document is required.

Example["apple","banana","fruit","vegetable"]

Item: A single document item in the VL rerank input list.

instructionstring

The instruction for the reranker. Only supported by Qwen/Qwen3-Reranker-8B, Qwen/Qwen3-Reranker-4B, Qwen/Qwen3-Reranker-0.6B. Length must be ≥ 1.

Length1 <= length
Example"Please rerank the documents based on the query."
top_ninteger

Number of most relevant documents or indices to return. Must be ≥ 1.

Range1 <= value
Example4
return_documentsboolean

If false, the response does not include document text; if true, it includes the input document text. Default is false.

max_chunks_per_docinteger

Maximum number of chunks generated from within a document. Must be ≥ 1, default is 1024.

Default1024
Range1 <= value
overlap_tokensinteger

Number of token overlaps between adjacent chunks when documents are chunked. Must be between 0 and 80.

Rangevalue <= 80

Response Body

The response from the model. The response header contains the x-siliconcloud-trace-id field, which serves as a unique identifier for tracing requests, facilitating log queries and issue troubleshooting; a user-supplied X-Trace-Id request header (if any) is returned as-is in that field. For troubleshooting, either trace ID is sufficient.

TypeScript Definitions

Use the response body type in TypeScript.

idstringrequired

Unique identifier for the response.

Example"rerank-20240115-abc123def456"
resultsarray<object>required

List of reranked results sorted by relevance score.

Item: A single rerank result.

metaobject

Metadata about the rerank response.

curl -X POST https://api.siliconflow.cn/v1/rerank \
  -H "Authorization: Bearer $SILICONFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "BAAI/bge-reranker-v2-m3",
    "query": "Apple",
    "documents": ["apple", "banana", "fruit", "vegetable"],
    "return_documents": true,
    "top_n": 4
  }'

import os
import requests

url = "https://api.siliconflow.cn/v1/rerank"
headers = {
    "Authorization": f"Bearer {os.environ.get('SILICONFLOW_API_KEY')}",
    "Content-Type": "application/json"
}
payload = {
    "model": "Qwen/Qwen3-VL-Reranker-8B",
    "query": {"image": "https://example.com/query-image.jpg"},
    "documents": [
        {"image": "https://example.com/doc1.jpg"},
        "A relevant text document..."
    ],
    "max_chunks_per_doc": 512
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

curl -X POST https://api.siliconflow.cn/v1/rerank \
  -H "Authorization: Bearer $SILICONFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen3-Reranker-8B",
    "query": "Find the most relevant technical docs",
    "documents": ["doc1", "doc2", "doc3"],
    "instruction": "Prefer recently published content",
    "overlap_tokens": 20
  }'

{
  "id": "rerank-20240115-abc123def456",
  "results": [
    {
      "index": 1,
      "document": {
        "text": "深度学习是机器学习的子集..."
      },
      "relevance_score": 0.85
    }
  ],
  "meta": {
    "tokens": {
      "input_tokens": 150,
      "output_tokens": 10,
      "image_tokens": 0
    },
    "billed_units": {
      "input_tokens": 150,
      "output_tokens": 10,
      "image_tokens": 0,
      "search_units": 1,
      "classifications": 0
    }
  }
}
{
  "code": 20012,
  "message": "string",
  "data": "string"
}
"Invalid token"
"Forbidden"
"404 page not found"
{
  "message": "Request was rejected due to rate limiting. If you want more, please contact contact@siliconflow.cn. Details:TPM limit reached.",
  "data": "string"
}
{
  "code": 50505,
  "message": "Model service overloaded. Please try again later.",
  "data": "string"
}
"string"

Create a Embedding POST

Converts input content into embedding vectors. Supports text, image URL/base64, and mixed lists.

Image Generation POST

Creates an image response for the given prompt. The URL for the generated image is valid for one hour. Please make sure to download and store it promptly to avoid any issues due to URL expiration.

Create a Rerank