API REST Cortex¶

L’API REST Cortex vous donne accès aux modèles de pointe de Anthropic, OpenAI, Meta, Mistral et autres via votre point de terminaison préféré ouSDK. Toutes les inférences s’exécutent dans le périmètre de Snowflake, de sorte que vos données restent sécurisées et dans les limites de votre gouvernance. Voir ci-dessous pour savoir comment démarrer.

Choisissez votre API¶

L’API REST Cortex prend en charge deux spécifications d’API standard du secteur. Choisissez celle qui correspond le mieux à votre pile :


	API Achèvements de chat	API de messages
Compatibilité	API Achèvements de chat OpenAI	API Messages Anthropic
Point de terminaison	`/api/v2/cortex/v1/chat/completions`	`/api/v2/cortex/v1/messages`
Modèles pris en charge	Tous les modèles (OpenAI, Claude, Llama, Mistral,DeepSeek, Snowflake)	Modèles Claude uniquement
Prise en charge de SDK	SDKs d’OpenAI Python et JavaScript	SDK Python Anthropic
Mieux adapté à	La plupart des cas d’utilisation ; flexibilité multi-modèles	Intégrations Anthropic existantes ; parité API Anthropic

Les deuxAPIs partagent les mêmes méthodes d’authentification, le même catalogue de modèles et les mêmes limites de débit. La seule différence est le format de la requête/réponse et les modèles pris en charge par chaque point de terminaison. Pour connaître les tarifs, consultez la Table de consommation du service Snowflake.

Démarrage rapide¶

Conditions préalables¶

Avant de commencer, vous avez besoin de ce qui suit :

L’URL de votre compte Snowflake (par exemple, https://<account-identifier>.snowflakecomputing.com).
Un jeton d’accès programmatique Snowflake (PAT) pour l’authentification. Voir Génération d’un jeton d’accès programmatique.
Un nom de modèle à utiliser dans les requêtes. Voir Disponibilité du modèle pour les modèles disponibles.

Démarrage rapide des achèvements de chat¶

L’API Achèvements de chat suit la spécification OpenAI. Vous pouvez utiliser le SDK OpenAI directement.

from openai import OpenAI

client = OpenAI(
  api_key="<SNOWFLAKE_PAT>",
  base_url="https://<account-identifier>.snowflakecomputing.com/api/v2/cortex/v1"
)

response = client.chat.completions.create(
  model="claude-sonnet-4-5",
  messages=[
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "How does a snowflake get its unique pattern?"}
  ]
)

print(response.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "<SNOWFLAKE_PAT>",
  baseURL: "https://<account-identifier>.snowflakecomputing.com/api/v2/cortex/v1"
});

const response = await client.chat.completions.create({
  model: "claude-sonnet-4-5",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "How does a snowflake get its unique pattern?" }
  ],
});

console.log(response.choices[0].message.content);

curl "https://<account-identifier>.snowflakecomputing.com/api/v2/cortex/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <SNOWFLAKE_PAT>" \
  -d '{
    "model": "claude-sonnet-4-5",
    "messages": [
      {"role": "user", "content": "How does a snowflake get its unique pattern?"}
    ]
  }'

Dans les exemples précédents, remplacez les éléments suivants :

<account-identifier> : identificateur du compte Snowflake.
<SNOWFLAKE_PAT> : jeton d’accès programmatique Snowflake (PAT).
model : nom du modèle. Voir Disponibilité du modèle pour les modèles pris en charge.

Démarrage rapide de l’API Messages¶

L’API Messages suit la spécification Anthropic et ne prend en charge que les modèles Claude.

Le SDK Anthropic envoie des identifiants de connexion via x-api-key par défaut, mais Snowflake attend un jeton Bearer. Utilisez un client httpx pour définir l’en-tête d’autorisation correct.

import httpx
import anthropic

PAT = "<SNOWFLAKE_PAT>"

http_client = httpx.Client(
  headers={"Authorization": f"Bearer {PAT}"},
)

client = anthropic.Anthropic(
  api_key="not-used",
  base_url="https://<account-identifier>.snowflakecomputing.com/api/v2/cortex",
  http_client=http_client,
  default_headers={"Authorization": f"Bearer {PAT}"},
)

response = client.messages.create(
  model="claude-sonnet-4-5",
  max_tokens=1024,
  messages=[
    {"role": "user", "content": "How does a snowflake get its unique pattern?"}
  ],
)

print(response.content[0].text)

Comme pour Python, remplacez l’en-tête d’authentification par défaut par un jeton Bearer via``defaultHeaders``.

import Anthropic from "@anthropic-ai/sdk";

const PAT = "<SNOWFLAKE_PAT>";

const client = new Anthropic({
  apiKey: "not-used",
  baseURL: "https://<account-identifier>.snowflakecomputing.com/api/v2/cortex",
  defaultHeaders: {
    "Authorization": `Bearer ${PAT}`,
  },
});

const response = await client.messages.create({
  model: "claude-sonnet-4-5",
  max_tokens: 1024,
  messages: [
    { role: "user", content: "How does a snowflake get its unique pattern?" }
  ],
});

console.log(response.content[0].text);

curl "https://<account-identifier>.snowflakecomputing.com/api/v2/cortex/v1/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <SNOWFLAKE_PAT>" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "How does a snowflake get its unique pattern?"}
    ]
  }'

Dans les exemples précédents, remplacez les éléments suivants :

<account-identifier> : identificateur du compte Snowflake.
<SNOWFLAKE_PAT> : jeton d’accès programmatique Snowflake (PAT).
model : nom du modèle Claude. Voir Disponibilité du modèle pour les modèles pris en charge.

Configuration de l’authentification¶

Pour vous authentifier auprès de l’API REST de Cortex , vous pouvez utiliser les méthodes décrites dans Authentification d”Snowflake REST APIs avec Snowflake.

Définissez l’en-tête Authorization pour inclure votre jeton (par exemple, un jeton Web JSON (JWT), un jeton OAuth ou un jeton d’accès programmatique).

Astuce

Envisagez de créer un utilisateur dédié pour les requêtes de l’API REST de Cortex.

Configuration de l’autorisation¶

Pour envoyer une demande d’API REST, votre rôle par défaut doit se voir accorder le rôle de base de données SNOWFLAKE.CORTEX_USER. Dans la plupart des cas, les utilisateurs disposent déjà de ce privilège, car SNOWFLAKE.CORTEX_USER est accordé au rôle PUBLIC automatiquement et tous les rôles héritent de PUBLIC.

Si votre administrateur Snowflake a révoqué cette autorisation, il doit la réaccorder :

GRANT DATABASE ROLE SNOWFLAKE.CORTEX_USER TO ROLE my_role;
GRANT ROLE my_role TO USER my_user;

Important

Les requêtes REST API utilisent le rôle par défaut de l’utilisateur, donc ce rôle doit disposer des privilèges nécessaires. Vous pouvez modifier le rôle par défaut d’un utilisateur avec ALTER USER … SET DEFAULT_ROLE.

ALTER USER my_user SET DEFAULT_ROLE=my_role

Disponibilité du modèle¶

Les tableaux suivants présentent les modèles disponibles dans l’API REST Cortex pour chaque région :


Modèle	Inter-Cloud (N’importe quelle région)	AWS Global (inter-régionale)	AWS US (inter-régionale)	AWS EU (inter-régionale)	AWS APJ (inter-régionale)	Azure Global (inter-régionale)	Azure US (inter-régionale)
`claude-sonnet-4-6`	✔	✔	✔	✔
`claude-opus-4-6`	✔	✔
`claude-sonnet-4-5`	✔	✔	✔	✔
`claude-opus-4-5`	✔	✔
`claude-haiku-4-5`	✔	✔	✔
`claude-4-sonnet`	✔	✔	✔	✔
`claude-4-opus`	✔	✔
`claude-3-7-sonnet`	✔	✔
`claude-3-5-sonnet`	✔	✔
`openai-gpt-4.1`	✔				✔
`openai-gpt-5`	*				*	*	*
`openai-gpt-5-mini`	*					*
`openai-gpt-5-nano`	*					*
`openai-gpt-5-chat`	✔
`openai-gpt-oss-120b`	*
`llama4-maverick`	✔	✔
`llama3.1-8b`	✔	✔
`llama3.1-70b`	✔	✔
`llama3.1-405b`	✔	✔
`deepseek-r1`	✔	✔
`mistral-7b`	✔	✔
`mistral-large`	✔	✔
`mistral-large2`	✔	✔
`snowflake-llama-3.3-70b`	✔	✔


Modèle	AWS US West 2 (Oregon)	AWS US East 1 (Virginie du Nord)	Azure Est US 2 (Virginie)
`claude-3-5-sonnet`	✔	✔
`llama4-maverick`	✔
`llama3.1-8b`	✔	✔	✔
`llama3.1-70b`	✔	✔	✔
`llama3.1-405b`	✔	✔	✔
`deepseek-r1`	✔
`mistral-7b`	✔	✔	✔
`mistral-large`	✔	✔	✔
`mistral-large2`	✔	✔	✔
`snowflake-llama-3.3-70b`	✔


Modèle	AWS Europe Central 1 (Francfort)	AWS Europe Ouest 1 (Irlande)	Azure Europe de l’Ouest (Pays-Bas)
`llama3.1-8b`	✔		✔
`llama3.1-70b`	✔	✔	✔
`mistral-7b`	✔		✔
`mistral-large`	✔		✔
`mistral-large2`	✔	✔	✔


Modèle	AWS AP Sud-Est 2 (Sydney)	AWS AP Nord-Est 1 (Tokyo)
`llama3.1-8b`	✔	✔
`llama3.1-70b`	✔	✔
`mistral-7b`		✔
`mistral-large`		✔
`mistral-large2`	✔	✔

* indique une fonction ou un modèle de prévisualisation. Les fonctions de prévisualisation ne conviennent pas aux charges de travail de production.

Vous pouvez également utiliser n’importe quel modèle affiné dans n’importe quelle région prise en charge.

Fonctionnalités¶

Streaming¶

Les deux APIs prennent en charge les réponses en continu à l’aide des événements envoyés par le serveur.

Streaming des achèvements de chat¶

from openai import OpenAI

client = OpenAI(
  api_key="<SNOWFLAKE_PAT>",
  base_url="https://<account-identifier>.snowflakecomputing.com/api/v2/cortex/v1"
)

response = client.chat.completions.create(
  model="claude-sonnet-4-5",
  messages=[
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "How does a snowflake get its unique pattern?"}
  ],
  stream=True
)

for chunk in response:
    print(chunk.choices[0].delta.content, end="", flush=True)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "<SNOWFLAKE_PAT>",
  baseURL: "https://<account-identifier>.snowflakecomputing.com/api/v2/cortex/v1"
});

const stream = await client.chat.completions.create({
  model: "claude-sonnet-4-5",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "How does a snowflake get its unique pattern?" }
  ],
  stream: true,
});

for await (const event of stream) {
  process.stdout.write(event.choices[0]?.delta?.content || "");
}

curl "https://<account-identifier>.snowflakecomputing.com/api/v2/cortex/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <SNOWFLAKE_PAT>" \
  -d '{
    "model": "claude-sonnet-4-5",
    "messages": [
      {"role": "user", "content": "How does a snowflake get its unique pattern?"}
    ],
    "stream": true,
    "stream_options": {
      "include_usage": true
    }
  }'

Streaming de l’API Messages¶

import httpx
import anthropic

PAT = "<SNOWFLAKE_PAT>"

http_client = httpx.Client(
  headers={"Authorization": f"Bearer {PAT}"},
)

client = anthropic.Anthropic(
  api_key="not-used",
  base_url="https://<account-identifier>.snowflakecomputing.com/api/v2/cortex",
  http_client=http_client,
  default_headers={"Authorization": f"Bearer {PAT}"},
)

with client.messages.stream(
  model="claude-sonnet-4-5",
  max_tokens=1024,
  messages=[
    {"role": "user", "content": "How does a snowflake get its unique pattern?"}
  ],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

import Anthropic from "@anthropic-ai/sdk";

const PAT = "<SNOWFLAKE_PAT>";

const client = new Anthropic({
  apiKey: "not-used",
  baseURL: "https://<account-identifier>.snowflakecomputing.com/api/v2/cortex",
  defaultHeaders: {
    "Authorization": `Bearer ${PAT}`,
  },
});

const stream = client.messages.stream({
  model: "claude-sonnet-4-5",
  max_tokens: 1024,
  messages: [
    { role: "user", content: "How does a snowflake get its unique pattern?" }
  ],
});

for await (const event of stream) {
  if (event.type === "content_block_delta" && event.delta.type === "text_delta") {
    process.stdout.write(event.delta.text);
  }
}

curl "https://<account-identifier>.snowflakecomputing.com/api/v2/cortex/v1/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <SNOWFLAKE_PAT>" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "stream": true,
    "messages": [
      {"role": "user", "content": "How does a snowflake get its unique pattern?"}
    ]
  }'

Appel d’outil¶

L’appel d’outil permet au modèle d’invoquer des fonctions externes pendant une conversation. Le flux fonctionne par étapes :

Vous envoyez une demande avec une liste des outils disponibles.
Le modèle décide d’appeler un ou plusieurs outils et renvoie le nom de l’outil et les arguments.
Vous exécutez l’outil de votre côté.
Vous renvoyez le résultat de l’outil et le modèle génère une réponse finale.

L’appel d’outil est pris en charge pour les modèles OpenAI et Claude.

Appel de l’outil d’achèvements de chat¶

import json
from openai import OpenAI

client = OpenAI(
  api_key="<SNOWFLAKE_PAT>",
  base_url="https://<account-identifier>.snowflakecomputing.com/api/v2/cortex/v1"
)

tools = [
  {
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Get the current weather for a location",
      "parameters": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "The city and state, e.g. San Francisco, CA"
          }
        },
        "required": ["location"]
      }
    }
  }
]

messages = [
  {"role": "user", "content": "What is the weather like in San Francisco?"}
]

# Step 1: Send the request with tools
response = client.chat.completions.create(
  model="claude-sonnet-4-5",
  messages=messages,
  tools=tools,
)

# Step 2: The model responds with tool_calls
message = response.choices[0].message

if message.tool_calls:
    tool_call = message.tool_calls[0]

    # Step 3: Execute the tool (your implementation)
    result = json.dumps({"temperature": "69°F", "condition": "sunny"})

    # Step 4: Send the tool result back
    messages.append(message)
    messages.append({
      "role": "tool",
      "tool_call_id": tool_call.id,
      "content": result,
    })

    final_response = client.chat.completions.create(
      model="claude-sonnet-4-5",
      messages=messages,
      tools=tools,
    )

    print(final_response.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "<SNOWFLAKE_PAT>",
  baseURL: "https://<account-identifier>.snowflakecomputing.com/api/v2/cortex/v1"
});

const tools = [
  {
    type: "function",
    function: {
      name: "get_weather",
      description: "Get the current weather for a location",
      parameters: {
        type: "object",
        properties: {
          location: {
            type: "string",
            description: "The city and state, e.g. San Francisco, CA"
          }
        },
        required: ["location"]
      }
    }
  }
];

const messages = [
  { role: "user", content: "What is the weather like in San Francisco?" }
];

// Step 1: Send the request with tools
const response = await client.chat.completions.create({
  model: "claude-sonnet-4-5",
  messages,
  tools,
});

// Step 2: The model responds with tool_calls
const message = response.choices[0].message;

if (message.tool_calls) {
  const toolCall = message.tool_calls[0];

  // Step 3: Execute the tool (your implementation)
  const result = JSON.stringify({ temperature: "69°F", condition: "sunny" });

  // Step 4: Send the tool result back
  messages.push(message);
  messages.push({
    role: "tool",
    tool_call_id: toolCall.id,
    content: result,
  });

  const finalResponse = await client.chat.completions.create({
    model: "claude-sonnet-4-5",
    messages,
    tools,
  });

  console.log(finalResponse.choices[0].message.content);
}

Étape 1 - Envoyer la requête avec les outils :

curl "https://<account-identifier>.snowflakecomputing.com/api/v2/cortex/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <SNOWFLAKE_PAT>" \
  -d '{
    "model": "claude-sonnet-4-5",
    "messages": [
      {"role": "user", "content": "What is the weather like in San Francisco?"}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Get the current weather for a location",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA"
              }
            },
            "required": ["location"]
          }
        }
      }
    ]
  }'

Le modèle répond par un tableau tool_calls :

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "tool_calls": [
          {
            "id": "call_abc123",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"location\": \"San Francisco, CA\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ]
}

Étape 2 - Exécuter l’outil et renvoyer le résultat :

curl "https://<account-identifier>.snowflakecomputing.com/api/v2/cortex/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <SNOWFLAKE_PAT>" \
  -d '{
    "model": "claude-sonnet-4-5",
    "messages": [
      {"role": "user", "content": "What is the weather like in San Francisco?"},
      {
        "role": "assistant",
        "tool_calls": [
          {
            "id": "call_abc123",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"location\": \"San Francisco, CA\"}"
            }
          }
        ]
      },
      {
        "role": "tool",
        "tool_call_id": "call_abc123",
        "content": "{\"temperature\": \"69°F\", \"condition\": \"sunny\"}"
      }
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Get the current weather for a location",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA"
              }
            },
            "required": ["location"]
          }
        }
      }
    ]
  }'

Appel d’outil de l’API Messages¶

import json
import httpx
import anthropic

PAT = "<SNOWFLAKE_PAT>"

http_client = httpx.Client(
  headers={"Authorization": f"Bearer {PAT}"},
)

client = anthropic.Anthropic(
  api_key="not-used",
  base_url="https://<account-identifier>.snowflakecomputing.com/api/v2/cortex",
  http_client=http_client,
  default_headers={"Authorization": f"Bearer {PAT}"},
)

tools = [
  {
    "name": "get_weather",
    "description": "Get the current weather for a location",
    "input_schema": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string",
          "description": "The city and state, e.g. San Francisco, CA"
        }
      },
      "required": ["location"]
    }
  }
]

messages = [
  {"role": "user", "content": "What is the weather like in San Francisco?"}
]

# Step 1: Send the request with tools
response = client.messages.create(
  model="claude-sonnet-4-5",
  max_tokens=1024,
  messages=messages,
  tools=tools,
)

# Step 2: The model responds with a tool_use block
if response.stop_reason == "tool_use":
    tool_use = next(b for b in response.content if b.type == "tool_use")

    # Step 3: Execute the tool (your implementation)
    result = json.dumps({"temperature": "69°F", "condition": "sunny"})

    # Step 4: Send the tool result back
    messages.append({"role": "assistant", "content": response.content})
    messages.append({
      "role": "user",
      "content": [
        {
          "type": "tool_result",
          "tool_use_id": tool_use.id,
          "content": result,
        }
      ],
    })

    final_response = client.messages.create(
      model="claude-sonnet-4-5",
      max_tokens=1024,
      messages=messages,
      tools=tools,
    )

    print(final_response.content[0].text)

import Anthropic from "@anthropic-ai/sdk";

const PAT = "<SNOWFLAKE_PAT>";

const client = new Anthropic({
  apiKey: "not-used",
  baseURL: "https://<account-identifier>.snowflakecomputing.com/api/v2/cortex",
  defaultHeaders: {
    "Authorization": `Bearer ${PAT}`,
  },
});

const tools = [
  {
    name: "get_weather",
    description: "Get the current weather for a location",
    input_schema: {
      type: "object",
      properties: {
        location: {
          type: "string",
          description: "The city and state, e.g. San Francisco, CA"
        }
      },
      required: ["location"]
    }
  }
];

const messages = [
  { role: "user", content: "What is the weather like in San Francisco?" }
];

// Step 1: Send the request with tools
const response = await client.messages.create({
  model: "claude-sonnet-4-5",
  max_tokens: 1024,
  messages,
  tools,
});

// Step 2: The model responds with a tool_use block
if (response.stop_reason === "tool_use") {
  const toolUse = response.content.find(b => b.type === "tool_use");

  // Step 3: Execute the tool (your implementation)
  const result = JSON.stringify({ temperature: "69°F", condition: "sunny" });

  // Step 4: Send the tool result back
  messages.push({ role: "assistant", content: response.content });
  messages.push({
    role: "user",
    content: [
      {
        type: "tool_result",
        tool_use_id: toolUse.id,
        content: result,
      }
    ],
  });

  const finalResponse = await client.messages.create({
    model: "claude-sonnet-4-5",
    max_tokens: 1024,
    messages,
    tools,
  });

  console.log(finalResponse.content[0].text);
}

Étape 1 - Envoyer la requête avec les outils :

curl "https://<account-identifier>.snowflakecomputing.com/api/v2/cortex/v1/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <SNOWFLAKE_PAT>" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "What is the weather like in San Francisco?"}
    ],
    "tools": [
      {
        "name": "get_weather",
        "description": "Get the current weather for a location",
        "input_schema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city and state, e.g. San Francisco, CA"
            }
          },
          "required": ["location"]
        }
      }
    ]
  }'

Le modèle répond par un bloc de contenu tool_use :

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll check the weather for you."
    },
    {
      "type": "tool_use",
      "id": "toolu_abc123",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    }
  ],
  "stop_reason": "tool_use"
}

Étape 2 - Exécuter l’outil et renvoyer le résultat :

curl "https://<account-identifier>.snowflakecomputing.com/api/v2/cortex/v1/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <SNOWFLAKE_PAT>" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "What is the weather like in San Francisco?"},
      {
        "role": "assistant",
        "content": [
          {"type": "text", "text": "I'\''ll check the weather for you."},
          {
            "type": "tool_use",
            "id": "toolu_abc123",
            "name": "get_weather",
            "input": {"location": "San Francisco, CA"}
          }
        ]
      },
      {
        "role": "user",
        "content": [
          {
            "type": "tool_result",
            "tool_use_id": "toolu_abc123",
            "content": "{\"temperature\": \"69°F\", \"condition\": \"sunny\"}"
          }
        ]
      }
    ],
    "tools": [
      {
        "name": "get_weather",
        "description": "Get the current weather for a location",
        "input_schema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city and state, e.g. San Francisco, CA"
            }
          },
          "required": ["location"]
        }
      }
    ]
  }'

Sortie structurée¶

Vous pouvez demander une sortie JSON structurée conforme à un schéma spécifique. Ceci est pris en charge pour les modèles OpenAI et Claude via l’API d’achèvements de chat. Pour API Messages, utilisez le modèle tool_use pour appliquer une sortie structurée.

Sortie structurée des achèvements de chat¶

Utilisez le champ response_format avec un schéma JSON pour contraindre la sortie du modèle.

import json
from openai import OpenAI

client = OpenAI(
  api_key="<SNOWFLAKE_PAT>",
  base_url="https://<account-identifier>.snowflakecomputing.com/api/v2/cortex/v1"
)

response = client.chat.completions.create(
  model="claude-sonnet-4-5",
  messages=[
    {"role": "user", "content": "Create a dataset of 3 people with their names and ages."}
  ],
  response_format={
    "type": "json_schema",
    "json_schema": {
      "name": "people_data",
      "schema": {
        "type": "object",
        "properties": {
          "people": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {"type": "string"},
                "age": {"type": "number"}
              },
              "required": ["name", "age"]
            }
          }
        },
        "required": ["people"]
      }
    }
  }
)

data = json.loads(response.choices[0].message.content)
print(data)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "<SNOWFLAKE_PAT>",
  baseURL: "https://<account-identifier>.snowflakecomputing.com/api/v2/cortex/v1"
});

const response = await client.chat.completions.create({
  model: "claude-sonnet-4-5",
  messages: [
    { role: "user", content: "Create a dataset of 3 people with their names and ages." }
  ],
  response_format: {
    type: "json_schema",
    json_schema: {
      name: "people_data",
      schema: {
        type: "object",
        properties: {
          people: {
            type: "array",
            items: {
              type: "object",
              properties: {
                name: { type: "string" },
                age: { type: "number" }
              },
              required: ["name", "age"]
            }
          }
        },
        required: ["people"]
      }
    }
  }
});

const data = JSON.parse(response.choices[0].message.content);
console.log(data);

curl "https://<account-identifier>.snowflakecomputing.com/api/v2/cortex/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <SNOWFLAKE_PAT>" \
  -d '{
    "model": "claude-sonnet-4-5",
    "messages": [
      {"role": "user", "content": "Create a dataset of 3 people with their names and ages."}
    ],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "people_data",
        "schema": {
          "type": "object",
          "properties": {
            "people": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "name": {"type": "string"},
                  "age": {"type": "number"}
                },
                "required": ["name", "age"]
              }
            }
          },
          "required": ["people"]
        }
      }
    }
  }'

Note

Les modèles Claude prennent uniquement en charge json_schema comme type de format de réponse. Les modèles OpenAI prennent en charge des types de format de réponse supplémentaires comme indiqué dans la référence API OpenAI.

Sortie structurée API Messages¶

L’API Messages n’a pas de champ response_format. Au lieu de cela, définissez un outil avec le schéma de sortie souhaité et demandez au modèle de l’utiliser. La réponse tool_use du modèle contiendra une sortie JSON structurée correspondant à votre schéma.

import json
import httpx
import anthropic

PAT = "<SNOWFLAKE_PAT>"

http_client = httpx.Client(
  headers={"Authorization": f"Bearer {PAT}"},
)

client = anthropic.Anthropic(
  api_key="not-used",
  base_url="https://<account-identifier>.snowflakecomputing.com/api/v2/cortex",
  http_client=http_client,
  default_headers={"Authorization": f"Bearer {PAT}"},
)

response = client.messages.create(
  model="claude-sonnet-4-5",
  max_tokens=1024,
  messages=[
    {"role": "user", "content": "Create a dataset of 3 people with their names and ages."}
  ],
  tools=[
    {
      "name": "people_data",
      "description": "Output a list of people with names and ages.",
      "input_schema": {
        "type": "object",
        "properties": {
          "people": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {"type": "string"},
                "age": {"type": "number"}
              },
              "required": ["name", "age"]
            }
          }
        },
        "required": ["people"]
      }
    }
  ],
  tool_choice={"type": "tool", "name": "people_data"},
)

# Extract the structured data from the tool_use block
tool_use = next(b for b in response.content if b.type == "tool_use")
print(tool_use.input)

import Anthropic from "@anthropic-ai/sdk";

const PAT = "<SNOWFLAKE_PAT>";

const client = new Anthropic({
  apiKey: "not-used",
  baseURL: "https://<account-identifier>.snowflakecomputing.com/api/v2/cortex",
  defaultHeaders: {
    "Authorization": `Bearer ${PAT}`,
  },
});

const response = await client.messages.create({
  model: "claude-sonnet-4-5",
  max_tokens: 1024,
  messages: [
    { role: "user", content: "Create a dataset of 3 people with their names and ages." }
  ],
  tools: [
    {
      name: "people_data",
      description: "Output a list of people with names and ages.",
      input_schema: {
        type: "object",
        properties: {
          people: {
            type: "array",
            items: {
              type: "object",
              properties: {
                name: { type: "string" },
                age: { type: "number" }
              },
              required: ["name", "age"]
            }
          }
        },
        required: ["people"]
      }
    }
  ],
  tool_choice: { type: "tool", name: "people_data" },
});

// Extract the structured data from the tool_use block
const toolUse = response.content.find(b => b.type === "tool_use");
console.log(toolUse.input);

curl "https://<account-identifier>.snowflakecomputing.com/api/v2/cortex/v1/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <SNOWFLAKE_PAT>" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Create a dataset of 3 people with their names and ages."}
    ],
    "tools": [
      {
        "name": "people_data",
        "description": "Output a list of people with names and ages.",
        "input_schema": {
          "type": "object",
          "properties": {
            "people": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "name": {"type": "string"},
                  "age": {"type": "number"}
                },
                "required": ["name", "age"]
              }
            }
          },
          "required": ["people"]
        }
      }
    ],
    "tool_choice": {"type": "tool", "name": "people_data"}
  }'

Inclusion d’image¶

Vous pouvez inclure des images dans vos requêtes pour les modèles qui prennent en charge la vue. Les images doivent être fournies sous forme de chaînes codées en base64. Les images sont limitées à 20 par conversation avec une taille maximale de requête de 20 MiB.

L’inclusion d’image est prise en charge pour :

Modèles Claude (claude-3-7-sonnet et plus récents)
Modèles OpenAI (openai-gpt-4.1, openai-gpt-5, openai-gpt-5-chat, openai-gpt-5-mini, openai-gpt-5-nano)

Inclusion d’images d’achèvements de chat¶

import base64
from openai import OpenAI

client = OpenAI(
  api_key="<SNOWFLAKE_PAT>",
  base_url="https://<account-identifier>.snowflakecomputing.com/api/v2/cortex/v1"
)

# Read and encode an image file
with open("image.png", "rb") as f:
    image_data = base64.b64encode(f.read()).decode("utf-8")

response = client.chat.completions.create(
  model="claude-sonnet-4-5",
  messages=[
    {
      "role": "user",
      "content": [
        {
          "type": "image_url",
          "image_url": {
            "url": f"data:image/png;base64,{image_data}"
          }
        },
        {
          "type": "text",
          "text": "What is in this image?"
        }
      ]
    }
  ]
)

print(response.choices[0].message.content)

import OpenAI from "openai";
import fs from "fs";

const client = new OpenAI({
  apiKey: "<SNOWFLAKE_PAT>",
  baseURL: "https://<account-identifier>.snowflakecomputing.com/api/v2/cortex/v1"
});

// Read and encode an image file
const imageData = fs.readFileSync("image.png").toString("base64");

const response = await client.chat.completions.create({
  model: "claude-sonnet-4-5",
  messages: [
    {
      role: "user",
      content: [
        {
          type: "image_url",
          image_url: {
            url: `data:image/png;base64,${imageData}`
          }
        },
        {
          type: "text",
          text: "What is in this image?"
        }
      ]
    }
  ],
});

console.log(response.choices[0].message.content);

curl "https://<account-identifier>.snowflakecomputing.com/api/v2/cortex/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <SNOWFLAKE_PAT>" \
  -d '{
    "model": "claude-sonnet-4-5",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "image_url",
            "image_url": {
              "url": "data:image/png;base64,<BASE64_IMAGE_DATA>"
            }
          },
          {
            "type": "text",
            "text": "What is in this image?"
          }
        ]
      }
    ]
  }'

Inclusion d’image d’API Messages¶

L’API Messages utilise un format d’image différent — un bloc``source``avec les champs type, media_type et``data`` champs au lieu d’une URL de données.

import base64
import httpx
import anthropic

PAT = "<SNOWFLAKE_PAT>"

http_client = httpx.Client(
  headers={"Authorization": f"Bearer {PAT}"},
)

client = anthropic.Anthropic(
  api_key="not-used",
  base_url="https://<account-identifier>.snowflakecomputing.com/api/v2/cortex",
  http_client=http_client,
  default_headers={"Authorization": f"Bearer {PAT}"},
)

# Read and encode an image file
with open("image.png", "rb") as f:
    image_data = base64.b64encode(f.read()).decode("utf-8")

response = client.messages.create(
  model="claude-sonnet-4-5",
  max_tokens=1024,
  messages=[
    {
      "role": "user",
      "content": [
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/png",
            "data": image_data
          }
        },
        {
          "type": "text",
          "text": "What is in this image?"
        }
      ]
    }
  ],
)

print(response.content[0].text)

import Anthropic from "@anthropic-ai/sdk";
import fs from "fs";

const PAT = "<SNOWFLAKE_PAT>";

const client = new Anthropic({
  apiKey: "not-used",
  baseURL: "https://<account-identifier>.snowflakecomputing.com/api/v2/cortex",
  defaultHeaders: {
    "Authorization": `Bearer ${PAT}`,
  },
});

// Read and encode an image file
const imageData = fs.readFileSync("image.png").toString("base64");

const response = await client.messages.create({
  model: "claude-sonnet-4-5",
  max_tokens: 1024,
  messages: [
    {
      role: "user",
      content: [
        {
          type: "image",
          source: {
            type: "base64",
            media_type: "image/png",
            data: imageData
          }
        },
        {
          type: "text",
          text: "What is in this image?"
        }
      ]
    }
  ],
});

console.log(response.content[0].text);

curl "https://<account-identifier>.snowflakecomputing.com/api/v2/cortex/v1/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <SNOWFLAKE_PAT>" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "image",
            "source": {
              "type": "base64",
              "media_type": "image/png",
              "data": "<BASE64_IMAGE_DATA>"
            }
          },
          {
            "type": "text",
            "text": "What is in this image?"
          }
        ]
      }
    ]
  }'

Mise en cache des invites¶

La mise en cache des invites vous permet de réutiliser des contextes précédemment traités (tels que de grandes invites système, des documents ou l’historique des conversations) dans les requêtes, réduisant ainsi la latence et les coûts.

Modèles OpenAI : La mise en cache est implicite. Les invites comportant plus de 1 024 jetons sont automatiquement mises en cache, aucune modification de la requête n’est nécessaire.
Modèles Claude : La mise en cache est explicite. Ajoutez des points d’arrêt cache_control aux blocs de contenu que vous souhaitez mettre en cache. Seul le type de cache ephemeral est pris en charge, avec une TTL de 5 minutes. 4 points d’arrêt de cache maximum par requête.

Mise en cache de l’invite des achèvements de chat¶

Pour les modèles Claude via des achèvements de chat, ajoutez``cache_control`` aux blocs de contenu. Les modèles OpenAI sont mis en cache automatiquement et ne nécessitent pas ce champ.

from openai import OpenAI

client = OpenAI(
  api_key="<SNOWFLAKE_PAT>",
  base_url="https://<account-identifier>.snowflakecomputing.com/api/v2/cortex/v1"
)

response = client.chat.completions.create(
  model="claude-sonnet-4-5",
  messages=[
    {
      "role": "system",
      "content": [
        {
          "type": "text",
          "text": "<long system prompt to cache>",
          "cache_control": {"type": "ephemeral"}
        }
      ]
    },
    {"role": "user", "content": "Summarize the key points."}
  ]
)

print(response.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "<SNOWFLAKE_PAT>",
  baseURL: "https://<account-identifier>.snowflakecomputing.com/api/v2/cortex/v1"
});

const response = await client.chat.completions.create({
  model: "claude-sonnet-4-5",
  messages: [
    {
      role: "system",
      content: [
        {
          type: "text",
          text: "<long system prompt to cache>",
          cache_control: { type: "ephemeral" }
        }
      ]
    },
    { role: "user", content: "Summarize the key points." }
  ],
});

console.log(response.choices[0].message.content);

curl "https://<account-identifier>.snowflakecomputing.com/api/v2/cortex/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <SNOWFLAKE_PAT>" \
  -d '{
    "model": "claude-sonnet-4-5",
    "messages": [
      {
        "role": "system",
        "content": [
          {
            "type": "text",
            "text": "<long system prompt to cache>",
            "cache_control": {"type": "ephemeral"}
          }
        ]
      },
      {"role": "user", "content": "Summarize the key points."}
    ]
  }'

Mise en cache des invites de l’API Messages¶

Utilisez cache_control sur les blocs de contenu système ou utilisateur. Seul le type de cache ephemeral est pris en charge, avec une TTL de 5 minutes. Un maximum de 4 points d’arrêt de cache peut être défini par requête.

import httpx
import anthropic

PAT = "<SNOWFLAKE_PAT>"

http_client = httpx.Client(
  headers={"Authorization": f"Bearer {PAT}"},
)

client = anthropic.Anthropic(
  api_key="not-used",
  base_url="https://<account-identifier>.snowflakecomputing.com/api/v2/cortex",
  http_client=http_client,
  default_headers={"Authorization": f"Bearer {PAT}"},
)

response = client.messages.create(
  model="claude-sonnet-4-5",
  max_tokens=1024,
  system=[
    {
      "type": "text",
      "text": "<long system prompt to cache>",
      "cache_control": {"type": "ephemeral"}
    }
  ],
  messages=[
    {"role": "user", "content": "Summarize the key points."}
  ],
)

print(response.content[0].text)

import Anthropic from "@anthropic-ai/sdk";

const PAT = "<SNOWFLAKE_PAT>";

const client = new Anthropic({
  apiKey: "not-used",
  baseURL: "https://<account-identifier>.snowflakecomputing.com/api/v2/cortex",
  defaultHeaders: {
    "Authorization": `Bearer ${PAT}`,
  },
});

const response = await client.messages.create({
  model: "claude-sonnet-4-5",
  max_tokens: 1024,
  system: [
    {
      type: "text",
      text: "<long system prompt to cache>",
      cache_control: { type: "ephemeral" }
    }
  ],
  messages: [
    { role: "user", content: "Summarize the key points." }
  ],
});

console.log(response.content[0].text);

curl "https://<account-identifier>.snowflakecomputing.com/api/v2/cortex/v1/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <SNOWFLAKE_PAT>" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "<long system prompt to cache>",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [
      {"role": "user", "content": "Summarize the key points."}
    ]
  }'

Note

La mise en cache des invites Anthropic a une TTL de 5 minutes. Le contenu en cache non consulté dans les 5 minutes est expulsé. La mise en cache des invites OpenAI est implicite et gérée automatiquement. Aucun champ cache_control n’est nécessaire.

Réflexion et raisonnement¶

Réflexion sur les achèvements de chat¶

Pour les modèles Claude, utilisez l’objet reasoning. Pour les modèles de raisonnement OpenAI, utilisez le champ reasoning_effort (valeurs :minimal ,``low`` ,``medium`` ,``high``).

from openai import OpenAI

client = OpenAI(
  api_key="<SNOWFLAKE_PAT>",
  base_url="https://<account-identifier>.snowflakecomputing.com/api/v2/cortex/v1"
)

# Claude models — use the reasoning object
response = client.chat.completions.create(
  model="claude-sonnet-4-5",
  messages=[
    {"role": "user", "content": "Are there an infinite number of prime numbers such that n mod 4 == 3?"}
  ],
  extra_body={
    "reasoning": {"effort": "high"}
  }
)

print(response.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "<SNOWFLAKE_PAT>",
  baseURL: "https://<account-identifier>.snowflakecomputing.com/api/v2/cortex/v1"
});

// Claude models — use the reasoning object
const response = await client.chat.completions.create({
  model: "claude-sonnet-4-5",
  messages: [
    { role: "user", content: "Are there an infinite number of prime numbers such that n mod 4 == 3?" }
  ],
  reasoning: { effort: "high" },
});

console.log(response.choices[0].message.content);

# Claude models — use the reasoning object
curl "https://<account-identifier>.snowflakecomputing.com/api/v2/cortex/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <SNOWFLAKE_PAT>" \
  -d '{
    "model": "claude-sonnet-4-5",
    "messages": [
      {"role": "user", "content": "Are there an infinite number of prime numbers such that n mod 4 == 3?"}
    ],
    "reasoning": {
      "effort": "high"
    }
  }'

# OpenAI reasoning models — use reasoning_effort
curl "https://<account-identifier>.snowflakecomputing.com/api/v2/cortex/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <SNOWFLAKE_PAT>" \
  -d '{
    "model": "openai-gpt-5",
    "messages": [
      {"role": "user", "content": "Are there an infinite number of prime numbers such that n mod 4 == 3?"}
    ],
    "reasoning_effort": "high"
  }'

Réflexion de l’API Messages¶

Certains modèles de Claude prennent en charge la réflexion adaptative, où le modèle ajuste la quantité de raisonnement qu’il applique en fonction de la complexité de la tâche. Les modèles suivants prennent en charge la réflexion adaptative :

claude-opus-4-6

Pour l’API Messages, utilisez le paramètre thinking avec``type: « adaptive »`` pour permettre la réflexion adaptative. Le paramètre output_config.effort fournit un certain contrôle de haut niveau sur la profondeur de réflexion et accepte les valeurs suivantes :


Niveau d’effort	Comportement
`max`	Réfléchit toujours sans contraintes sur la profondeur de réflexion. Claude Opus 4.6 uniquement.
`high` (par défaut)	Réfléchit toujours. Fournit un raisonnement profond sur des tâches complexes.
`medium`	Réflexion modérée. Peut ignorer la réflexion pour les requêtes très simples.
`low`	Minimise la réflexion. Ignore la réflexion pour les tâches simples où la vitesse compte le plus.

Les exemples suivants montrent comment faire un appel d’API Messages avec la réflexion adaptative activée :

import httpx
import anthropic

PAT = "<SNOWFLAKE_PAT>"

http_client = httpx.Client(
  headers={"Authorization": f"Bearer {PAT}"},
)

client = anthropic.Anthropic(
  api_key="not-used",
  base_url="https://<account-identifier>.snowflakecomputing.com/api/v2/cortex",
  http_client=http_client,
  default_headers={"Authorization": f"Bearer {PAT}"},
)

response = client.messages.create(
  model="claude-opus-4-6",
  max_tokens=16384,
  thinking={
    "type": "adaptive"
  },
  messages=[
    {"role": "user", "content": "Are there an infinite number of prime numbers such that n mod 4 == 3?"}
  ],
)

# The response includes thinking blocks followed by text
for block in response.content:
    if block.type == "thinking":
        print(f"Thinking: {block.thinking[:100]}...")
    elif block.type == "text":
        print(f"Answer: {block.text}")

import Anthropic from "@anthropic-ai/sdk";

const PAT = "<SNOWFLAKE_PAT>";

const client = new Anthropic({
  apiKey: "not-used",
  baseURL: "https://<account-identifier>.snowflakecomputing.com/api/v2/cortex",
  defaultHeaders: {
    "Authorization": `Bearer ${PAT}`,
  },
});

const response = await client.messages.create({
  model: "claude-opus-4-6",
  max_tokens: 16384,
  thinking: {
    type: "adaptive"
  },
  messages: [
    { role: "user", content: "Are there an infinite number of prime numbers such that n mod 4 == 3?" }
  ],
});

// The response includes thinking blocks followed by text
for (const block of response.content) {
  if (block.type === "thinking") {
    console.log(`Thinking: ${block.thinking.slice(0, 100)}...`);
  } else if (block.type === "text") {
    console.log(`Answer: ${block.text}`);
  }
}

curl "https://<account-identifier>.snowflakecomputing.com/api/v2/cortex/v1/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <SNOWFLAKE_PAT>" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 16384,
    "thinking": {
      "type": "adaptive"
    },
    "messages": [
      {"role": "user", "content": "Are there an infinite number of prime numbers such that n mod 4 == 3?"}
    ]
  }'

La réponse comprend des blocs de réflexion avec un résumé de la réflexion et des signatures de réflexion. Transmettez ces blocs dans des conversations à plusieurs tours pour maintenir le contexte de raisonnement :

{
  "role": "assistant",
  "content": [
    {"type": "thinking", "thinking": "<thinking>", "signature": "<signature>"},
    {"type": "text", "text": "Yes, there are infinitely many primes p where p ≡ 3 (mod 4)..."}
  ]
}

Pour une description complète de l’API Messages prise en charge pour la réflexion adaptative, voir` Documentation de l’API Claude – Réflexion adaptative <https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking>`__.

Fonctionnalités Bêta (API Messages)¶

L’API Messages prend en charge les fonctions bêta d’Anthropic via l’en-tête anthropic-beta. Transmettez une ou plusieurs valeurs d’en-tête bêta sous la forme d’une chaîne séparée par des virgules.

En-têtes bêta pris en charge¶
Valeur d’en-tête bêta	Fonctionnalité
`token-efficient-tools-2025-02-19`	Outils économes en jetons
`interleaved-thinking-2025-05-14`	Réflexion entrelacée
`output-128k-2025-02-19`	Active les jetons de sortie jusqu’à 128 K
`dev-full-thinking-2025-05-14`	Mode développeur pour la réflexion brute sur les modèles Claude 4+
`context-1m-2025-08-07`	Fenêtre de contexte d’1 million de jetons
`context-management-2025-06-27`	Gestion des contextes
`effort-2025-11-24`	Paramètre d’effort pour la réflexion
`tool-search-tool-2025-10-19`	Outil de recherche d’outils
`tool-examples-2025-10-29`	Exemples d’utilisation d’outils

L’exemple suivant active la fenêtre de contexte d’1 million de jetons avec``claude-sonnet-4-6`` :

import httpx
import anthropic

PAT = "<SNOWFLAKE_PAT>"

http_client = httpx.Client(
  headers={"Authorization": f"Bearer {PAT}"},
)

client = anthropic.Anthropic(
  api_key="not-used",
  base_url="https://<account-identifier>.snowflakecomputing.com/api/v2/cortex",
  http_client=http_client,
  default_headers={
    "Authorization": f"Bearer {PAT}",
    "anthropic-beta": "context-1m-2025-08-07",
  },
)

response = client.messages.create(
  model="claude-sonnet-4-6",
  max_tokens=8192,
  messages=[
    {"role": "user", "content": "<very long document text>... Summarize the key themes."}
  ],
)

print(response.content[0].text)

import Anthropic from "@anthropic-ai/sdk";

const PAT = "<SNOWFLAKE_PAT>";

const client = new Anthropic({
  apiKey: "not-used",
  baseURL: "https://<account-identifier>.snowflakecomputing.com/api/v2/cortex",
  defaultHeaders: {
    "Authorization": `Bearer ${PAT}`,
    "anthropic-beta": "context-1m-2025-08-07",
  },
});

const response = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 8192,
  messages: [
    { role: "user", content: "<very long document text>... Summarize the key themes." }
  ],
});

console.log(response.content[0].text);

curl "https://<account-identifier>.snowflakecomputing.com/api/v2/cortex/v1/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <SNOWFLAKE_PAT>" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: context-1m-2025-08-07" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 8192,
    "messages": [
      {"role": "user", "content": "<very long document text>... Summarize the key themes."}
    ]
  }'

Vous pouvez combiner plusieurs fonctionnalités bêta en transmettant une chaîne séparée par des virgules :

-H "anthropic-beta: context-1m-2025-08-07,interleaved-thinking-2025-05-14"

Référence de l’API Achèvements de chat¶

POST /api/v2/cortex/v1/chat/completions¶

Génère un achèvement de chat en utilisant le modèle spécifié. Le format de la requête et de la réponse suit la spécification de l’API Achèvements du chat OpenAI.

POST https://<account_identifier>.snowflakecomputing.com/api/v2/cortex/v1/chat/completions

En-têtes obligatoires¶

Authorization: Bearer token: Autorisation pour la requête.:samp:{token} est un jeton Web JSON (JWT ), un jeton OAuth ou un :doc:` jeton d’accès programmatique</user-guide/programmatic-access-tokens>`. Pour plus de détails, voir Authentification d”Snowflake REST APIs avec Snowflake.
Content-Type: application/json: Spécifie que le corps de la requête est en format JSON.

En-têtes facultatifs¶

X-Snowflake-Authorization-Token-Type: type

Définit le type de jeton d’autorisation.

Si vous omettez l’en-tête X-Snowflake-Authorization-Token-Type, Snowflake détermine le type de jeton en examinant le jeton.

Bien que cet en-tête soit facultatif, vous pouvez choisir de le spécifier. Vous pouvez définir l’en-tête sur l’une des valeurs suivantes :

KEYPAIR_JWT (pour l’authentification par paire de clés)
OAUTH (pour OAuth)
PROGRAMMATIC_ACCESS_TOKEN (pour les jetons d’accès programmatiques)

Accept: application/json, text/event-stream

Spécifie que la réponse contiendra soit du JSON (en cas d’erreur), soit des événements envoyés par le serveur.

Champs JSON obligatoires¶


Champ	Type	Description
`model`	string	Le modèle à utiliser (voir Disponibilité du modèle). Vous pouvez également utiliser le nom complet d’un modèle affiné au format:samp:`{database}.{schema}.{model}`.
`messages`	tableau	Un tableau d’objets de message représentant la conversation. Chaque message doit avoir un``role`` (`system`,``user``,``assistant`` ou``tool``) et``content`` (chaîne ou tableau de parties de contenu).

Champs JSON facultatifs couramment utilisés¶


Champ	Type	Par défaut	Description
`max_completion_tokens`	entier	4096	Maximum de jetons dans la réponse. Le maximum théorique est 131 072 ; chaque modèle a sa propre limite de sortie.
`temperature`	number	Varie selon le modèle	Contrôle l’aléatoire. Valeurs de 0 à 2.
`top_p`	number	1,0	Contrôle la diversité via l’échantillonnage par noyau.
`stream`	booléen	false	S’il faut transmettre la progression partielle en tant qu’événements envoyés par le serveur.
`tools`	tableau	null	Une liste d’outils que le modèle peut appeler. Chaque outil doit avoir un objet `type: "function"` et `function` avec `name`, `description` et `parameters`.
`tool_choice`	chaîne ou objet	`"auto"`	Contrôle la manière dont le modèle sélectionne les outils. Options :`"auto"`, `"required"`, `"none"` ou un objet spécifiant une fonction particulière.
`response_format`	objet	null	Contraint le format de sortie. Utiliser `{"type": "json_schema", "json_schema": {...}}` pour la sortie structurée.
`reasoning_effort`	string	null	Pour les modèles de raisonnement OpenAI. Valeurs : `"minimal"`, `"low"`, `"medium"`, `"high"`.
`reasoning`	objet	null	Pour les modèles Claude. Définir `reasoning.effort` ou``reasoning.max_tokens`` pour permettre la réflexion.

Voir le tableau de compatibilité détaillé pour obtenir la liste complète des champs pris en charge par famille de modèles.

Codes de statut¶

200 OK: La requête a été complétée avec succès.
400 invalid options object: Les arguments facultatifs ont des valeurs non valides.
400 unknown model model_name: Le modèle spécifié n’existe pas.
400 schema validation failed: La structure du schéma de réponse est incorrecte.
400 max tokens of count exceeded: La requête a dépassé le nombre maximum de jetons pris en charge par le modèle.
400 all requests were throttled by remote service: La requête a été limitée. Veuillez réessayer plus tard.
402 budget exceeded: Le budget de consommation du modèle a été dépassé.
403 Not Authorized: Compte non activé pour REST API, ou le rôle par défaut de l’utilisateur appelant n’a pas le rôle de base de données snowflake.cortex_user.
429 too many requests: Le quota d’utilisation a été dépassé. Veuillez réessayer plus tard.
503 inference timed out: La requête a pris trop de temps.

Limitations¶

Si non défini, la valeur max_completion_tokens par défaut est 4 096. Chaque modèle a sa propre limite de jetons de sortie.
L’appel d’outil est pris en charge pour les modèles OpenAI et Claude uniquement.
L’audio n’est pas pris en charge.
La compréhension de l’image est prise en charge pour les modèles OpenAI et Claude uniquement. Les images sont limitées à 20 par conversation avec une taille maximale de requête de 20 MiB.
Seuls les modèles Claude prennent en charge des points de contrôle de cache éphémères pour la mise en cache rapide. Les modèles OpenAI prennent en charge la mise en cache implicite.
Seuls les modèles Claude prennent en charge le renvoi des détails de raisonnement dans la réponse.
max_tokens est obsolète. Utilisez max_completion_tokens à la place.
Les messages d’erreur sont générés par Snowflake, et non par le fournisseur de modèles.

Graphique de compatibilité détaillée¶

Les tableaux suivants récapitulent les champs et en-têtes de requête et de réponse pris en charge lors de l’utilisation de l’API Achèvements de chat Cortex avec différentes familles de modèles hébergées par Snowflake.

Champs de demande¶
Champ	Modèles OpenAI	Modèles Claude	Autres modèles
`model`	✔ pris en charge	✔ pris en charge	✔ pris en charge
`messages`	Voir les sous-champs	Voir les sous-champs	Voir les sous-champs
`messages[].audio`	❌ Erreur	❌ Ignoré	❌ Ignoré
`messages[].role`	✔ pris en charge	✔ Uniquement utilisateur/assistant/système	✔ Uniquement utilisateur/assistant/système
`messages[].content` (string)	✔ pris en charge	✔ pris en charge	✔ pris en charge
`messages[].content[]` (tableau)	Voir les sous-champs	Voir les sous-champs	Voir les sous-champs
`messages[].content[].text`	✔ pris en charge	✔ pris en charge	✔ pris en charge
`messages[].content[].type`	✔ pris en charge	✔ pris en charge	✔ pris en charge
`messages[].content[].image_url`	✔ pris en charge	✔ pris en charge	❌ Erreur
`messages[].content[].cache_control`	❌ Ignoré	✔ Pris en charge (éphémère uniquement)	❌ Ignoré
`messages[].content[].file`	❌ Erreur	❌ Erreur	❌ Ignoré
`messages[].content[].input_audio`	❌ Erreur	❌ Ignoré	❌ Ignoré
`messages[].content[].refusal`	✔ pris en charge	❌ Ignoré	❌ Ignoré
`messages[].function_call`	✔ Pris en charge (obsolète)	❌ Ignoré	❌ Ignoré
`messages[].name`	✔ pris en charge	❌ Ignoré	❌ Ignoré
`messages[].refusal`	✔ pris en charge	❌ Ignoré	❌ Ignoré
`messages[].tool_call_id`	✔ pris en charge	✔ pris en charge	❌ Ignoré
`messages[].tool_calls`	✔ pris en charge	✔ Uniquement outils `function`	❌ Ignoré
`messages[].reasoning_details`	❌ Ignoré	✔ Format OpenRouter `reasoning.text`	❌ Ignoré
`audio`	❌ Erreur	❌ Ignoré	❌ Ignoré
`frequency_penalty`	✔ pris en charge	❌ Ignoré	❌ Ignoré
`logit_bias`	✔ pris en charge	❌ Ignoré	❌ Ignoré
`logprobs`	✔ pris en charge	❌ Ignoré	❌ Ignoré
`max_tokens`	❌ Erreur (obsolète)	❌ Erreur (obsolète)	❌ Erreur (obsolète)
`max_completion_tokens`	✔ Pris en charge (4 096 par défaut, 131 072 max)	✔ Pris en charge (4 096 par défaut, 131 072 max)	✔ Pris en charge (4 096 par défaut, 131 072 max)
`metadata`	❌ Ignoré	❌ Ignoré	❌ Ignoré
`modalities`	❌ Ignoré	❌ Ignoré	❌ Ignoré
`n`	✔ pris en charge	❌ Ignoré	❌ Ignoré
`parallel_tool_calls`	✔ pris en charge	❌ Ignoré	❌ Ignoré
`prediction`	✔ pris en charge	❌ Ignoré	❌ Ignoré
`presence_penalty`	✔ pris en charge	❌ Ignoré	❌ Ignoré
`prompt_cache_key`	✔ pris en charge	❌ Ignoré	❌ Ignoré
`reasoning_effort`	✔ pris en charge	❌ Ignoré (utiliser l’objet `reasoning`)	❌ Ignoré
`reasoning`	Voir les sous-champs	Voir les sous-champs	Voir les sous-champs
`reasoning.effort`	✔ Pris en charge (remplace `reasoning_effort`)	✔ Converti en `reasoning.max_tokens`.	❌ Ignoré
`reasoning.max_tokens`	❌ Ignoré	✔ pris en charge	❌ Ignoré
`response_format`	✔ pris en charge	✔ Uniquement `json_schema`	❌ Ignoré
`safety_identifier`	❌ Ignoré	❌ Ignoré	❌ Ignoré
`service_tier`	❌ Erreur	❌ Erreur	❌ Erreur
`stop`	✔ pris en charge	❌ Ignoré	❌ Ignoré
`store`	❌ Erreur	❌ Erreur	❌ Erreur
`stream`	✔ pris en charge	✔ pris en charge	✔ pris en charge
`stream_options`	Voir les sous-champs	Voir les sous-champs	Voir les sous-champs
`stream_options.include_obfuscation`	❌ Ignoré	❌ Ignoré	❌ Ignoré
`stream_options.include_usage`	✔ pris en charge	✔ pris en charge	✔ pris en charge
`temperature`	✔ pris en charge	✔ pris en charge	✔ pris en charge
`tool_choice`	✔ pris en charge	✔ Uniquement outils `function`	❌ Ignoré
`tools`	✔ pris en charge	✔ Uniquement outils `function`	❌ Erreur
`top_logprobs`	✔ pris en charge	❌ Ignoré	❌ Ignoré
`top_p`	✔ pris en charge	✔ pris en charge	✔ pris en charge
`verbosity`	✔ pris en charge	❌ Ignoré	❌ Ignoré
`web_search_options`	❌ Erreur	❌ Ignoré	❌ Ignoré

Champs de réponse¶
Champ	Modèles OpenAI	Modèles Claude	Autres modèles
`id`	✔ pris en charge	✔ pris en charge	✔ pris en charge
`object`	✔ pris en charge	✔ pris en charge	✔ pris en charge
`created`	✔ pris en charge	✔ pris en charge	✔ pris en charge
`model`	✔ pris en charge	✔ pris en charge	✔ pris en charge
`choices`	Voir les sous-champs	Voir les sous-champs	Voir les sous-champs
`choices[].index`	✔ pris en charge	✔ Choix unique seulement	✔ Choix unique seulement
`choices[].finish_reason`	✔ pris en charge	❌ Non pris en charge	✔ Uniquement `stop`
`choices[].logprobs`	✔ pris en charge	❌ Non pris en charge	❌ Non pris en charge
`choices[].message` (non streaming)	Voir les sous-champs	Voir les sous-champs	Voir les sous-champs
`choices[].message.content`	✔ pris en charge	✔ pris en charge	✔ pris en charge
`choices[].message.role`	✔ pris en charge	✔ pris en charge	✔ pris en charge
`choices[].message.refusal`	✔ pris en charge	❌ Non pris en charge	❌ Non pris en charge
`choices[].message.annotations`	❌ Non pris en charge	❌ Non pris en charge	❌ Non pris en charge
`choices[].message.audio`	❌ Non pris en charge	❌ Non pris en charge	❌ Non pris en charge
`choices[].message.function_call`	✔ pris en charge	❌ Non pris en charge	❌ Non pris en charge
`choices[].message.tool_calls`	✔ pris en charge	✔ Uniquement outils `function`	❌ Non pris en charge
`choices[].message.reasoning`	❌ Non pris en charge	✔ Format OpenRouter	❌ Non pris en charge
`choices[].delta` (streaming)	Voir les sous-champs	Voir les sous-champs	Voir les sous-champs
`choices[].delta.content`	✔ pris en charge	✔ pris en charge	✔ pris en charge
`choices[].delta.role`	✔ pris en charge	❌ Non pris en charge	❌ Non pris en charge
`choices[].delta.refusal`	✔ pris en charge	❌ Non pris en charge	❌ Non pris en charge
`choices[].delta.function_call`	✔ pris en charge	❌ Non pris en charge	❌ Non pris en charge
`choices[].delta.tool_calls`	✔ pris en charge	✔ Uniquement outils `function`	❌ Non pris en charge
`choices[].delta.reasoning`	❌ Non pris en charge	✔ Format OpenRouter	❌ Non pris en charge
`usage`	Voir les sous-champs	Voir les sous-champs	Voir les sous-champs
`usage.prompt_tokens`	✔ pris en charge	✔ pris en charge	✔ pris en charge
`usage.completion_tokens`	✔ pris en charge	✔ pris en charge	✔ pris en charge
`usage.total_tokens`	✔ pris en charge	✔ pris en charge	✔ pris en charge
`usage.prompt_tokens_details`	Voir les sous-champs	Voir les sous-champs	Voir les sous-champs
`usage.prompt_tokens_details.audio_tokens`	❌ Non pris en charge	❌ Non pris en charge	❌ Non pris en charge
`usage.prompt_tokens_details.cached_tokens`	✔ Uniquement lectures du cache	✔ Lecture + écriture du cache	❌ Non pris en charge
`usage.completion_tokens_details`	Voir les sous-champs	Voir les sous-champs	Voir les sous-champs
`usage.completion_tokens_details.accepted_prediction_tokens`	✔ pris en charge	❌ Non pris en charge	❌ Non pris en charge
`usage.completion_tokens_details.audio_tokens`	❌ Non pris en charge	❌ Non pris en charge	❌ Non pris en charge
`usage.completion_tokens_details.reasoning_tokens`	✔ pris en charge	❌ Non pris en charge	❌ Non pris en charge
`usage.completion_tokens_details.rejected_prediction_tokens`	✔ pris en charge	❌ Non pris en charge	❌ Non pris en charge
`service_tier`	✔ pris en charge	❌ Non pris en charge	❌ Non pris en charge
`system_fingerprint`	✔ pris en charge	❌ Non pris en charge	❌ Non pris en charge

En-têtes de requête¶
En-tête	Assistance
`Authorization`	✔ Obligatoire
`Content-Type`	✔ Pris en charge (`application/json`)
`Accept`	✔ Pris en charge (`application/json`, `text/event-stream`)

En-têtes de réponse¶
En-tête	Assistance
`openai-organization`	❌ Non pris en charge
`openai-version`	❌ Non pris en charge
`openai-processing-ms`	❌ Non pris en charge
`x-ratelimit-limit-requests`	❌ Non pris en charge
`x-ratelimit-limit-tokens`	❌ Non pris en charge
`x-ratelimit-remaining-requests`	❌ Non pris en charge
`x-ratelimit-remaining-tokens`	❌ Non pris en charge
`x-ratelimit-reset-requests`	❌ Non pris en charge
`x-ratelimit-reset-tokens`	❌ Non pris en charge
`retry-after`	❌ Non pris en charge

En savoir plus¶

Pour d’autres exemples d’utilisation, voir la référence de l’API Achèvements du chat OpenAI ou le Cookbook OpenAI.

En plus de fournir une compatibilité avec l’API Chat Completions, Snowflake prend en charge les fonctionnalités compatibles OpenRouter pour les modèles Claude. Ces fonctionnalités sont exposées sous forme de champs supplémentaires dans la requête :

Pour la mise en cache des invites, utilisez le champ cache_control. Voir la ` documentation sur la mise en cache des invitesOpenRouter <https://openrouter.ai/docs/features/prompt-caching>`_.
Pour les jetons de raisonnement, utilisez le champ reasoning. Voir la documentation sur le raisonnement OpenRouter.

Référence de l’API Messages¶

POST /api/v2/cortex/v1/messages¶

Génère une réponse en utilisant un modèle Claude. Le format de la requête et de la réponse suit la `spécification de l’API Messages Anthropic<https://docs.anthropic.com/en/api/messages>`_.

POST https://<account_identifier>.snowflakecomputing.com/api/v2/cortex/v1/messages

Note

L’ API Messages prend en charge les modèles Claude uniquement. Pour les autres modèles, utilisez l’API Achèvements de chat.

En-têtes obligatoires¶

Authorization: Bearer token: Autorisation pour la requête.:samp:{token} est un jeton Web JSON (JWT ), un jeton OAuth ou un :doc:` jeton d’accès programmatique</user-guide/programmatic-access-tokens>`. Pour plus de détails, voir Authentification d”Snowflake REST APIs avec Snowflake.
Content-Type: application/json: Spécifie que le corps de la requête est en format JSON.
anthropic-version: 2023-06-01: En-tête de version d’API Anthropic requis.

En-têtes facultatifs¶

X-Snowflake-Authorization-Token-Type: type

Définit le type de jeton d’autorisation.

Si vous omettez l’en-tête X-Snowflake-Authorization-Token-Type, Snowflake détermine le type de jeton en examinant le jeton.

Bien que cet en-tête soit facultatif, vous pouvez choisir de le spécifier. Vous pouvez définir l’en-tête sur l’une des valeurs suivantes :

KEYPAIR_JWT (pour l’authentification par paire de clés)
OAUTH (pour OAuth)
PROGRAMMATIC_ACCESS_TOKEN (pour les jetons d’accès programmatiques)

anthropic-beta: feature

Active les fonctions bêta. Seuls les en-têtes bêta compatibles Bedrock sont pris en charge.

Champs JSON obligatoires¶


Champ	Type	Description
`model`	string	Le modèle Claude à utiliser (voir Disponibilité du modèle).
`max_tokens`	entier	Le nombre maximal de jetons à générer.
`messages`	tableau	Un tableau d’objets de message. Chaque message a un `role` (`user` ou``assistant``) et``content`` (chaîne ou tableau de blocs de contenu).

Fonctionnalités prises en charge¶

L’API Messages prend en charge l’ensemble de fonctionnalités d’API Messages Anthropic standard pour les modèles Claude, dont :

Génération de texte et conversations à plusieurs tours
Streaming ("stream": true)
Messages système (via le champ system de niveau supérieur)
Appel d’outils (format Anthropic avec name, description, input_schema)
Inclusion d’images (blocs sources base64)
Mise en cache des invites (cache_control sur les blocs de contenu)
Réflexion étendue (paramètre thinking avec``budget_tokens``)

Pour des détails complets sur les schémas de requêtes et de réponses, voir la documentation de l’API Messages Anthropic.

Limitations¶

**Modèles Claude uniquement.**OpenAI, Llama, Mistral et d’autres modèles ne sont pas disponibles via ce point de terminaison.
Pas de traitement flexible ni de niveau de priorité. Le champ service_tier n’est pas pris en charge.
En-têtes bêta Bedrock uniquement. Seules les valeurs d’en-tête anthropic-beta compatibles Bedrock sont prises en charge.
Les messages d’erreur sont générés par Snowflake et non par Anthropic.

Codes de statut¶

200 OK: La requête a été complétée avec succès.
400 invalid_request_error: Le corps de la requête est malformé ou contient des valeurs non valides.
400 unknown model model_name: Le modèle spécifié n’existe pas ou n’est pas un modèle Claude.
402 budget exceeded: Le budget de consommation du modèle a été dépassé.
403 Not Authorized: Compte non activé pour l’API REST ou le rôle par défaut n’a pas le rôle de base de données snowflake.cortex_user.
429 too many requests: Le quota d’utilisation a été dépassé. Veuillez réessayer plus tard.
503 inference timed out: La requête a pris trop de temps.

Limites de débit¶

Afin de garantir des performance élevées pour tous les clients de Snowflake, les requêtes d’API REST Snowflake Cortex sont soumises à des limites de débit. Les requêtes dépassant les limites peuvent recevoir une réponse HTTP 429. Snowflake peut parfois ajuster ces limites.

Les limites par défaut dans les tableaux suivants sont appliquées par compte et indépendamment pour chaque modèle. Assurez-vous que votre application traite correctement les réponses 429 en réessayant avec l’interruption exponentielle.

Si vous avez besoin d’augmenter cette limite, contactez le support Snowflake.

Limites de débit API REST Cortex¶
Modèle	Jetons traités par minute (TPM)	Requêtes par Minute (RPM)	Sortie maximale (jetons)
`claude-3-5-sonnet`	300,000	300	16,384
`claude-3-7-sonnet`	300,000	300	16,384
`claude-sonnet-4-5`	600,000	600	16,384
`claude-haiku-4-5`	600,000	600	16,384
`claude-4-sonnet`	300,000	300	16,384
`claude-4-opus`	75,000	75	16,384
`deepseek-r1`	100,000	100	16,384
`llama3.1-8b`	400,000	400	16,384
`llama3.1-70b`	200,000	200	16,384
`llama3.1-405b`	100,000	100	16,384
`mistral-7b`	400,000	400	16,384
`mistral-large2`	200,000	200	16,384
`openai-gpt-4.1`	300,000	300	16,384
`openai-gpt-5`	300,000	300	16,384
`openai-gpt-5-chat`	300,000	300	16,384
`openai-gpt-5-mini`	1,000,000	1,000	16,384
`openai-gpt-5-nano`	5,000,000	5,000	16,384

Augmenter les limites de débit grâce à l’inférence interrégionale¶

si vous configurez l’inférence interrégionale dans votre compte snowflake, les limites de débit pour sont plus élevées pour les modèles suivants :

Limites de début de l’API REST avec inférence interrégionale¶
Modèle	Jetons traités par minute (TPM)	Requêtes par Minute (RPM)	Sortie maximale (jetons)
`claude-3-7-sonnet`	600,000	600	16,384
`claude-haiku-4-5`	600,000	600	16,384
`claude-sonnet-4-5`	600,000	600	16,384
`claude-4-sonnet`	1 200 000	1,200	16,384
`claude-4-opus`	150,000	150	16,384
`llama3.1-8b`	800,000	400	16,384
`llama3.1-70b`	400,000	200	16,384
`llama3.1-405b`	200,000	100	16,384

Dépannage des événements de limite de débit¶

Ne pas respecter les limites TPM ou RPM entraînera un code de réponse 429. si votre utilisation de l’API REST est inférieure à la limite de débit de requête par minute, mais a quand même reçu un code de réponse 429, revérifiez la limite d’utilisation des jetons.

l’API REST cortex implémente des limites de débit à l’aide du modèle compteur de fenêtrages glissants. Les compteurs sont stockés dans un cluster Redis hautement disponible qui n’est accessible que par Snowflake Cortex au sein du réseau privé de Snowflake.

le compteur à fenêtrages glissants suppose que le trafic du client vers l’API dans le fenêtrage temporel précédent est uniformément distribué. Lorsque le trafic est important, cette hypothèse pourrait surestimer le taux des requêtes, mais se rétablit rapidement étant donné que le fenêtrage est court. Veuillez contacter l’assistance Snowflake si vous êtes soumis à une surestimation et que vous souhaitez augmenter les limites.

Problèmes connus¶

Expiration des jetons de session¶

Nous vous recommandons de vous authentifier avec l’une des trois méthodes définies dans Authentification d”Snowflake REST APIs avec Snowflake. Cependant, si vous choisissez de vous authentifier avec un jeton de session Snowflake, vous devez gérer l’actualisation du jeton pour assurer un accès ininterrompu à l’API.

Les jetons de session expirent périodiquement. Si une requête est exécutée avec un jeton de session expiré, l’API REST renvoie une réponse 200 OK qui comprend le code d’erreur 390112. Lorsque cela se produit, l’opération n’est pas effectuée.

Pour gérer ce comportement, votre application doit :

Vérifiez chaque réponse d’API pour le code d’erreur 390112, même lorsque le code d’état HTTP est 200 OK.
Lorsque le code d’erreur 390112 est détecté, actualisez le jeton de session et réessayez la requête.

Note

Ce comportement n’affecte que les applications utilisant des jetons de session Snowflake. Si vous vous authentifiez en utilisant l’authentification par paire de clés, OAuth ou des jetons d’accès programmatiques (PATs), vous n’avez pas besoin d’implémenter ce traitement des erreurs.

Considérations relatives aux clients¶

Les requêtes API REST Snowflake Cortex ont un coût de calcul basé sur le nombre de jetons traités. Reportez-vous au Tableau de consommation du service Snowflake pour connaître le coût de chaque modèle en crédits par million de jetons.

Un jeton est la plus petite unité de texte traitée par les fonctions Snowflake Cortex LLM, correspondant approximativement à quatre caractères de texte. L’équivalence du texte brut d’entrée ou de sortie en jetons peut varier selon le modèle.

Les jetons d’entrée et de sortie entraînent tous deux des coûts de calcul. Si vous utilisez l’API pour offrir une expérience utilisateur conversationnelle ou de chat, toutes les invites et réponses précédentes sont traitées pour générer chaque nouvelle réponse, avec les coûts correspondants.