Jina

Jina AI provides embedding and reranker models for search and retrieval applications. Applications can call those models through the AISIX gateway's OpenAI-compatible embeddings route and unified rerank route. The gateway manages the Jina credential, caller access, and rate limits.

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:

# AISIX_CP is the Admin API base URL; include /api and omit a trailing slash
# The local On-Premises quickstart uses http://localhost:8080/api
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_API_URL"
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 value the AISIX rerank route recognizes. Jina is absent from models.dev, but AISIX Cloud accepts it as a directly supported provider and derives the openai adapter for embeddings and other OpenAI-shaped routes. 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 embeddings route appends /embeddings to this value, and the rerank route recognizes the trailing /v1 before appending /rerank, so both routes compose the correct upstream URL from one provider key. The field is optional for this provider; when it is omitted, the AISIX Cloud Admin API fills in the same canonical value. Set it explicitly when you point the key at a different Jina deployment.

The command captures the returned provider key ID in PROVIDER_KEY_ID.

Create a Model

This example uses jina-embeddings-v5-text-small, the current 1024-dimension text embedding model. Jina also publishes multimodal v5 models for text, image, audio, video, and PDF input. Those non-text input shapes require a passthrough route because the normalized AISIX route accepts strings only.

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-v5-text-small",
    "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 exact Jina model ID. Because Jina is not on models.dev, the dashboard suggests no model IDs for this provider; enter an ID from Jina's current model catalog.

❸ 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-v5-text-small"
    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_API_KEY="$CALLER_API_KEY"

Verify the Provider Connection

Export the AISIX gateway origin:

# The local quickstarts use http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_ORIGIN"

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

curl -sS -X POST "$AISIX_PROXY/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 1024-dimension output to the requested size.

AISIX reconstructs the accepted dense result in its OpenAI embeddings response shape. It preserves the upstream model ID, float or base64 vector, index, and prompt and total token counters. It does not preserve Jina-specific usage fields such as image_tokens, audio_tokens, or video_tokens. 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 accepts only model, input as a string or array of strings, encoding_format, and dimensions. AISIX preserves the caller's single-string or array input shape upstream. Jina documents embedding_type, rather than encoding_format, for output encoding.

Jina-specific fields such as task, embedding_type, normalized, and truncate are dropped before the request reaches Jina. Object inputs for images, audio, video, or PDF documents do not match the AISIX request schema and are rejected during request decoding. Jina sparse embeddings and v4 multi-vector responses also fall outside the AISIX response schema and fail upstream response decoding. Use a passthrough route for these request or response shapes.

To send them, call Jina through a passthrough route instead, which forwards the request body verbatim. The /passthrough/jina paths on this page assume a passthrough route claiming that prefix with https://api.jina.ai/v1 as its target_url and the Jina provider key attached; grant the route on the caller key's allowed_routes:

curl -sS -X POST "$AISIX_PROXY/passthrough/jina/embeddings" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jina-embeddings-v5-text-small",
    "task": "retrieval.passage",
    "embedding_type": "float",
    "normalized": true,
    "truncate": true,
    "input": [
      "Provider keys store the upstream credential.",
      "Caller API keys authorize model access."
    ]
  }'

The route does not rewrite the body, so model must be the upstream model ID rather than the alias. It injects the provider key configured on the route rather than borrowing one from the caller key's model allowlist; when more than one Jina provider key exists, give each its own route.

The route appends the remaining path to its target_url, producing https://api.jina.ai/v1/embeddings, and relays the response body unchanged. Passthrough detection is key-based rather than endpoint-based, so this embeddings body's top-level input makes AISIX apply Responses-style extraction and usage rules. AISIX records usage only when the response includes supported token fields. Do not rely on passthrough accounting for Jina-specific response shapes. See Passthrough Routes for the route's behavior and limits, and the Embedding API reference for current model-specific fields.

Add a Rerank Model

The /v1/rerank route accepts a model whose provider value is openai, cohere, or jina. For jina, the request and response wire shapes match the gateway's unified rerank contract. AISIX forwards Jina's model, query, documents, and optional fields verbatim, with only the model field rewritten to the upstream model ID.

Jina 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. This differs from providers whose rerank endpoint lives outside their OpenAI-compatible surface; compare Cohere's rerank setup. The rerank route appends /rerank and recognizes a base that already ends in /v1, producing https://api.jina.ai/v1/rerank without a duplicate 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.5",
    "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 caller key to use both aliases:

resources.yaml
models:
  - display_name: "jina-embed-prod"
    provider: "jina"
    model_name: "jina-embeddings-v5-text-small"
    provider_key: "jina-prod"
  - display_name: "jina-rerank-prod"
    provider: "jina"
    model_name: "jina-reranker-v3.5"
    provider_key: "jina-prod"

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

For the open-source setup, 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.5 is the current multilingual, multi-document reranker and a drop-in successor to jina-reranker-v3. Check the Reranker API reference for the current catalog.

Send a rerank request through the proxy:

curl -sS -X POST "$AISIX_PROXY/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.5 and forwards the body unchanged, so Jina's optional parameters, such as top_n, return_documents, max_doc_length, and return_embeddings, 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 requested, the document or document embedding. AISIX reads usage.total_tokens as input tokens for rerank usage and cost accounting.

Experimental Chat Completions

Jina publishes an experimental OpenAI-compatible /v1/chat/completions endpoint on the same API root for the exact model ID jina-ai/jina-vlm. It accepts text and image input, but Jina describes the endpoint as testing-only and does not guarantee availability, scalability, or production readiness. Do not use it as a production dependency.

To test it, create a separate model alias with model_name: "jina-ai/jina-vlm" on the existing provider key. Direct /v1/chat/completions requests reach Jina's native chat route. /v1/responses and /v1/messages use AISIX translation through chat completions, so they retain the bridge limitations described in Responses and Anthropic Messages.

Jina DeepSearch is a different chat-shaped product on https://deepsearch.jina.ai/v1. Configure it with a separate provider key and model alias. For passthrough, create a separate passthrough route that targets the DeepSearch base and injects the DeepSearch provider key.

Supply Cost Metadata

Jina is not priced on the models.dev catalog. No automatic catalog price exists for these aliases, so least_cost routing and cost estimates use only pricing you supply. Set rates through Model Pricing in AISIX Cloud, or with the cost field on the model in the open-source gateway's resources.yaml; see Cost Metadata. Convert Jina's published rates to USD per 1,000 tokens.

The normalized embeddings route records Jina's usage.prompt_tokens. If a Jina model returns only usage.total_tokens, AISIX uses that total for token-per-minute enforcement but records zero input tokens in its usage event. Rerank maps Jina's usage.total_tokens to input tokens. Passthrough records prompt_tokens or input_tokens and completion_tokens or output_tokens when present, but does not map Jina's total_tokens-only response into input usage.

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 for string inputs and single dense float outputs by default. The modeled shape forwards `model`, string or string-array `input`, `encoding_format`, and `dimensions`, but Jina documents `embedding_type` rather than `encoding_format` for selecting base64, binary, or unsigned-binary output. Use a passthrough route as shown in Send Jina-Specific Embedding Fields for those encodings, native fields, multimodal inputs, and other output shapes.
`/v1/rerank`	Supported with a Jina reranker alias. `jina` is one of the three provider values this route accepts. See Add a Rerank Model.
`/v1/chat/completions`	Supported only by Jina's testing-only `jina-ai/jina-vlm` model on this root. See Experimental Chat Completions. Embedding and rerank aliases fail on the chat route.
`/v1/responses` and `/v1/messages`	Supported through chat translation only for the experimental VLM alias. They are not native Jina routes and retain their bridge limitations. `/v1/messages/count_tokens` remains Anthropic-only.
`/v1/completions`, `/v1/audio/*`, `/v1/files`, `/v1/batches`, and `/v1/fine_tuning/jobs`	Not compatible with Jina's APIs on this root. Jina audio and video support refers to multimodal v5 embedding inputs, not the normalized AISIX audio or video-generation endpoints. Jina's native batch embeddings use different paths and contracts.
`/v1/images/generations` and `/v1/videos`	Not supported for the `jina` provider value.
`/passthrough/jina/*rest`	Available through a configured passthrough route, relative to the route's target. Use it for native embedding fields, multimodal input, classifiers, training, or native batch paths such as `/batch/embeddings`. The route requires exact upstream model IDs and preserves the response body. Usage is recorded only when the detected request envelope and response fields use a supported token shape.

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​

Experimental Chat Completions​

Supply Cost Metadata​

Endpoint Coverage​

Next Steps​