Skip to main content
API7.ai Logo
Version: Dev

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 Enterprise or AISIX Cloud, an environment with an attached gateway and a write-scoped admin token. For AISIX Enterprise, follow the AISIX Enterprise getting-started guide. To request AISIX Cloud access, contact API7.
    • For the open-source AISIX gateway, prepare either a local AISIX installation or the Docker setup from the AISIX OSS getting-started guide. Configure the gateway to load a declarative resources file.
  • A Mistral API key from the Mistral console.
  • curl and jq.

Configure with AISIX Enterprise or AISIX Cloud​

Export the control-plane connection details:

# AISIX_CP is the Admin API base URL; include /api and omit a trailing slash
# The local AISIX Enterprise quickstart uses http://localhost:8080/api
export AISIX_CP="YOUR_AISIX_CONTROL_PLANE_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 AISIX OSS​

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"

For a new gateway, use this complete resources file. For an existing gateway, merge the entries into its current file, preserving its other resources:

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 AISIX OSS getting-started guide. 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:

# AISIX_PROXY has no trailing slash or endpoint path
# The local quickstarts use http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_URL"

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. A non-streaming response reaches each normalized endpoint as follows:

  • /v1/chat/completions returns the array in message.content as Mistral sent it. AISIX does not convert the thinking chunks to reasoning_content.
  • /v1/messages returns the text as a text block and the thinking chunks as a thinking block with signature: "", as described in Anthropic Messages.
  • /v1/responses returns the text as output_text and the thinking chunks as a reasoning output item, as described in Responses API.

The thinking text is also captured as reasoning by content exporters, and counted in the estimated completion tokens when Mistral reports no usage. A response.reasoning_field override cannot convert the content array. A gateway at 1.7.0 or earlier fails these responses with an upstream decode error.

A stream whose delta.content is such an array keeps the order of its chunks on every endpoint. /v1/chat/completions returns the text of the text chunks as delta.content and the thinking chunks as delta.reasoning_content, so a streamed answer has a different shape from a non-streaming one. A chat delta has no field for the chunk's signature, so the signature is not returned. /v1/messages streams the thinking as a thinking block, and /v1/responses streams it as a reasoning item. Content exporters and the estimated completion tokens count the streamed thinking the same way as a non-streaming answer's.

A Mistral thinking chunk replayed in an assistant turn on /v1/chat/completions is checked by input guardrails. See Reasoning and Thinking Content.

For a reasoning-capable model such as mistral-small-latest, use reasoning_effort: "none" on the normalized endpoints when you do not need its reasoning. To receive the thinking chunks exactly as Mistral sent them, including on a stream, call Mistral's native chat contract through /passthrough/mistral/chat/completions and send the upstream Mistral model ID rather than the AISIX alias. The /passthrough/mistral paths on this page assume a passthrough route claiming that prefix with the Mistral API root as its target_url; grant the route name on the caller key's allowed_routes. The route preserves the response body and relays a native streaming response incrementally.

Mistral also supports n greater than 1. /v1/chat/completions returns every choice, while /v1/messages and /v1/responses carry one answer and return the first. See The Whole Answer Comes Back.

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, including stream: true, function tools, and text or image input supported by the selected model. A non-streaming structured reasoning response is returned as Mistral sent it; a stream returns its thinking as delta.reasoning_content.
/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. A structured reasoning response, streamed or not, returns its thinking as a reasoning item.
/v1/messagesSupported for Anthropic-shaped callers through translation to chat completions. A structured reasoning response, streamed or not, returns its thinking as a thinking block. 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 reachable through a passthrough route, but it requires a raw Mistral file ID. A passthrough route 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/*Available through a configured passthrough route for native Mistral routes, with raw request and response bodies. Provider SSE responses relay incrementally.

Passthrough routes are the way to reach Mistral-native OCR, moderation, classification, FIM, batch, Agents, Conversations, and structured reasoning. For example, with a route targeting https://api.mistral.ai/v1, /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. The route supplies the upstream base URL and, in inject mode, the provider key credential; a route binds one target and credential, so configure separate routes for separate Mistral accounts or bases. For the request shapes that record token usage, see Envelope Detection and Usage.

Next Steps​

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