> ## Documentation Index
> Fetch the complete documentation index at: https://docs.siliconflow.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 创建重排序请求

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



## OpenAPI

````yaml post /rerank
openapi: 3.0.0
info:
  title: SiliconFlow API
  description: The SiliconFlow REST API
  version: 1.0.0
  contact:
    name: SiliconFlow Support
    url: https://www.siliconflow.cn/
  license:
    name: MIT
    url: https://github.com/siliconflow/siliconcloud/blob/main/LICENSE
servers:
  - url: https://api.siliconflow.cn/v1
security:
  - bearerAuth: []
paths:
  /rerank:
    post:
      tags:
        - Rerank
      summary: Create Rerank
      description: >-
        Reranks documents by relevance to a query. Supports text, image, and
        video content.
      operationId: createRerank
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RerankRequest'
      responses:
        '200':
          description: >-
            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.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RerankResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimit'
        '503':
          $ref: '#/components/responses/Overloaded'
        '504':
          $ref: '#/components/responses/Timeout'
      deprecated: false
      x-codeSamples:
        - lang: curl
          label: Text query with text documents
          source: |
            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
              }'
        - lang: curl
          label: Multimodal query with images
          source: |
            curl -X POST https://api.siliconflow.cn/v1/rerank \
              -H "Authorization: Bearer $SILICONFLOW_API_KEY" \
              -H "Content-Type: application/json" \
              -d '{
                "model": "Qwen/Qwen3-VL-Reranker-8B",
                "query": {
                  "image": "https://example.com/query-image.jpg"
                },
                "documents": [
                  {
                    "image": "https://example.com/doc1.jpg"
                  },
                  "这是一个相关的文本文档..."
                ],
                "max_chunks_per_doc": 512
              }'
        - lang: curl
          label: With instruction (specific models only)
          source: |
            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": "找出最相关的技术文档",
                "documents": ["文档1", "文档2", "文档3"],
                "instruction": "优先考虑最新发布的内容",
                "overlap_tokens": 20
              }'
components:
  schemas:
    RerankRequest:
      description: >
        Compatible with two request formats:

        - Classic Rerank: text query with text documents

        - Multimodal Rerank: supports image/video content in query and documents


        Note: OpenAPI cannot automatically route schemas based on `model`.
        Choose parameters according to model capabilities.
      anyOf:
        - $ref: '#/components/schemas/RerankClassicRequest'
        - $ref: '#/components/schemas/RerankVLRequest'
    RerankResponse:
      type: object
      required:
        - id
        - results
      properties:
        id:
          type: string
          description: Unique identifier for the response.
          example: rerank-20240115-abc123def456
        results:
          type: array
          description: List of reranked results sorted by relevance score.
          items:
            $ref: '#/components/schemas/RerankResult'
        meta:
          $ref: '#/components/schemas/RerankResponseMeta'
    RerankClassicRequest:
      title: RerankClassicRequest
      type: object
      required:
        - model
        - query
        - documents
      properties:
        model:
          type: string
          description: >-
            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](https://cloud.siliconflow.cn/sft-d29cs9gh3vvc73c59kb0/models?types=rerank)**.
          example: BAAI/bge-reranker-v2-m3
        query:
          type: string
          description: The search query. Length must be ≥ 1.
          example: Apple
          minLength: 1
        documents:
          description: |
            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.
          oneOf:
            - type: string
              title: string
              description: A single text document.
              example: apple
            - type: array
              title: array
              description: An array of text strings or content objects.
              minItems: 1
              items:
                $ref: '#/components/schemas/RerankDocumentItem'
              example:
                - apple
                - banana
                - fruit
                - vegetable
        instruction:
          type: string
          description: >-
            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.
          example: Please rerank the documents based on the query.
          minLength: 1
        top_n:
          type: integer
          description: Number of most relevant documents or indices to return. Must be ≥ 1.
          example: 4
          minimum: 1
        return_documents:
          type: boolean
          description: >-
            If false, the response does not include document text; if true, it
            includes the input document text. Default is false.
          default: false
        max_chunks_per_doc:
          type: integer
          description: >-
            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.
          default: 1024
          minimum: 1
        overlap_tokens:
          type: integer
          description: >-
            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.
          minimum: 0
          maximum: 80
    RerankVLRequest:
      title: RerankVLRequest
      type: object
      required:
        - model
        - query
        - documents
      properties:
        model:
          type: string
          description: >-
            The model name for multimodal reranking. Support models:
            Qwen/Qwen3-VL-Reranker-8B
          example: Qwen/Qwen3-VL-Reranker-8B
        query:
          description: >
            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.
          oneOf:
            - type: string
              title: string
              description: Text query string.
              example: Apple
              minLength: 1
            - $ref: '#/components/schemas/RerankImageUrlContent'
        documents:
          description: >
            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.
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/RerankVLDocumentItem'
          example:
            - apple
            - banana
            - fruit
            - vegetable
        instruction:
          type: string
          description: >-
            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.
          example: Please rerank the documents based on the query.
          minLength: 1
        top_n:
          type: integer
          description: Number of most relevant documents or indices to return. Must be ≥ 1.
          example: 4
          minimum: 1
        return_documents:
          type: boolean
          description: >-
            If false, the response does not include document text; if true, it
            includes the input document text. Default is false.
          default: false
        max_chunks_per_doc:
          type: integer
          description: >-
            Maximum number of chunks generated from within a document. Must be ≥
            1, default is 1024.
          default: 1024
          minimum: 1
        overlap_tokens:
          type: integer
          description: >-
            Number of token overlaps between adjacent chunks when documents are
            chunked. Must be between 0 and 80.
          minimum: 0
          maximum: 80
    RerankResult:
      type: object
      description: A single rerank result.
      properties:
        index:
          type: integer
          description: The index of the document in the original input list.
          example: 1
        document:
          description: >-
            Original document content. Only returned when
            `return_documents=true`.
          oneOf:
            - $ref: '#/components/schemas/RerankTextDocument'
            - $ref: '#/components/schemas/RerankImageDocument'
        relevance_score:
          type: number
          description: Relevance score (0-1, higher is more relevant).
          example: 0.85
    RerankResponseMeta:
      type: object
      description: Metadata about the rerank response.
      properties:
        tokens:
          $ref: '#/components/schemas/RerankResponseMetaTokens'
        billed_units:
          $ref: '#/components/schemas/RerankResponseMetaBilledUnits'
    BadRquestData:
      type: object
      required:
        - message
        - data
        - code
      properties:
        code:
          type: integer
          nullable: true
          default: false
          example: 20012
        message:
          type: string
          nullable: false
        data:
          type: string
          nullable: false
    UnauthorizedData:
      type: string
      default: false
      example: Invalid token
    ForbiddenData:
      type: string
      default: false
      example: Forbidden
    NotFoundData:
      type: string
      default: false
      example: 404 page not found
    RateLimitData:
      type: object
      required:
        - message
        - data
      properties:
        message:
          type: string
          example: >-
            Request was rejected due to rate limiting. If you want more, please
            contact contact@siliconflow.cn. Details:TPM limit reached.
        data:
          type: string
    OverloadedtData:
      type: object
      required:
        - code
        - message
        - data
      properties:
        code:
          type: integer
          example: 50505
        message:
          type: string
          example: Model service overloaded. Please try again later.
        data:
          type: string
          nullable: false
    TimeoutData:
      type: string
    RerankDocumentItem:
      description: A single document item in the rerank input list.
      oneOf:
        - type: string
          description: Text document string.
          example: apple
        - $ref: '#/components/schemas/RerankTextContent'
        - $ref: '#/components/schemas/RerankImageUrlContent'
    RerankImageUrlContent:
      type: object
      description: Image content object for reranking.
      properties:
        image:
          type: string
          description: Image URL or base64-encoded image content.
          example: https://example.com/image.jpg
      required:
        - image
    RerankVLDocumentItem:
      description: A single document item in the VL rerank input list.
      oneOf:
        - type: string
          description: Text document string.
          example: apple
        - $ref: '#/components/schemas/RerankTextContent'
        - $ref: '#/components/schemas/RerankImageUrlContent'
    RerankTextDocument:
      type: object
      description: Text document content in the rerank result.
      properties:
        text:
          type: string
          description: The text content of the document.
          example: 深度学习是机器学习的子集...
    RerankImageDocument:
      type: object
      description: Image document content in the rerank result.
      properties:
        image:
          type: string
          description: >-
            Base64-encoded image data or URL (sensitive information is
            redacted).
    RerankResponseMetaTokens:
      type: object
      description: Token usage statistics.
      properties:
        input_tokens:
          type: integer
          description: Number of input tokens.
          example: 150
        output_tokens:
          type: integer
          description: Number of output tokens.
          example: 10
        image_tokens:
          type: integer
          description: Number of input image tokens.
          example: 0
    RerankResponseMetaBilledUnits:
      type: object
      description: Billed units statistics.
      properties:
        input_tokens:
          type: integer
          description: Number of billed input tokens.
          example: 150
        output_tokens:
          type: integer
          description: Number of billed output tokens.
          example: 10
        image_tokens:
          type: integer
          description: Number of billed image tokens.
          example: 0
        search_units:
          type: integer
          description: Number of search units.
          example: 1
        classifications:
          type: integer
          description: Number of classification units.
          example: 0
    RerankTextContent:
      type: object
      description: Text content object for reranking.
      properties:
        text:
          type: string
          description: Text content.
          example: The quick brown fox
      required:
        - text
  responses:
    BadRequest:
      description: BadRequest
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BadRquestData'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnauthorizedData'
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ForbiddenData'
    NotFound:
      description: NotFound
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotFoundData'
    RateLimit:
      description: RateLimit
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitData'
    Overloaded:
      description: Overloaded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OverloadedtData'
    Timeout:
      description: Timeout
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TimeoutData'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: your api key
      description: >-
        Use the following format for authentication: Bearer [<your api
        key>](https://cloud.siliconflow.cn/account/ak)

````