Jina

Jina AI provides embedding and reranker models for search and retrieval applications. AISIX lets applications call those models through the gateway's OpenAI-compatible embeddings route and unified rerank route while managing the Jina credential, caller access, rate limits, and usage accounting.

Jina serves embeddings and reranking from the same API root, so one provider key can support both model types. This guide configures an embedding model first, then reuses the provider key for a reranker.

Prerequisites

Before starting, prepare the following:

One AISIX setup:
- For AISIX Cloud, an environment with an attached gateway and a write-scoped admin token. For On-Premises, follow the AISIX Cloud Quickstart. To request Hybrid Cloud access, contact API7.
- For the open-source AISIX gateway, prepare either a local AISIX installation or the Docker setup from the Open-Source AISIX Gateway Quickstart. Configure the gateway to load a declarative resources file.
A Jina API key from the Jina AI API dashboard. One key authorizes all Jina API products, including embeddings and reranking.
curl and jq.

Configure with AISIX Cloud

Export the AISIX Cloud connection details:

# Replace with your values
export AISIX_CP="http://localhost:8080/api"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"

Create a provider key, model alias, and caller API key for the Jina-backed embeddings route.

Create a Provider Key

Create the provider key that stores the Jina credential and API root:

# Replace with your value
export JINA_API_KEY="YOUR_PROVIDER_API_KEY"

PROVIDER_KEY_ID=$(curl -sS -X POST "$AISIX_CP/provider_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "jina-prod",
    "provider": "jina",
    "api_key": "'"${JINA_API_KEY}"'",
    "api_base": "https://api.jina.ai/v1",
    "allowed_environments": ["'"${ENV_ID}"'"]
  }' | jq -r '.provider_key.id')

echo "$PROVIDER_KEY_ID"

❶ provider is jina, the provider ID for Jina AI's search foundation API. The AISIX Cloud Admin API derives the openai adapter from the provider; the adapter field is only accepted on BYO provider keys.

❷ api_key stores the Jina API key and is sent as a bearer token on upstream calls. It follows the credential-handling behavior in Provider Keys.

❸ api_base is the versioned Jina API root. The version segment belongs on the base for this provider: the embeddings route appends /embeddings to this value verbatim, and the rerank route appends /rerank while recognizing the trailing /v1, so it does not insert a second version segment. Both routes compose their correct upstream URL from this one value. The field is optional for this provider — when it is omitted, the AISIX Cloud Admin API fills in the same canonical value — but the examples set it explicitly so the upstream root each key targets stays visible in the configuration.

Jina is not listed in the models.dev catalog, but it is not a community catalog entry. The gateway implements the embeddings and rerank wires for this provider. The dashboard therefore does not mark a jina provider key as a community entry with an unverified wire format. The catalog absence affects pricing instead; see Supply Cost Metadata.

Create a Model

Jina names its embedding models by generation: jina-embeddings-v4 is the current multimodal, multilingual generation. It returns 2048-dimension vectors by default and truncates them to smaller sizes through the standard dimensions field. Check the Embedding API reference for the current catalog before creating a model alias.

Create the model alias callers will send in requests:

MODEL_ID=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "jina-embed-prod",
    "model_name": "jina-embeddings-v4",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }' | jq -r '.model.id')

echo "$MODEL_ID"

❶ display_name is the alias callers send in model.

❷ model_name is the Jina model ID, for example jina-embeddings-v4. Because Jina is not on models.dev, the dashboard suggests no model IDs for this provider — enter the ID from Jina's model catalog yourself.

❸ provider_key_id attaches the alias to the Jina provider key.

Create a Caller API Key

Create the caller API key that can access the model alias. The plaintext key is server-generated and returned once in the response, so capture it now:

AISIX_API_KEY=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/api_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "jina-caller",
    "allowed_models": ["'"${MODEL_ID}"'"]
  }' | jq -r '.plaintext')

echo "$AISIX_API_KEY"

The allowed_models value must reference the model ID captured in the previous step, so the key can only access the alias you created. After the write, the configuration projects to attached gateways automatically.

Configure with the Open-Source AISIX Gateway

Export the upstream credential and choose the caller API key that applications will send to the gateway:

export JINA_API_KEY="YOUR_PROVIDER_API_KEY"
export CALLER_API_KEY="YOUR_CALLER_API_KEY"

Create a complete declarative resources file for this provider:

resources.yaml
_format_version: "1"

provider_keys:
  - display_name: "jina-prod"
    provider: "jina"
    adapter: "openai"
    api_key: ${JINA_API_KEY}
    api_base: "https://api.jina.ai/v1"

models:
  - display_name: "jina-embed-prod"
    provider: "jina"
    model_name: "jina-embeddings-v4"
    provider_key: "jina-prod"

api_keys:
  - display_name: "jina-caller"
    key_env: CALLER_API_KEY
    allowed_models:
      - "jina-embed-prod"

If AISIX is installed locally, validate the file before loading it:

aisix validate --resources resources.yaml

After validation, start the gateway with the referenced environment variables in its process environment. Reload an existing gateway only if those variables are already available to the process; otherwise, restart it with the updated environment.

If you use Docker, adapt the validation and startup commands in the Open-Source AISIX Gateway Quickstart. Mount this resources.yaml file and pass every environment variable it references with -e in both commands. After the resources load, prepare the shared verification request below:

export AISIX_PROXY="http://127.0.0.1:3000"
export AISIX_API_KEY="$CALLER_API_KEY"

Verify the Provider Connection

Send an embeddings request through the AISIX proxy, with a dimensions value below the model's default:

curl -sS -X POST "http://127.0.0.1:3000/v1/embeddings" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jina-embed-prod",
    "input": "AISIX keeps the provider credential on the gateway side.",
    "dimensions": 128
  }' -o jina-embed-response.json

jq '.data[0].embedding | length' jina-embed-response.json

The command should print 128. The vector length matching the requested dimensions confirms the optional field reached Jina, which truncates the model's default 2048-dimension output to the requested size. The response keeps the upstream response shape, so model carries the upstream model ID rather than the caller-facing alias, and usage reports the upstream token count that AISIX reads for usage accounting. If the request fails, check the provider key api_key, api_base, and the Jina model ID in model_name.

Send Jina-Specific Embedding Fields

The modeled /v1/embeddings route forwards the OpenAI request shape: model, input as a single string or an array of strings (the wire shape the caller sent is preserved upstream), encoding_format, and dimensions. Jina's embeddings API accepts additional fields beyond this shape — task selects a task-optimized embedding, such as retrieval.passage for indexing documents or retrieval.query for queries, and late_chunking embeds the inputs in one shared context before returning per-input vectors. These fields are not part of the modeled request shape, and the gateway drops them before the request reaches Jina.

To send them, call Jina through the raw passthrough route instead, which forwards the request body verbatim:

curl -sS -X POST "http://127.0.0.1:3000/passthrough/jina/embeddings" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jina-embeddings-v4",
    "task": "retrieval.passage",
    "late_chunking": true,
    "input": [
      "Provider keys store the upstream credential.",
      "Caller API keys authorize model access."
    ]
  }'

Two differences from the modeled route apply. The passthrough route does not rewrite the body, so model must be the upstream model ID rather than the alias. It also resolves the upstream credential and base URL from the first Jina model the caller API key can access, so the key must already be allowed to use a Jina-backed alias. The route appends the remaining path to the provider key api_base, producing https://api.jina.ai/v1/embeddings. See Provider Passthrough for the route's behavior and limits, and the Embedding API reference for the accepted values of task and late_chunking.

Add a Rerank Model

The /v1/rerank route accepts a model whose provider value is openai, cohere, or jina. For jina, the wire is identity-mapped: Jina's rerank API uses the same request fields — model, query, documents, and the optional parameters — and the same results response shape as the gateway's unified rerank contract, so AISIX forwards the body verbatim with only the model field rewritten to the upstream model ID.

Jina also serves rerank from the same https://api.jina.ai/v1 root as embeddings, so the provider key created above already reaches it. No second provider key on a different API root is needed, unlike providers whose rerank endpoint lives outside their OpenAI-compatible surface (compare Cohere's rerank setup). The rerank route appends /rerank to the provider key base and inserts a /v1 segment only when the base does not already end in /v1, so the canonical Jina base builds https://api.jina.ai/v1/rerank without doubling the version segment.

In AISIX Cloud, create the rerank model alias and a caller key scoped to it:

RERANK_MODEL_ID=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "jina-rerank-prod",
    "model_name": "jina-reranker-v3",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }' | jq -r '.model.id')

RERANK_API_KEY=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/api_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "jina-rerank-caller",
    "allowed_models": ["'"${RERANK_MODEL_ID}"'"]
  }' | jq -r '.plaintext')

For the open-source AISIX gateway, add the rerank model to the existing models collection and allow the existing caller key to use both aliases:

resources.yaml
models:
  - display_name: "jina-embed-prod"
    provider: "jina"
    model_name: "jina-embeddings-v4"
    provider_key: "jina-prod"
  - display_name: "jina-rerank-prod"
    provider: "jina"
    model_name: "jina-reranker-v3"
    provider_key: "jina-prod"

api_keys:
  - display_name: "jina-caller"
    key_env: CALLER_API_KEY
    allowed_models:
      - "jina-embed-prod"
      - "jina-rerank-prod"

Validate and reload or restart the declarative resources file as described above, then use the existing caller key for the rerank request:

export RERANK_API_KEY="$CALLER_API_KEY"

Reranker IDs follow their own naming, separate from the embedding generations: jina-reranker-v3 is the current multilingual generation, and jina-reranker-v2-base-multilingual is its predecessor. Check the Reranker API reference for the current catalog.

Send a rerank request through the proxy:

curl -sS -X POST "http://127.0.0.1:3000/v1/rerank" \
  -H "Authorization: Bearer ${RERANK_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jina-rerank-prod",
    "query": "How do I rotate a provider credential?",
    "documents": [
      "Provider keys store the upstream credential.",
      "Caller API keys authorize model access.",
      "Rate limits apply per caller key."
    ],
    "top_n": 2
  }'

AISIX rewrites only the model field to jina-reranker-v3 and forwards the body unchanged, so Jina's optional parameters, such as top_n and return_documents, reach the upstream as written. The response keeps Jina's rerank shape: a results array ordered by relevance_score, with each entry carrying the candidate's index and, when document text is requested, the document itself. AISIX reads usage.total_tokens from the response for usage accounting, so rerank traffic appears in gateway logs and, in AISIX Cloud, budget totals alongside embeddings traffic.

Chat Completions Are Not Served

The https://api.jina.ai/v1 root serves embeddings and reranking; it publishes no chat models. The gateway does not gate chat-shaped routes by provider, so a /v1/chat/completions request against a Jina-backed alias passes model resolution and caller key checks, reaches https://api.jina.ai/v1/chat/completions, and fails with an upstream error rather than a gateway-side rejection. The bridged /v1/responses route and the translated /v1/messages route resolve to the same upstream chat surface and fail the same way. Keep Jina-backed aliases scoped to embedding and reranker model IDs.

Jina's chat-shaped DeepSearch API is served on a separate host, https://deepsearch.jina.ai/v1, and is not part of the API root this page configures.

Supply Cost Metadata

Jina is not priced on the models.dev catalog that AISIX Cloud's pricing pipeline reads. Two consequences follow:

The dashboard suggests no model IDs when you create a model on a jina provider key, so enter the upstream model ID yourself.
No catalog price exists for these aliases, so the cost used by budget checks, usage reports, and least_cost routing resolves only from pricing you supply — the same posture as a bring-your-own endpoint.

In an AISIX Cloud deployment, set the per-token rate through Model Pricing. For the open-source AISIX gateway, record the rate with the cost field on the model in resources.yaml, as described in Model Aliases. Take the rates from Jina's published token pricing and convert them to USD per 1,000 tokens. In AISIX Cloud, these aliases contribute no cost to budget totals until a rate is set.

Endpoint Coverage

A Jina provider key resolves the openai adapter for the OpenAI-shaped routes, and the rerank route dispatches on the jina provider value directly:

Route	Behavior with a `jina` model alias
`/v1/embeddings`	Supported. The `openai` adapter appends `/embeddings` to `api_base`. The modeled shape forwards `model`, `input`, `encoding_format`, and `dimensions`; see Send Jina-Specific Embedding Fields for `task` and `late_chunking`.
`/v1/rerank`	Supported natively. `jina` is one of the three provider values this route accepts. See Add a Rerank Model.
`/v1/chat/completions`	Not served by Jina. The gateway forwards the request, and it fails upstream because this API root has no chat models. See Chat Completions Are Not Served.
`/v1/responses`	Not served by Jina. The Responses bridge resolves to the same upstream chat surface and fails upstream.
`/v1/messages`	Not served by Jina. The Anthropic-to-OpenAI translation resolves to the same upstream chat surface and fails upstream.
`/v1/images/generations`	Not supported. This route accepts only models whose configured provider is `openai`.
`/v1/videos`	Not supported. Jina is not among the video route's providers, so the route returns a not-implemented error before contacting the upstream.
`/passthrough/jina/*rest`	Supported. The request is forwarded verbatim to `api_base` plus the remaining path. Use it for Jina-specific request fields and for Jina APIs the gateway has not modeled.

See Provider Compatibility for the full endpoint and provider matrix.

Next Steps

You have now connected AISIX to Jina, verified the embedding alias, and added a rerank route. Continue with these guides:

Model Aliases: configure routing, retry behavior, or cost metadata for these aliases.
Rerank: review the rerank request contract and its provider requirement.
Embeddings: review the modeled embeddings request shape and provider behavior.
Provider Compatibility: review supported proxy endpoints and provider-specific boundaries.

Prerequisites​

Configure with AISIX Cloud​

Create a Provider Key​

Create a Model​

Create a Caller API Key​

Configure with the Open-Source AISIX Gateway​

Verify the Provider Connection​

Send Jina-Specific Embedding Fields​

Add a Rerank Model​

Chat Completions Are Not Served​

Supply Cost Metadata​

Endpoint Coverage​

Next Steps​