Skip to main content
API7.ai Logo

Mistral AI

Mistral AI develops and hosts the Mistral family of models. AISIX lets applications call its chat and compatible API surfaces with gateway-issued caller keys.

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 Mistral API key from the Mistral console.
  • 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 Mistral-backed chat-completions route.

Because Mistral exposes an OpenAI-compatible API, AISIX connects through the openai adapter and uses the Mistral API root as api_base.

Create a Provider Key​

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

# Replace with your value
export MISTRAL_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": "mistral-prod",
    "provider": "mistral",
    "api_key": "'"${MISTRAL_API_KEY}"'",
    "api_base": "https://api.mistral.ai/v1",
    "allowed_environments": ["'"${ENV_ID}"'"]
  }' | jq -r '.provider_key.id')

echo "$PROVIDER_KEY_ID"

❶ provider is mistral. The AISIX Cloud Admin API derives the adapter from the catalog provider; the adapter field is only accepted on BYO provider keys.

❷ api_key stores the Mistral API key. It follows the credential-handling behavior in Provider Keys.

❸ api_base already includes the /v1 path. AISIX appends /chat/completions to it. The field is optional for this catalog provider, because the AISIX Cloud Admin API fills in this same value when you omit it, but the examples set it explicitly so the upstream root stays visible on the resource.

The command captures the returned provider key ID in PROVIDER_KEY_ID.

Create a Model​

Mistral model IDs ending in -latest track the newest snapshot of that model. To pin a specific version, use the dated model ID from the Mistral models list.

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": "mistral-large-prod",
    "model_name": "mistral-large-latest",
    "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 Mistral model ID, for example mistral-large-latest or mistral-small-latest. If you use structured reasoning with mistral-small-latest, review Understand Structured Responses before enabling it.

❸ provider_key_id attaches the alias to the Mistral 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 — store it securely:

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": "mistral-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.

The gateway picks up the new resources automatically — no restart is needed.

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 MISTRAL_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: "mistral-prod"
    provider: "mistral"
    adapter: "openai"
    api_key: ${MISTRAL_API_KEY}
    api_base: "https://api.mistral.ai/v1"

models:
  - display_name: "mistral-large-prod"
    provider: "mistral"
    model_name: "mistral-large-latest"
    provider_key: "mistral-prod"

api_keys:
  - display_name: "mistral-caller"
    key_env: CALLER_API_KEY
    allowed_models:
      - "mistral-large-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 a chat-completions request through the AISIX proxy:

curl -sS -X POST "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistral-large-prod",
    "messages": [
      {
        "role": "user",
        "content": "Say hello from Mistral."
      }
    ]
  }'

The gateway returns an OpenAI-compatible response that echoes the caller-facing alias mistral-large-prod. If the request fails, check the provider key api_key, api_base, and the Mistral model ID in model_name.

Understand Structured Responses​

Standard Mistral chat responses work through the normalized AISIX endpoints when message.content, or each streaming delta.content, is a string. Text and OpenAI-style image input blocks are forwarded to compatible multimodal models such as Mistral Large 3.

Current Mistral reasoning models can return a different shape. With reasoning_effort: "high", Mistral returns arrays of ThinkChunk and TextChunk objects in content. The AISIX OpenAI adapter currently expects string content and returns an upstream decode error for those responses. This applies to /v1/chat/completions and to the Responses and Messages bridges, which ultimately use the same chat adapter. A response.reasoning_field override cannot convert the content array.

For a reasoning-capable model such as mistral-small-latest, use reasoning_effort: "none" on the normalized endpoints. To retain structured reasoning and replay the complete thinking history, call Mistral's native chat contract through /passthrough/mistral/chat/completions and send the upstream Mistral model ID rather than the AISIX alias. Passthrough preserves the response body but buffers it, so a native streaming response is returned only after the upstream stream ends.

Mistral also supports n greater than 1, but AISIX returns only the first choice on normalized chat routes. Use passthrough when the application needs every choice or another provider-native response shape.

Endpoint Coverage​

The model alias in this guide is a chat model. Create a separate alias with the appropriate Mistral model ID for embeddings, transcription, speech, or another capability.

RouteBehavior with a Mistral alias
/v1/chat/completionsSupported for scalar-content responses, including stream: true, function tools, and text or image input supported by the selected model. Structured reasoning content arrays are not supported.
/v1/responsesSupported through the Responses bridge, which translates to chat completions rather than calling a native Mistral Responses API. Fields without a chat equivalent are ignored, and the structured reasoning limitation still applies.
/v1/messagesSupported for Anthropic-shaped callers through translation to chat completions. The alias is OpenAI-backed, so /v1/messages/count_tokens returns a 400 error.
/v1/embeddingsSupported with a dedicated alias such as mistral-embed. AISIX forwards dimensions, but Mistral names the reduced-size field output_dimension; configure a request parameter rename if you need it.
/v1/audio/transcriptionsSupported with a transcription alias such as voxtral-mini-latest. AISIX relays the Mistral response, including provider-specific fields, but buffers streaming responses rather than relaying their events incrementally.
/v1/audio/translationsNot supported because Mistral does not publish this route.
/v1/audio/speechThe path reaches Mistral TTS, but the wire contract is not OpenAI-compatible. Send native fields such as voice_id and expect base64 JSON, or a buffered Mistral SSE payload, rather than raw audio bytes. AISIX does not translate this contract.
/v1/filesSupported for upload, list, retrieve, delete, and content download. Mistral's signed-URL route at /v1/files/{id}/url is available through passthrough, but it requires a raw Mistral file ID. Passthrough does not decode the AISIX-routed ID returned by a normalized upload.
/v1/batchesNot supported. AISIX forwards the OpenAI /v1/batches path, while Mistral uses /v1/batch/jobs.
/v1/fine_tuning/jobsNot supported. AISIX forwards the OpenAI job surface and requires training_file; Mistral's current public API does not publish compatible fine-tuning job routes.
/v1/completionsNot supported. Mistral code completion uses the native /v1/fim/completions contract.
/v1/images/generationsRejected with a 400 error because the route accepts only openai provider models. Mistral image generation is a built-in tool rather than this OpenAI image route.
/v1/rerankRejected with a 400 error because the route does not accept the mistral provider. Mistral publishes classification APIs, not this rerank contract.
/passthrough/mistral/*Supported for native Mistral routes, with raw request and response bodies. Provider SSE responses are buffered rather than relayed incrementally. See Provider Passthrough.

Passthrough is the route for Mistral-native OCR, moderation, classification, FIM, batch, Agents, Conversations, and structured reasoning. For example, /passthrough/mistral/ocr and /passthrough/mistral/v1/ocr both resolve to https://api.mistral.ai/v1/ocr, because AISIX removes one duplicated version segment.

AISIX does not rewrite a model value in a passthrough body. It borrows the base URL and credential from the first Mistral model alias that the caller can access. If you configure multiple Mistral accounts or bases, scope caller keys to the intended alias. Passthrough usage records report zero input and output tokens and zero calculated cost.

Next Steps​

You have now connected AISIX to Mistral and verified the model alias. Continue with these guides: