Skip to main content
API7.ai Logo

Snowflake Cortex

Snowflake Cortex brings hosted foundation models into Snowflake accounts and exposes them through REST APIs. AISIX gives applications one OpenAI-compatible API for the models available in your account.

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 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 Snowflake connection details:

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 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"

Snowflake is a community catalog provider with an OpenAI-compatible Cortex endpoint. AISIX connects through the openai adapter, authenticates upstream requests with a bearer token, and uses the account-specific hostname as api_base.

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.

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"

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 SNOWFLAKE_PAT="YOUR_SNOWFLAKE_PROGRAMMATIC_ACCESS_TOKEN"
export SNOWFLAKE_ACCOUNT="YOUR_SNOWFLAKE_ACCOUNT"
export SNOWFLAKE_API_BASE="https://${SNOWFLAKE_ACCOUNT}.snowflakecomputing.com/api/v2/cortex/v1"
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: "snowflake-cortex-prod"
    provider: "snowflake-cortex"
    adapter: "openai"
    api_key: ${SNOWFLAKE_PAT}
    api_base: "${SNOWFLAKE_API_BASE}"

models:
  - display_name: "snowflake-claude-prod"
    provider: "snowflake-cortex"
    model_name: "claude-sonnet-4-5"
    provider_key: "snowflake-cortex-prod"

api_keys:
  - display_name: "snowflake-cortex-caller"
    key_env: CALLER_API_KEY
    allowed_models:
      - "snowflake-claude-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": "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​

Snowflake serves both OpenAI-compatible chat completions and a Claude-only Anthropic Messages API. The snowflake-cortex catalog entry uses the openai adapter, so normalized route behavior differs from Snowflake's native surface:

RouteBehavior with a Snowflake Cortex alias
/v1/chat/completionsSupported, buffered and streaming, through Snowflake's OpenAI-compatible chat route.
/v1/responsesSupported through the AISIX Responses bridge. Snowflake does not publish a native Responses endpoint, and fields without a chat-completions equivalent are ignored.
/v1/messagesSupported through translation to chat completions, not through Snowflake's native Messages route. For a Claude alias that needs Snowflake's native Anthropic contract or beta features, call /passthrough/snowflake-cortex/messages with the exact upstream model ID and the required anthropic-version: 2023-06-01 header.
/v1/messages/count_tokensNot supported. Token counting is limited to models whose configured adapter is Anthropic.
/v1/embeddingsNot compatible with Snowflake's Vector Embed REST API. Snowflake uses POST /api/v2/cortex/inference:embed and a native request body. Reach it through a separate passthrough route whose target_url is https://<account>.snowflakecomputing.com/api/v2/cortex — a route relays to one fixed base, so give this route its own path prefix — then call the native inference:embed path beneath that prefix, or use another embedding provider.
/v1/images/generations, /v1/videos, and /v1/rerankNot supported. These routes do not accept the snowflake-cortex provider value.
/passthrough/snowflake-cortex/*restAvailable through a configured passthrough route for Snowflake-native routes, with limited gateway normalization. Use a separate route with its own prefix when the native API needs a different base URL.

The /passthrough/snowflake-cortex paths on this page assume a passthrough route claiming that prefix with this guide's api_base as its target_url; grant the route name on the caller key's allowed_routes.

See Provider Compatibility for the full endpoint and provider matrix.

Troubleshooting​

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

Next Steps​

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