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

# Réorganiser les documents

> Réorganise les documents par pertinence par rapport à une requête

Réorganisez les documents à l'aide de modèles de similitude sémantique. Utile pour améliorer les résultats de recherche et les applications RAG.

## Corps de la requête

**Timeout des requêtes synchrones :** cet endpoint non-chat attend que le modèle routé termine son traitement. Les entrées volumineuses, les longs fichiers audio ou les grands lots peuvent dépasser les valeurs par défaut courantes de 30s côté client ; configurez donc le timeout de votre client HTTP à au moins `120s`.

<ParamField body="model" type="string" required>
  ID du modèle de reranker à utiliser (par ex., `qwen3-vl-rerank`).
</ParamField>

<ParamField body="query" type="string" required>
  La requête par rapport à laquelle classer les documents. Longueur maximale : `32,000` caractères.
</ParamField>

<ParamField body="documents" type="array" required>
  Liste de documents (chaînes de caractères) à réorganiser. Limites : jusqu'à `1,000` documents, chaque document jusqu'à `100,000` caractères, et au plus `2,000,000` caractères de documents au total.
</ParamField>

<ParamField body="top_n" type="integer">
  Nombre de meilleurs résultats à retourner. Par défaut, tous les documents. Doit être au moins `1` et ne pas dépasser `documents.length`. TokenLab n'applique actuellement aucun plafond public plus bas propre à un fournisseur ; si cette limite change, cette page sera mise à jour avant son application.
</ParamField>

<ParamField body="return_documents" type="boolean" default="false">
  Indique s'il faut inclure le texte original du document dans la réponse.
</ParamField>

## Réponse

<ResponseField name="results" type="array">
  Liste classée des documents avec scores.

  Chaque résultat contient :

  * `index` (integer) : Index du document original
  * `relevance_score` (number) : Score de pertinence (0-1)
  * `document` (string) : Texte original (si `return_documents=true`)
</ResponseField>

<ResponseField name="model" type="string">
  Le modèle utilisé pour la réorganisation.
</ResponseField>

<ResponseField name="usage" type="object">
  Statistiques d'utilisation des tokens.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.tokenlab.sh/v1/rerank" \
    -H "Authorization: Bearer sk-your-api-key" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "qwen3-vl-rerank",
      "query": "What is machine learning?",
      "documents": [
        "Machine learning is a subset of AI",
        "The weather is nice today",
        "Deep learning uses neural networks"
      ],
      "top_n": 2,
      "return_documents": true
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.tokenlab.sh/v1/rerank",
      headers={"Authorization": "Bearer sk-your-api-key"},
      json={
          "model": "qwen3-vl-rerank",
          "query": "What is machine learning?",
          "documents": [
              "Machine learning is a subset of AI",
              "The weather is nice today",
              "Deep learning uses neural networks"
          ],
          "top_n": 2
      }
  )

  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.tokenlab.sh/v1/rerank', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk-your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      model: 'qwen3-vl-rerank',
      query: 'What is machine learning?',
      documents: [
        'Machine learning is a subset of AI',
        'The weather is nice today',
        'Deep learning uses neural networks'
      ],
      top_n: 2
    })
  });

  const data = await response.json();
  console.log(data.results);
  ```

  ```go Go theme={null}
  package main

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

  func main() {
      payload := map[string]interface{}{
          "model": "qwen3-vl-rerank",
          "query": "What is machine learning?",
          "documents": []string{
              "Machine learning is a subset of AI",
              "The weather is nice today",
              "Deep learning uses neural networks",
          },
          "top_n": 2,
      }
      body, _ := json.Marshal(payload)

      req, _ := http.NewRequest("POST", "https://api.tokenlab.sh/v1/rerank", bytes.NewBuffer(body))
      req.Header.Set("Authorization", "Bearer sk-your-api-key")
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()

      var result map[string]interface{}
      json.NewDecoder(resp.Body).Decode(&result)
      fmt.Println(result["results"])
  }
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init('https://api.tokenlab.sh/v1/rerank');

  curl_setopt_array($ch, [
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_POST => true,
      CURLOPT_HTTPHEADER => [
          'Content-Type: application/json',
          'Authorization: Bearer sk-your-api-key'
      ],
      CURLOPT_POSTFIELDS => json_encode([
          'model' => 'qwen3-vl-rerank',
          'query' => 'What is machine learning?',
          'documents' => [
              'Machine learning is a subset of AI',
              'The weather is nice today',
              'Deep learning uses neural networks'
          ],
          'top_n' => 2
      ])
  ]);

  $response = curl_exec($ch);
  curl_close($ch);

  $data = json_decode($response, true);
  print_r($data['results']);
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "results": [
      {
        "index": 0,
        "relevance_score": 0.95,
        "document": "Machine learning is a subset of AI"
      },
      {
        "index": 2,
        "relevance_score": 0.82,
        "document": "Deep learning uses neural networks"
      }
    ],
    "model": "qwen3-vl-rerank",
    "usage": {
      "prompt_tokens": 45,
      "total_tokens": 45
    }
  }
  ```
</ResponseExample>