Rerank

POST https://api-staging.impossiblecarrot.cc/api/v1/rerank

The retrieval half of the embeddings rail: a query and a set of documents go in, and one relevance score per document comes back. Requires a bearer API key.

Routed only to models whose output modality is rerank — filter the model list or look for "output_modalities": ["rerank"] in the catalogue. A model with no scoring head is refused with 503 naming rerank_unsupported rather than being sent the request, because a relevance ask answered in prose would be recorded against an endpoint that never offered the rail. Routing and provider preferences otherwise work as on chat.

An image or video in the query or a document requires an endpoint declaring the corresponding input modality. Text-only endpoints and endpoints with no input declaration are excluded. If none qualify, the API returns 503 with input_unsupported in the routing details, before calling a provider or reserving credit. Plain strings and objects carrying only text require no visual input declaration. An instruction is sent only to an endpoint that declares it; otherwise routing rejects the request.

Request body#

Other controls may be sent by name when a seller declares them. The model's endpoint listing shows each seller's parameter_domains; routing refuses an undeclared name or a value outside that domain before contacting the seller. ImpCC's Qwen3-VL reranker declares positive truncate_prompt_tokens, truncation_side (left or right, with a token limit), nonnegative max_tokens_per_query and max_tokens_per_doc, boolean use_activation, string cache_salt, and chat_template_kwargs with optional instruction or instruct text. A future seller can publish a different control without a new marketplace request field.

Example#

curl https://api-staging.impossiblecarrot.cc/api/v1/rerank \
-H "Authorization: Bearer $HEIMDALL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "model": "baai/bge-reranker-v2-m3",
  "query": "How many legs does a spider have?",
  "documents": [
    "A spider has eight legs.",
    "The Danube flows through ten countries.",
    "Bread dough rises because yeast releases carbon dioxide."
  ],
  "top_n": 2
}'

{
  "id": "gen_01J8Z4K6V9",
  "model": "baai/bge-reranker-v2-m3",
  "provider": "ImpCC",
  "results": [
    { "index": 0, "relevance_score": 0.9871 },
    { "index": 2, "relevance_score": 0.0142 }
  ],
  "usage": { "search_units": 1, "total_tokens": 26, "cost": 0.000026 }
}

For an image query, use a model listing image input. The image value can be a URL or an inline data URL:

{
  "model": "qwen/qwen3-vl-reranker-8b",
  "query": { "image": "data:image/png;base64,<image bytes>" },
  "documents": ["a red ceramic cube", "a blue chair"],
  "instruction": "Match the image to the most accurate caption."
}

For a video query or document, use a model listing video input. The video value can be a URL or an inline video data URL. A seller may declare image, video, both, or neither; routing checks each visual input in the request separately.

Response fields#

Results arrive ordered by relevance_score, highest first, whatever order the endpoint answered in, and are cut to top_n where one was named. Scores are comparable within one reply and not between models: a reranker is trained to order documents, not to put them on a shared scale.

Billing#

A rerank scores the query against every document, so one call consumes one token figure covering the whole batch. It is billed per token where the endpoint publishes a prompt price and reports a count, and per request where it publishes a request price; an endpoint publishing both is charged both. Tokens consumed against no published price are recorded as unpriced rather than billed at zero, and usage.total_tokens is omitted entirely when the endpoint reported no count — an unreported figure is unknown, not none.

usage.search_units is reported for reconciliation against the Cohere search-unit shape and is not itself charged. A request price coincides with one search unit only while a call carries at most 100 of the 2048 documents a request may carry.

The X-Generation-Id and X-Provider-Name headers are sent as on chat completions.