A Rerank API key looks similar to an ordinary chat key, but its risk profile is higher: every request carries the user's query and a batch of candidate document text, and the bill scales with call volume. If the key leaks, someone else can consume your balance and fill your invoice with requests you never made.

This guide covers two ways to obtain a key — the vendor's own platform and a domestic AI gateway — then explains permission and quota settings at creation time, environment variable conventions, 401 troubleshooting, and a rotation process. Model availability and pricing follow the in-site model pricing page.

Note: Cohere, Jina AI, Alibaba Cloud, SiliconFlow, and Volcano Engine are names owned by their respective rights holders and are used here for technical explanation only. ZSQH AI Gateway is not affiliated with these vendors; interfaces and models are governed by the in-site documentation.

1. How a Rerank key differs from a chat key

A chat key calls a generative model: the input is a message and the output is text. A Rerank key calls a reranking model: the input is one query plus a set of candidate documents, and the output is a relevance score and ordering for each document.

The differences come down to three points:

  • More sensitive data: candidate documents often come from an internal knowledge base and may contain contracts, policies, or customer information.
  • Different billing: charges are usually based on the tokens in the query and documents, so long documents and large candidate sets multiply consumption.
  • Narrower permissions: many platforms let you restrict a key to specific models, allowing only rerank models and reducing the risk of misuse.

For these reasons, do not mix a rerank key with a chat key, and do not hand the same key to several projects. The right granularity is one key per environment and per project.

2. Route A: Getting a key from a vendor platform

Cohere, Jina AI, Alibaba Cloud Model Studio, SiliconFlow, and Volcano Engine all offer reranking services. Entry points and field names differ, but the flow is broadly the same:

  1. Choose a platform. First confirm supported languages, maximum document length, Chinese-language support, and whether data leaves the country.
  2. Register an account. Domestic platforms usually require a phone number or enterprise verification; overseas platforms require an email address and a payment method.
  3. Enable the service. Find the Rerank or reranking section in the console and confirm that the target model is enabled.
  4. Create a key. Open the API Keys page, create a new secret, and name it by project and environment, for example rag-prod.
  5. Set limits. Set a spending cap if the platform supports one, set an expiry date if available, and select only rerank models if model scoping is offered.
  6. Test immediately. After copying the key, send one minimal request to confirm that authentication, the model name, and the response shape are all correct.

Authentication headers are not identical across platforms. Cohere and Jina commonly use Authorization: Bearer <key>, while some domestic platforms use their own signing scheme. Do not write headers from memory — copy them from the current vendor documentation.

3. Route B: Getting a key through ZSQH AI Gateway

If your team has no overseas payment method, or you want to combine bills across models, the gateway route may fit:

  1. Open ZSQH AI Gateway and complete sign-up.
  2. Go to the API Keys page in the console and create a key.
  3. Enter a name, choose the project or group, and set a spending cap and expiry date.
  4. Top up the wallet and confirm that the balance is enough to complete a test call.
  5. Copy the key into a password manager rather than leaving it in a chat log.

The gateway exposes reranking as POST /v1/rerank and also accepts /rerank, with the base URL https://ai.zhongshangqihang.com/v1. Note that Rerank is not part of OpenAI's Chat Completions specification; it is a separate endpoint, so you cannot call it with a chat SDK method directly.

Dimension Vendor platform ZSQH AI Gateway
Registration and payment Overseas platforms usually require a foreign card; domestic platforms require identity verification Domestic registration and top-up; methods follow the checkout page
Network Overseas endpoints may be unstable Direct domestic access, reducing network troubleshooting
Model range Only that vendor's models One entry point for multiple upstream models, subject to the model list
Billing Reconciled separately per vendor Combined bill across models, easier to expense
Data path Requests go directly to the vendor Forwarded through the gateway; confirm the data-processing terms
Best for Teams standardized on one vendor that need vendor support Multi-model teams, domestic teams, centralized operations

The two routes can coexist. A common pattern is to keep a vendor account for fallback while domestic teams and test environments use the gateway. Before choosing, confirm the contracting entity, invoice type, and data terms.

4. Four security settings when creating a key

Obtaining a key is only the beginning. The settings chosen at creation time define how much damage a later problem can cause.

First, split by environment. Use a separate key for development, testing, and production, and include the project and date in the name. This makes it possible to trace a bill to its source and to disable only one key if a leak occurs.

Second, set a spending cap. Give each key a daily or monthly cap, and set at least one alert threshold. Rerank consumption depends directly on the number of documents and their length, so a looping script can generate a large number of requests in a short time.

Third, set an expiry date. Test keys should expire quickly, and production keys should rotate according to team policy. For keys issued temporarily to contractors or partners, automatic expiry is more reliable than manual collection.

Fourth, apply least privilege. If the platform supports model scopes, IP allowlists, or project groups, expose only rerank models and the necessary source addresses. Do not grant all-model access for convenience.

5. Environment variables and reading the key in code

A key should exist only in server-side environment variables or a secrets management service. Do not put it in a code repository or bundle it into a front end. The minimal configuration looks like this:

RERANK_API_KEY=sk-your-key
RERANK_BASE_URL=https://ai.zhongshangqihang.com/v1

Add .env to .gitignore and inject the values through the platform's environment variable panel at deploy time. Reading them in Python:

import os
import requests

api_key = os.environ["RERANK_API_KEY"]
base_url = os.environ.get("RERANK_BASE_URL", "https://ai.zhongshangqihang.com/v1")

resp = requests.post(
    f"{base_url}/rerank",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "model": "your-rerank-model-name",
        "query": "How long is the trial period?",
        "documents": ["The trial period is 14 days.", "Bank transfer is supported."],
        "top_n": 2,
    },
    timeout=20,
)
resp.raise_for_status()
print(resp.json()["results"])

Model names follow the model pricing page. If your team uses a secrets manager, store the key as ciphertext and inject it at runtime; never print it to logs. When debugging, you may log the request ID and status code, but not the full Authorization header.

6. Diagnosing 401: authentication failure vs. insufficient permission

401 means the identity was not recognized; 403 means the identity was recognized but lacks permission. Many gateways unify both into one error shape, so read the response body and error code instead of the status code alone.

Symptom Common cause Action
401 Unauthorized Key typed incorrectly, leading or trailing spaces, or truncated during copy Copy again and confirm there are no line breaks
401 invalid token Key was deleted, has expired, or belongs to another project Check its status in the console and create a new one
401 despite a correct key Wrong header field, or the base URL points to another service Check Authorization and the path against the documentation
403 Forbidden The key lacks model permission, or the account is suspended Check the model scope and account status
404 Not Found Wrong model name or endpoint path Verify /v1/rerank and the model list
429 Too Many Requests Concurrency too high or a quota limit reached Retry with exponential backoff; check quota and rate limits

Fix the troubleshooting order: confirm the request URL and headers, then the key status, then the model name, and finally the account balance and rate limits. Writing these four steps into a checklist is faster than guessing each time.

7. Rotation and leak response

Key rotation should not wait for an incident. Rotate on a fixed schedule, and immediately when staff leave, a key is committed to a repository by mistake, or a full key appears in logs.

  1. Create a new key in the console and include the rotation date in its name.
  2. Put the new key into the test environment first and run one minimal request.
  3. Update the production environment variable and restart the service; watch error rates and call volume.
  4. Once the old key receives no traffic, disable or delete it.
  5. Review recent call logs for unfamiliar sources or abnormal spikes.
  6. Record the rotation date and put the next rotation on the team calendar.

If you suspect a leak, disable the old key first, then examine bills and logs — do not delete logs first. Evidence helps you judge the scope of impact. After rotation, check repository history, CI variables, and chat records for other copies.

8. FAQ

Can a Rerank API key call chat models?

It depends on whether the platform permits it. Even when technically possible, it is not advisable. A rerank key should be used only for the rerank endpoint, so that one key does not carry both generation and retrieval billing.

Can the key be placed in a front end or mini program?

No. Front-end code and network requests are visible to users, which makes the key public. The correct approach is for the front end to call your own backend, which holds the key and forwards the request.

What is the difference between 401 and 403?

401 is an authentication failure, usually meaning the key is invalid, expired, or sent with the wrong header. 403 is insufficient permission: the key may be valid but lacks access to the model or project. Check the code and message fields in the error body first.

Can one key be shared across several projects?

Technically it often can, but operationally it should not be. A shared key makes bills impossible to split and widens the impact of a leak. At minimum, separate keys by environment and project.

How often should a key be rotated?

Follow your team's security policy. A common practice is scheduled rotation, plus immediate rotation after staff changes, a suspected leak, or an accidental repository commit. There is no universal frequency; what matters is that the process is executable.