Snowflake Cortex

Connect AISIX AI Gateway to the Snowflake Cortex REST API so applications can access models available in your Snowflake account through one OpenAI-compatible gateway.

Snowflake exposes an OpenAI-compatible Cortex endpoint on an account-specific hostname. AISIX discovers the snowflake-cortex provider through its community catalog and sends bearer-authenticated requests with the openai adapter.

Setting	Value used by AISIX
Catalog provider ID	snowflake-cortex
API base	https://<account>.snowflakecomputing.com/api/v2/cortex/v1
Example upstream model	claude-sonnet-4-5
Authentication	Snowflake programmatic access token

Prerequisites

Before configuring the provider, prepare:

• An AISIX Cloud environment with an attached gateway.
• A Snowflake account identifier and a programmatic access token (PAT).
• A Snowflake role allowed to use Cortex. Snowflake documents the SNOWFLAKE.CORTEX_USER database role and the REST API user role requirements.
• Access to the selected model in your Snowflake region.
• curl and jq.

Export the AISIX and Snowflake connection details:

export AISIX_CP="http://localhost:8080/api"
export AISIX_TOKEN="aisix_pat_YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"
export AISIX_PROXY="http://127.0.0.1:3000"

export SNOWFLAKE_ACCOUNT="example-account"
export SNOWFLAKE_API_BASE="https://${SNOWFLAKE_ACCOUNT}.snowflakecomputing.com/api/v2/cortex/v1"
export SNOWFLAKE_PAT="YOUR_SNOWFLAKE_PROGRAMMATIC_ACCESS_TOKEN"

Use the account hostname from your Snowflake connection details. Do not include https:// or another path in SNOWFLAKE_ACCOUNT.

Configure the Snowflake Cortex Upstream

Create a Provider 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": "snowflake-cortex-prod",
      "provider": "snowflake-cortex",
      "api_key": "'"${SNOWFLAKE_PAT}"'",
      "api_base": "'"${SNOWFLAKE_API_BASE}"'",
      "allowed_environments": ["'"${ENV_ID}"'"]
    }' | jq -er '.provider_key.id'
)

echo "$PROVIDER_KEY_ID"

snowflake-cortex is the exact catalog ID. snowflake is not an alias for it. AISIX derives the openai adapter, so omit the adapter field.

The account-specific api_base is required in practice because AISIX cannot infer which Snowflake account should receive the request. AISIX appends /chat/completions to this root.

note

AISIX_TOKEN is an AISIX administrative token. SNOWFLAKE_PAT is the upstream credential stored in the provider key. They are unrelated token types even though both may be described as PATs.

Create a Model

Create an alias for a Cortex model available in your account:

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": "snowflake-claude-prod",
      "model_name": "claude-sonnet-4-5",
      "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
    }' | jq -er '.model.id'
)

echo "$MODEL_ID"

Snowflake's supported model list varies by region and release. Replace claude-sonnet-4-5 only with an ID available to your account, and copy its spelling from the current Cortex model availability reference.

Create a Caller API Key

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": "snowflake-cortex-caller",
      "allowed_models": ["'"${MODEL_ID}"'"]
    }' | jq -er '.plaintext'
)

echo "$AISIX_API_KEY"

Verify the Provider Connection

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

AISIX forwards the Snowflake model ID and authenticates with Authorization: Bearer <SNOWFLAKE_PAT>.

Endpoint Coverage

The Snowflake Cortex OpenAI-compatible chat route supports /v1/chat/completions through AISIX. Compatible Responses and Messages requests can use the chat bridges in AISIX.

The normalized AISIX /v1/embeddings route is not compatible with Snowflake's Vector Embed REST API. Snowflake uses POST /api/v2/cortex/inference:embed and a Snowflake-native request body. Use provider passthrough with a separate provider key rooted at https://<account>.snowflakecomputing.com/api/v2/cortex, or use another embedding provider.

Image generation, video generation, and rerank do not accept the snowflake-cortex provider value. See Provider Compatibility.

Troubleshooting

Symptom	Check
DNS error or upstream 404	Confirm SNOWFLAKE_ACCOUNT produces the same hostname shown in your Snowflake connection details.
Upstream 401	Rotate the Snowflake PAT and update the provider key.
Upstream 403	Confirm the token's user and role have Cortex privileges and access to the model.
Model unavailable	Choose a model supported in the Snowflake account's region.
Provider key creation returns 400	Use provider: "snowflake-cortex" and omit adapter.

For account-specific credentials and rotation, see Provider Credentials.