On most platforms, an Embedding API key is no different from a chat model key: it is only an identity credential. What you can actually call is determined by account permissions and the model parameter in each request. Embedding workloads, however, often run in the background and process large document batches, so a leaked or misconfigured key can be both costly and slow to diagnose.

This article walks through the sequence: where to register, what to enter when creating a key, how to separate permissions, where to store environment variables, how to investigate a 401, how to choose between a vendor key and a gateway key, and how to handle rotation and leaks.

Note: OpenAI and other brand names mentioned here are trademarks of their respective owners. This article is for technical explanation only and implies no affiliation with those vendors. Interfaces, permissions, and prices are subject to each platform's official documentation and on-site pages.

1. First, does Embedding need a separate key?

Most OpenAI-compatible platforms use a single authentication scheme: the same key can call both /v1/chat/completions and /v1/embeddings. Whether a call works depends on account balance, model permissions, and platform policy, not on the type of key.

A few platforms bill or authorize vector services separately. Before creating a key, confirm three things in the console:

  • Whether your current plan or balance covers embedding models.
  • Whether the key has a model allowlist or project scope restriction.
  • Whether embedding and chat share the same quota.

If the console has no fine-grained permission options, isolate by "one key per purpose" so you can at least set limits and disable keys separately.

2. Registration and console access

Using the ZSQH AI Gateway as an example:

  1. Open https://ai.zhongshangqihang.com, register with your email, and complete verification.
  2. Sign in, open the console, and find the "API Keys" page.
  3. Check your balance on the "Wallet" or "Top-up" page. During testing, a small top-up is enough.
  4. Open "Usage Logs" and confirm that model, token, and cost records are visible.

You can also start from the sign-up link. If you only want to verify the endpoint first and are not in a hurry to fund the account, create a low-limit test key, get a request working, and adjust afterward.

3. What to enter when creating a key

Click "New Key" and you will usually see these fields:

  1. Name: state the purpose and environment, such as rag-prod-backend or embedding-batch-dev. Avoid names like "test1".
  2. Spending limit: start low and raise it after you know the real consumption of a batch job.
  3. Expiration: set 7 or 30 days for temporary scripts; production keys should also have a fixed rotation cycle.
  4. Model or project scope: if the platform supports it, select only embedding models and the required project.
  5. Save and copy: the full key is usually shown only once. If you lose it, delete and recreate it.

Keys commonly begin with sk-, but the prefix is not proof of authenticity. When copying, make sure you do not include leading or trailing spaces or line breaks. That is one of the most common causes of a 401.

4. Designing permissions and quotas

Embedding workloads are read-heavy, batch-oriented, and prone to retries. The goal of permission design is not to stop external attacks but to prevent one key from affecting every environment.

Scenario Key name Quota Storage Rotation
Local development emb-dev-name Lowest tier Local .env 30 days
Staging emb-staging Low CI/CD secrets 60 days
Production batch emb-prod-batch By budget Secrets manager 90 days
Production queries emb-prod-query By budget Secrets manager 90 days

A few principles:

  • Separate development and production: a leaked test key will not affect the production bill.
  • Separate batch and query: batch jobs retry often, so a separate limit makes abnormal consumption easier to locate.
  • Least privilege: if you only need embedding, do not enable chat models; if you can restrict a project, do not grant account-level access.
  • Never put keys in the front end: keys in browsers, mobile apps, and mini-programs will be extracted. Embedding requests must go through your own backend.
  • Do not share personal keys: if a colleague leaves or a device is lost, a shared key cannot be disabled individually.

5. Put the key in environment variables

Do not hard-code it in source files. A Python project can read it like this:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ZSQH_API_KEY"],
    base_url="https://ai.zhongshangqihang.com/v1",
)

resp = client.embeddings.create(
    model="text-embedding-3-small",
    input=["First piece of text", "Second piece of text"],
)
print(len(resp.data[0].embedding))

For local .env files, add the file to .gitignore and commit only .env.example. In production, prefer container secrets, cloud key management, or a service such as Vault. Do not write keys into Dockerfiles, image layers, front-end bundles, or CI logs.

One more detail: restart the process after changing an environment variable. Many "401 in production, fine locally" cases come from the service still reading an old variable, or from the deployment platform not injecting the variable into the runtime environment.

6. 401 troubleshooting order

When you see 401 Unauthorized, check in this order. It usually takes only a few minutes to locate the cause:

  1. Check that the request header is Authorization: Bearer sk-..., with a single space between Bearer and the key.
  2. Copy the key again and confirm there are no spaces, line breaks, quotes, or invisible characters.
  3. Confirm the key has not been deleted, disabled, or expired.
  4. Confirm the key belongs to the platform for the current Base URL. Do not send a key from platform A to platform B.
  5. Confirm the process actually reads the environment variable rather than an empty string.
  6. Check whether a reverse proxy, gateway, or SDK rewrites the Authorization header.
  7. If only some requests fail, check whether a key exposed in front-end code was disabled by risk controls.

One clarification: 401 is an identity problem, 403 is usually permissions or regional restrictions, and 429 is usually rate or quota. Do not attribute every failure to the key.

7. Vendor key or gateway key

Both paths work. The differences are mainly procurement, networking, and maintenance:

  • Direct vendor access: the account, billing, and models are managed by the model vendor. It suits teams that can pay overseas and handle networking and compliance themselves. The downside is that models are spread across multiple platforms, so keys and reconciliation must be managed separately.
  • Gateway access: one Base URL and one key for multiple vendors' models, easier access from mainland China and RMB settlement, with centralized logs and limits. The trade-off is an extra dependency, so confirm the provider's data policy, availability, and incident handling.

Do not choose on price alone. At minimum, confirm whether data is retained, whether invoices are supported, how outages are communicated, whether model retirements are announced in advance, and whether usage records can be exported. For current models and prices, refer to model pricing. Prices change, so do not budget from numbers in older articles.

8. Rotation and leak response

Make rotation a routine rather than something you do only after an incident:

  1. Create a new key with the same permissions on the original platform.
  2. Update the value in environment variables or the secrets manager.
  3. Restart or redeploy the service and make one embedding call to confirm success.
  4. Watch usage logs for 24 to 48 hours and confirm there is no anomaly.
  5. Delete the old key and record the rotation time.

If you suspect a leak, reverse the order: disable the old key first, then examine usage logs and repository history, and only then create a new key. Deleting a string from code is not enough; the key may already be in CI logs, image layers, or third-party caches.

FAQ

Does Embedding always need a separate key?

Not necessarily. Most OpenAI-compatible platforms allow one key to call both embedding and chat endpoints. Whether to create a separate one depends on whether you need separate limits, separate auditing, or individual disablement.

Can I see the full key after creation?

Usually not. The full key is shown only once at creation, after which only a prefix or mask is retained. If you did not save it, delete and recreate it rather than trying to recover it from logs.

Can one key call multiple embedding models?

Usually yes. The model is specified in the model field of the request. For available models and dimensions, refer to platform documentation and model pricing.

curl works locally but returns 401 online. Why?

Check three things first: whether environment variables are injected online, whether the reverse proxy preserves the Authorization header, and whether production uses a different key that was deleted or has expired. Then check whether the Base URL points to the wrong platform.

Is deleting a leaked key enough?

No. Disable the key first, then check usage logs for abnormal calls, review repositories, CI logs, and image history, and finally rotate every key that may be affected. If the key had a funded balance, assess whether the quota needs adjustment as well.

Next steps

If you do not have an account yet, start from the sign-up page, create a low-limit key, and run a single text through /v1/embeddings. Once that works, check model pricing to choose a production model. For the vectorization workflow itself, continue with the setup guide below.

Related reading: