Cortex REST API¶

Die Cortex REST API bietet Ihnen Zugriff auf führende Fronter-Modelle von Anthropic, OpenAI, Meta, Mistral und mehr über Ihren bevorzugten Endpunkt oder Ihr SDK. Alle Inferenzen werden innerhalb des Snowflake-Perimeters ausgeführt, sodass Ihre Daten sicher und innerhalb Ihrer Governance-Grenze bleiben. Nachfolgend finden Sie eine Anleitung für den Einstieg.

Auswahl der API¶

Die Cortex REST API unterstützt zwei branchenübliche API-Spezifikationen. Wählen Sie die Option aus, die am besten zu Ihrem Stapel passt:


	Chat Completions API	Messages API
Kompatibilität	OpenAI Chat Completions API	Anthropic Messages API
Endpunkt	`/api/v2/cortex/v1/chat/completions`	`/api/v2/cortex/v1/messages`
Unterstützte Modelle	Alle Modelle (OpenAI, Claude, Llama, Mistral, DeepSeek, Snowflake)	Nur Claude-Modelle
SDK-Unterstützung	OpenAI Python und JavaScript SDKs	Anthropic Python SDK
Am besten geeignet für	Die meisten Anwendungsfälle; Flexibilität bei mehreren Modellen	Bestehende Anthropic-Integrationen; Anthropic API-Parität

Beide APIs teilen sich dieselbe Authentifizierung, denselben Modellkatalog und dieselben Ratenbegrenzungen. Der einzige Unterschied sind das Anfrage-/Antwortformat und die von jedem Endpunkt unterstützten Modelle. Die Preise finden Sie in der Snowflake Service Consumption Table.

Quickstart¶

Voraussetzungen¶

Bevor Sie beginnen, benötigen Sie Folgendes:

Ihre Snowflake-Konto-URL** (z. B. https://<account-identifier>.snowflakecomputing.com).
Ein programmgesteuertes Snowflake-Zugriffstoken (PAT) für die Authentifizierung. Siehe Generierung eines programmatischen Zugriffstokens.
Einen Modellnamen zur Verwendung in Anforderungen. Siehe Verfügbarkeit der Modelle für verfügbare Modelle.

Schnellstart für Chat Completions API¶

Die Chat Completions API folgt der OpenAI-Spezifikation. Sie können direkt das OpenAI SDK verwenden.

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?"}
    ]
  }'

Ersetzen Sie in den vorherigen Beispielen Folgendes:

<account-identifier>: Ihr Snowflake-Kontobezeichner.
<SNOWFLAKE_PAT>: Ihr programmgesteuertes Snowflake-Zugriffstoken (PAT).
model: Der Modellname. Siehe Verfügbarkeit der Modelle für unterstützte Modelle.

Schnellstart für Messages API¶

Die Messages API folgt der Anthropic-Spezifikation und unterstützt nur Claude-Modelle.

Das Anthropic SDK sendet Anmeldeinformationen standardmäßig über x-api-key, aber Snowflake erwartet ein Bearer-Token. Verwenden Sie einen httpx-Client, um den korrekten Authentifizierungsheader einzustellen.

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)

Überschreiben Sie wie bei Python den Standard-Authentifizierungsheader mit einem Bearer-Token über``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?"}
    ]
  }'

Ersetzen Sie in den vorherigen Beispielen Folgendes:

<account-identifier>: Ihr Snowflake-Kontobezeichner.
<SNOWFLAKE_PAT>: Ihr programmgesteuertes Snowflake-Zugriffstoken (PAT).
model: Der Name des Claude-Modells. Siehe Verfügbarkeit der Modelle für unterstützte Modelle.

Einrichten der Authentifizierung¶

Um sich bei der Cortex REST API zu authentifizieren, können Sie die unter Authentifizierung von Snowflake REST APIs mit Snowflake beschriebenen Methoden verwenden.

Stellen Sie den Authorization-Header ein, um Ihr Token einzufügen (z. B. ein JSON-Web-Token (JWT), ein OAuth-Token oder ein programmgesteuertes Zugriffstoken).

Tipp

Erwägen Sie die Einrichtung eines eigenen Benutzers für Cortex REST API-Anfragen.

Festlegen der Autorisierung¶

Um eine REST API-Anforderung zu senden, muss Ihrer Standardrolle die Datenbankrolle SNOWFLAKE.CORTEX_USER zugewiesen werden. In den meisten Fällen verfügen Benutzende bereits über diese Berechtigung, da SNOWFLAKE.CORTEX_USER der Rolle PUBLIC automatisch erteilt wird und alle Rollen PUBLIC erben.

Wenn Ihr Snowflake-Admin diese Berechtigung widerrufen hat, muss sie erneut erteilt werden:

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

Wichtig

REST API-Anfragen verwenden die Standardrolle des Benutzers, sodass diese Rolle über die erforderlichen Berechtigungen verfügen muss. Sie können die Standardrolle eines Benutzenden mit ALTER USER … SET DEFAULT_ROLE ändern.

ALTER USER my_user SET DEFAULT_ROLE=my_role

Verfügbarkeit der Modelle¶

Die folgenden Tabellen zeigen die in der Cortex REST API für jede Region verfügbaren Modelle:


Modell	Cloudübergreifend (Alle Regionen)	AWS Global (Regionsübergreifend)	AWS-US (Regionsübergreifend)	AWS-EU (Regionsübergreifend)	AWS-APJ (Regionsübergreifend)	Azure Global (Regionsübergreifend)	Azure US (Regionsübergreifend)
`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`	✔	✔


Modell	AWS US West 2 (Oregon)	AWS US East 1 (N. Virginia)	Azure East US 2 (Virginia)
`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`	✔


Modell	AWS Europe Central 1 (Frankfurt)	AWS Europe West 1 (Ireland)	Azure West Europe (Niederlande)
`llama3.1-8b`	✔		✔
`llama3.1-70b`	✔	✔	✔
`mistral-7b`	✔		✔
`mistral-large`	✔		✔
`mistral-large2`	✔	✔	✔


Modell	AWS AP Southeast 2 (Sydney)	AWS AP Northeast 1 (Tokio)
`llama3.1-8b`	✔	✔
`llama3.1-70b`	✔	✔
`mistral-7b`		✔
`mistral-large`		✔
`mistral-large2`	✔	✔

* Zeigt ein Vorschau-Feature oder ein Modell an. Vorschau-Features sind nicht für Produktions-Workloads geeignet.

Sie können auch jedes feinabgestimmte Modell in jeder unterstützten Region verwenden.

Features¶

Streaming¶

Beide APIs unterstützen Streaming-Antworten mit vom Server gesendeten Ereignissen.

Chat Completions-Streaming¶

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
    }
  }'

Messages API-Streaming¶

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?"}
    ]
  }'

Toolaufruf¶

Mit dem Toolaufruf kann das Modell während einer Konversation externe Funktionen aufgerufen werden. Der Workflow umfasst folgende Schritte:

Sie senden eine Anforderung mit einer Liste der verfügbaren Tools.
Das Modell beschließt, ein oder mehrere Tools aufzurufen, und gibt den Namen des Tools und die Argumente zurück.
Sie führen das Tool an Ihrem Ende aus.
Sie senden das Tool-Ergebnis zurück und das Modell generiert eine endgültige Antwort.

Der Toolaufruf wird für OpenAI- und Claude-Modelle unterstützt.

Toolaufruf mit Chat Completions¶

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);
}

Schritt 1 – Senden der Anforderung mit Tools:

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"]
          }
        }
      }
    ]
  }'

Das Modell antwortet mit einem tool_calls-Array:

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

Schritt 2 – Ausführen des Tools und Senden des Ergebnisses:

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"]
          }
        }
      }
    ]
  }'

Toolaufruf mit Messages API¶

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);
}

Schritt 1 – Senden der Anforderung mit Tools:

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"]
        }
      }
    ]
  }'

Das Modell antwortet mit einem``tool_use``-Inhaltsblock:

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

Schritt 2 – Ausführen des Tools und Senden des Ergebnisses:

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"]
        }
      }
    ]
  }'

Strukturierte Ausgabe¶

Sie können eine strukturierte JSON-Ausgabe anfordern, die einem bestimmten Schema entspricht. Dies wird für OpenAI und Claude-Modelle durch die Chat Completions API unterstützt. Für die Messages API verwenden Sie das tool_use-Muster, um eine strukturierte Ausgabe zu erzwingen.

Strukturierte Ausgabe mit Chat Completions¶

Verwenden Sie das Feld response_format mit einem JSON-Schema, um die Ausgabe des Modells einzuschränken.

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"]
        }
      }
    }
  }'

Bemerkung

Claude-Modelle unterstützen nur``json_schema`` als Antwortformattyp.OpenAI-Modelle unterstützen zusätzliche Antwortformattypen, wie in der OpenAI API-Referenz dokumentiert.

Strukturierte Ausgabe mit der Messages API¶

Die Messages API hat kein Feld response_format. Definieren Sie stattdessen ein Tool mit dem gewünschten Ausgabeschema und weisen Sie das Modell an, dieses zu verwenden. Die tool_use-Antwort des Modells enthält strukturiertes JSON, das zu Ihrem Schema passt.

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

Bildeingabe¶

Sie können Bilder in Ihre Anfragen einfügen, wenn Sie Modelle nutzen, die visuelle Inhalte unterstützen. Bilder müssen als base64-codierte Zeichenfolgen bereitgestellt werden. Pro Konversation begrenzt auf 20 Bilder mit max. Anforderungsgröße von 20 MiB.

Die Bildeingabe wird unterstützt für:

Claude-Modelle (claude-3-7-sonnet und höher)
OpenAI-Modelle (openai-gpt-4.1, openai-gpt-5, openai-gpt-5-chat, openai-gpt-5-mini, openai-gpt-5-nano)

Bildeingabe mit Chat Completions¶

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?"
          }
        ]
      }
    ]
  }'

Bildeingabe mit der Messages API¶

Die Messages API verwendet ein anderes Bildformat – einen source-Block mit den Feldern type,``media_type`` und data anstelle einer Daten-URL.

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?"
          }
        ]
      }
    ]
  }'

Zwischenspeichern von Eingabeaufforderungen¶

Durch das Caching von Prompts können Sie zuvor verarbeiteten Kontext (z. B. große System-Prompts, Dokumente oder den Konversationsverlauf) für Anforderungen wiederverwenden, was die Latenz und die Kosten reduziert.

OpenAI-Modelle: Das Caching ist implizit. Prompts mit mehr als 1.024 Token werden automatisch zwischengespeichert – es sind keine Anforderungsänderungen erforderlich.
Claude-Modelle Das Caching ist explizit. Fügen Sie cache_control-Breakpoints zu Inhaltsblöcken hinzu, die zwischengespeichert werden sollen. Nur der Cachetyp ephemeral wird unterstützt, mit einem 5-Minuten-TTL. Maximal 4 Cache-Breakpoints pro Anforderung.

Prompt-Caching mit Chat Completions¶

Fügen Sie für Claude-Modelle über Chat Completions cache_control zu Inhaltsblöcken hinzu. OpenAI-Modelle werden automatisch zwischengespeichert und benötigen dieses Feld nicht.

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."}
    ]
  }'

Prompt-Caching mit der Messages API¶

Verwenden Sie cache_control für System- oder Benutzerinhaltsblöcken. Nur der Cachetyp ephemeral wird unterstützt, mit einem 5-Minuten-TTL. Pro Anforderung können maximal 4 Cache-Breakpoints gesetzt werden.

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."}
    ]
  }'

Bemerkung

Anthropic-Prompt-Caching hat ein 5-Minuten-TTL Zwischengespeicherte Inhalte, auf die nicht innerhalb von 5 Minuten zugegriffen wird, werden entfernt. OpenAI-Prompt-Caching ist implizit und wird automatisch verwaltet – keine cache_control-Felder erforderlich.

Thinking und Reasoning¶

Thinking mit Chat Completions¶

Für Claude-Modelle verwenden Sie das Objekt reasoning. Für OpenAI-Reasoning-Modelle verwenden Sie das Feld reasoning_effort (Werte: 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"
  }'

Thinking mit der Messages API¶

Einige Claude-Modelle unterstützen Adaptive Thinking, bei dem das Modell die Argumentationsfähigkeit an die Komplexität der Aufgabe anpasst. Die folgenden Modelle unterstützen Adaptive Thinking:

claude-opus-4-6

Verwenden Sie für die Messages API den Parameter thinking mit type: "adaptive", um Adaptive Thinking zu ermöglichen. Der Parameter output_config.effort bietet eine gewisse Kontrolle über die Denktiefe und akzeptiert die folgenden Werte:


Effort-Level	Verhalten
`max`	Denkt ohne Einschränkungen bei der Denktiefe. Nur Claude Opus 4.6.
`high` (Standard)	Denkt immer. Bietet tiefgreifendes Reasoning für komplexe Aufgaben.
`medium`	Moderates Denken. Kann den Denkprozess bei sehr einfachen Abfragen überspringen.
`low`	Minimiert das Denken. Überspringt den Denkprozess bei einfachen Aufgaben, bei denen es am meisten auf die Geschwindigkeit ankommt.

Die folgenden Beispiele zeigen, wie Sie einen Messages API-Aufruf mit aktiviertem Adaptive Thinking durchführen:

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?"}
    ]
  }'

Die Antwort enthält Denk-Blöcke mit zusammengefasstem Denkprozessen und Denksignaturen. Geben Sie diese Blöcke in Multi-Turn-Konversationen zurück, um den Reasoning-Kontext beizubehalten:

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

Eine vollständige Beschreibung der Messages API-Unterstützung für Adaptive Thinking finden Sie in der `Claude API-Dokumentation – Adaptives Thinking<https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking>`__.

Beta-Features (Messages API)¶

Die Messages API unterstützt Anthropic-Beta-Features über den anthropic-beta-Header. Übergeben Sie einen oder mehrere Beta-Header-Werte als kommagetrennte Zeichenfolge.

Unterstützte Beta-Header¶
Beta-Header-Wert	Feature
`token-efficient-tools-2025-02-19`	Token-effiziente Tools
`interleaved-thinking-2025-05-14`	Verschachteltes Denken
`output-128k-2025-02-19`	Ermöglicht die Ausgabe von Token bis zu 128 K
`dev-full-thinking-2025-05-14`	Entwicklermodus für Raw Thinking bei Claude 4+-Modellen
`context-1m-2025-08-07`	1-Million-Token-Kontextfenster
`context-management-2025-06-27`	Kontextverwaltung
`effort-2025-11-24`	Effort-Parameter für das Denken
`tool-search-tool-2025-10-19`	Tool für die Toolsuche
`tool-examples-2025-10-29`	Beispiele für die Verwendung von Tools

Das folgende Beispiel aktiviert das 1-Million-Token-Kontextfenster mit 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."}
    ]
  }'

Sie können mehrere Beta-Features kombinieren, indem Sie eine durch Kommas getrennte Zeichenfolge übergeben:

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

Chat Completions API-Referenz¶

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

Generiert eine Chat-Vervollständigung unter Verwendung des angegebenen Modells. Das Anforderungs- und Antwortformat folgt der OpenAI Chat Completions API-Spezifikation.

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

Erforderliche Header¶

Authorization: Bearer token: Autorisierung für die Anforderung. token ist ein JSON-Web-Token (JWT), ein OAuth-Token oder ein programmgesteuertes Zugriffstoken. Weitere Details dazu finden Sie unter Authentifizierung von Snowflake REST APIs mit Snowflake.
Content-Type: application/json: Gibt an, dass der Body der Anfrage im JSON-Format vorliegt.

Optionale Header¶

X-Snowflake-Authorization-Token-Type: type

Definiert die Art des Tokens für die Autorisierung.

Wenn Sie die Kopfzeile X-Snowflake-Authorization-Token-Type weglassen, bestimmt Snowflake den Token-Typ, indem es das Token untersucht.

Auch wenn diese Kopfzeile optional ist, können Sie sie angeben. Sie können die Kopfzeile auf einen der folgenden Werte setzen:

KEYPAIR_JWT (für Schlüsselpaar-Authentifizierung)
OAUTH (für OAuth)
PROGRAMMATIC_ACCESS_TOKEN (für programmatische Zugriffstokens)

Accept: application/json, text/event-stream

Gibt an, dass die Antwort entweder JSON (Fehlerfall) oder vom Server gesendete Ereignisse enthalten wird.

Erforderliche JSON-Felder¶


Feld	Typ	Beschreibung
`model`	string	Das zu verwendende Modell (siehe Verfügbarkeit der Modelle). Sie können auch den vollqualifizierten Namen eines beliebigen feinabgestimmten Modells im Format `database.schema.model` verwenden.
`messages`	Array	Ein Array von Nachrichtenobjekten, die die Konversation repräsentieren. Jede Nachricht muss eine `role` (`system`, `user`, `assistant` oder `tool`) und``content`` (Zeichenfolge oder Array von Inhaltsabschnitten) aufweisen.

Häufig verwendete optionale JSON-Felder¶


Feld	Typ	Standard	Beschreibung
`max_completion_tokens`	Ganzzahl	4096	Maximale Anzahl von Token in der Antwort. Das theoretische Maximum ist 131.072; jedes Modell hat seine eigene Ausgabebeschränkung.
`temperature`	number	Variiert je nach Modell	Steuert die Zufälligkeit. Werte von 0 bis 2.
`top_p`	number	1.0	Steuert die Vielfalt über Kern-Sampling.
`stream`	boolean	false	Ob Teilfortschritte als vom Server gesendete Ereignisse zurückgestreamt werden sollen.
`tools`	Array	null	Eine Liste von Tools, die das Modell aufrufen kann. Jedes Tool muss `type: "function"` und ein `function`-Objekt mit``name``, `description` und``parameters`` aufweisen.
`tool_choice`	string oder object	`"auto"`	Steuert, wie das Modell Tools auswählt. Optionen: `"auto"`, `"required"`, `"none"` oder ein Objekt, das eine bestimmte Funktion angibt.
`response_format`	Objekt	null	Schränkt das Ausgabeformat ein. Verwenden Sie `{"type": "json_schema", "json_schema": {...}}` für eine strukturierte Ausgabe.
`reasoning_effort`	string	null	Für OpenAI-Reasoning-Modelle. Werte: `"minimal"`, `"low"`, `"medium"`, `"high"`.
`reasoning`	Objekt	null	Für Claude-Modelle. Legen Sie `reasoning.effort` oder``reasoning.max_tokens`` fest, um das Denken zu aktivieren.

Die vollständige Liste der unterstützten Felder pro Modellfamilie finden Sie in der detaillierten Kompatibilitätstabelle.

Statuscodes¶

200 OK: Anfrage erfolgreich abgeschlossen.
400 invalid options object: Die optionalen Argumente haben ungültige Werte.
400 unknown model model_name: Das angegebene Modell ist nicht vorhanden.
400 schema validation failed: Die Struktur des Antwortschemas ist falsch.
400 max tokens of count exceeded: Die Anforderung hat die maximale Anzahl der vom Modell unterstützten Token überschritten.
400 all requests were throttled by remote service: Die Anforderung wurde gedrosselt. Versuchen Sie es später noch einmal.
402 budget exceeded: Das Budget für den Modellverbrauch wurde überschritten.
403 Not Authorized: Konto nicht für REST API aktiviert, oder die Standardrolle des aufrufenden Benutzers hat nicht die Datenbankrolle snowflake.cortex_user.
429 too many requests: Das Nutzungskontingent wurde überschritten. Versuchen Sie es später noch einmal.
503 inference timed out: Die Anfrage hat zu lange gedauert.

Einschränkungen¶

Wenn nicht gesetzt, ist der max_completion_tokens Standardwert 4096. Jedes Modell hat seine eigenen Grenzwerte für die Ausgabetoken.
Der Toolaufruf wird nur für OpenAI- und Claude-Modelle unterstützt.
Die Verwendung von Audio wird nicht unterstützt.
Bildverstehen wird nur für OpenAI- und Claude-Modelle unterstützt. Pro Konversation begrenzt auf 20 Bilder mit max. Anforderungsgröße von 20 MiB.
Nur Claude-Modelle unterstützen kurzlebige Cache-Kontrollpunkte für das Caching von Eingabeaufforderungen. OpenAI-Modelle unterstützen implizites Caching.
Nur Claude-Modelle unterstützen die Rückgabe des Reasonings in der Antwort.
max_tokens ist veraltet. Verwenden Sie stattdessen max_completion_tokens.
Fehlermeldungen werden von Snowflake generiert, nicht vom Modellanbieter.

Detaillierte Kompatibilitätstabelle¶

Die folgenden Tabellen fassen zusammen, welche Felder für Anforderungen und Antworten bei Verwendung der Chat Completions API mit verschiedenen von Snowflake gehosteten Modellfamilien unterstützt werden.

Anforderungsfelder¶
Feld	OpenAI-Modelle	Claude-Modelle	Andere Modelle
`model`	✔ unterstützt	✔ unterstützt	✔ unterstützt
`messages`	Siehe Unterfelder	Siehe Unterfelder	Siehe Unterfelder
`messages[].audio`	❌-Fehler	❌ Ignoriert	❌ Ignoriert
`messages[].role`	✔ unterstützt	✔ Nur Benutzer/Assistent/System	✔ Nur Benutzer/Assistent/System
`messages[].content` (string)	✔ unterstützt	✔ unterstützt	✔ unterstützt
`messages[].content[]` (array)	Siehe Unterfelder	Siehe Unterfelder	Siehe Unterfelder
`messages[].content[].text`	✔ unterstützt	✔ unterstützt	✔ unterstützt
`messages[].content[].type`	✔ unterstützt	✔ unterstützt	✔ unterstützt
`messages[].content[].image_url`	✔ unterstützt	✔ unterstützt	❌-Fehler
`messages[].content[].cache_control`	❌ Ignoriert	✔ unterstützt (nur ephemere)	❌ Ignoriert
`messages[].content[].file`	❌-Fehler	❌-Fehler	❌ Ignoriert
`messages[].content[].input_audio`	❌-Fehler	❌ Ignoriert	❌ Ignoriert
`messages[].content[].refusal`	✔ unterstützt	❌ Ignoriert	❌ Ignoriert
`messages[].function_call`	✔ unterstützt (veraltet)	❌ Ignoriert	❌ Ignoriert
`messages[].name`	✔ unterstützt	❌ Ignoriert	❌ Ignoriert
`messages[].refusal`	✔ unterstützt	❌ Ignoriert	❌ Ignoriert
`messages[].tool_call_id`	✔ unterstützt	✔ unterstützt	❌ Ignoriert
`messages[].tool_calls`	✔ unterstützt	✔ nur `function`-Tools	❌ Ignoriert
`messages[].reasoning_details`	❌ Ignoriert	✔ OpenRouter-Format `reasoning.text`	❌ Ignoriert
`audio`	❌-Fehler	❌ Ignoriert	❌ Ignoriert
`frequency_penalty`	✔ unterstützt	❌ Ignoriert	❌ Ignoriert
`logit_bias`	✔ unterstützt	❌ Ignoriert	❌ Ignoriert
`logprobs`	✔ unterstützt	❌ Ignoriert	❌ Ignoriert
`max_tokens`	❌ Fehler (veraltet)	❌ Fehler (veraltet)	❌ Fehler (veraltet)
`max_completion_tokens`	✔ unterstützt (Standardeinstellung 4096, max. 131072)	✔ unterstützt (Standardeinstellung 4096, max. 131072)	✔ unterstützt (Standardeinstellung 4096, max. 131072)
`metadata`	❌ Ignoriert	❌ Ignoriert	❌ Ignoriert
`modalities`	❌ Ignoriert	❌ Ignoriert	❌ Ignoriert
`n`	✔ unterstützt	❌ Ignoriert	❌ Ignoriert
`parallel_tool_calls`	✔ unterstützt	❌ Ignoriert	❌ Ignoriert
`prediction`	✔ unterstützt	❌ Ignoriert	❌ Ignoriert
`presence_penalty`	✔ unterstützt	❌ Ignoriert	❌ Ignoriert
`prompt_cache_key`	✔ unterstützt	❌ Ignoriert	❌ Ignoriert
`reasoning_effort`	✔ unterstützt	❌ ignoriert (verwenden Sie das `reasoning`-Objekt)	❌ Ignoriert
`reasoning`	Siehe Unterfelder	Siehe Unterfelder	Siehe Unterfelder
`reasoning.effort`	✔ unterstützt (überschreibt `reasoning_effort`)	✔ wird in `reasoning.max_tokens` konvertiert	❌ Ignoriert
`reasoning.max_tokens`	❌ Ignoriert	✔ unterstützt	❌ Ignoriert
`response_format`	✔ unterstützt	✔ nur `json_schema`	❌ Ignoriert
`safety_identifier`	❌ Ignoriert	❌ Ignoriert	❌ Ignoriert
`service_tier`	❌-Fehler	❌-Fehler	❌-Fehler
`stop`	✔ unterstützt	❌ Ignoriert	❌ Ignoriert
`store`	❌-Fehler	❌-Fehler	❌-Fehler
`stream`	✔ unterstützt	✔ unterstützt	✔ unterstützt
`stream_options`	Siehe Unterfelder	Siehe Unterfelder	Siehe Unterfelder
`stream_options.include_obfuscation`	❌ Ignoriert	❌ Ignoriert	❌ Ignoriert
`stream_options.include_usage`	✔ unterstützt	✔ unterstützt	✔ unterstützt
`temperature`	✔ unterstützt	✔ unterstützt	✔ unterstützt
`tool_choice`	✔ unterstützt	✔ nur `function`-Tools	❌ Ignoriert
`tools`	✔ unterstützt	✔ nur `function`-Tools	❌-Fehler
`top_logprobs`	✔ unterstützt	❌ Ignoriert	❌ Ignoriert
`top_p`	✔ unterstützt	✔ unterstützt	✔ unterstützt
`verbosity`	✔ unterstützt	❌ Ignoriert	❌ Ignoriert
`web_search_options`	❌-Fehler	❌ Ignoriert	❌ Ignoriert

Antwortfelder¶
Feld	OpenAI-Modelle	Claude-Modelle	Andere Modelle
`id`	✔ unterstützt	✔ unterstützt	✔ unterstützt
`object`	✔ unterstützt	✔ unterstützt	✔ unterstützt
`created`	✔ unterstützt	✔ unterstützt	✔ unterstützt
`model`	✔ unterstützt	✔ unterstützt	✔ unterstützt
`choices`	Siehe Unterfelder	Siehe Unterfelder	Siehe Unterfelder
`choices[].index`	✔ unterstützt	✔ nur einfache Auswahl	✔ nur einfache Auswahl
`choices[].finish_reason`	✔ unterstützt	❌ nicht unterstützt	✔ nur `stop`
`choices[].logprobs`	✔ unterstützt	❌ nicht unterstützt	❌ nicht unterstützt
`choices[].message` (nicht Streaming)	Siehe Unterfelder	Siehe Unterfelder	Siehe Unterfelder
`choices[].message.content`	✔ unterstützt	✔ unterstützt	✔ unterstützt
`choices[].message.role`	✔ unterstützt	✔ unterstützt	✔ unterstützt
`choices[].message.refusal`	✔ unterstützt	❌ nicht unterstützt	❌ nicht unterstützt
`choices[].message.annotations`	❌ nicht unterstützt	❌ nicht unterstützt	❌ nicht unterstützt
`choices[].message.audio`	❌ nicht unterstützt	❌ nicht unterstützt	❌ nicht unterstützt
`choices[].message.function_call`	✔ unterstützt	❌ nicht unterstützt	❌ nicht unterstützt
`choices[].message.tool_calls`	✔ unterstützt	✔ nur `function`-Tools	❌ nicht unterstützt
`choices[].message.reasoning`	❌ nicht unterstützt	✔ OpenRouter-Format	❌ nicht unterstützt
`choices[].delta` (Streaming)	Siehe Unterfelder	Siehe Unterfelder	Siehe Unterfelder
`choices[].delta.content`	✔ unterstützt	✔ unterstützt	✔ unterstützt
`choices[].delta.role`	✔ unterstützt	❌ nicht unterstützt	❌ nicht unterstützt
`choices[].delta.refusal`	✔ unterstützt	❌ nicht unterstützt	❌ nicht unterstützt
`choices[].delta.function_call`	✔ unterstützt	❌ nicht unterstützt	❌ nicht unterstützt
`choices[].delta.tool_calls`	✔ unterstützt	✔ nur `function`-Tools	❌ nicht unterstützt
`choices[].delta.reasoning`	❌ nicht unterstützt	✔ OpenRouter-Format	❌ nicht unterstützt
`usage`	Siehe Unterfelder	Siehe Unterfelder	Siehe Unterfelder
`usage.prompt_tokens`	✔ unterstützt	✔ unterstützt	✔ unterstützt
`usage.completion_tokens`	✔ unterstützt	✔ unterstützt	✔ unterstützt
`usage.total_tokens`	✔ unterstützt	✔ unterstützt	✔ unterstützt
`usage.prompt_tokens_details`	Siehe Unterfelder	Siehe Unterfelder	Siehe Unterfelder
`usage.prompt_tokens_details.audio_tokens`	❌ nicht unterstützt	❌ nicht unterstützt	❌ nicht unterstützt
`usage.prompt_tokens_details.cached_tokens`	✔ Nur Lesecache	✔ Lese- und Schreibcache	❌ nicht unterstützt
`usage.completion_tokens_details`	Siehe Unterfelder	Siehe Unterfelder	Siehe Unterfelder
`usage.completion_tokens_details.accepted_prediction_tokens`	✔ unterstützt	❌ nicht unterstützt	❌ nicht unterstützt
`usage.completion_tokens_details.audio_tokens`	❌ nicht unterstützt	❌ nicht unterstützt	❌ nicht unterstützt
`usage.completion_tokens_details.reasoning_tokens`	✔ unterstützt	❌ nicht unterstützt	❌ nicht unterstützt
`usage.completion_tokens_details.rejected_prediction_tokens`	✔ unterstützt	❌ nicht unterstützt	❌ nicht unterstützt
`service_tier`	✔ unterstützt	❌ nicht unterstützt	❌ nicht unterstützt
`system_fingerprint`	✔ unterstützt	❌ nicht unterstützt	❌ nicht unterstützt

Header der Anforderung¶
Header	Unterstützung
`Authorization`	✔ erforderlich
`Content-Type`	✔ unterstützt (`application/json`)
`Accept`	✔ unterstützt (`application/json`, `text/event-stream`)

Antwort-Header¶
Header	Unterstützung
`openai-organization`	❌ nicht unterstützt
`openai-version`	❌ nicht unterstützt
`openai-processing-ms`	❌ nicht unterstützt
`x-ratelimit-limit-requests`	❌ nicht unterstützt
`x-ratelimit-limit-tokens`	❌ nicht unterstützt
`x-ratelimit-remaining-requests`	❌ nicht unterstützt
`x-ratelimit-remaining-tokens`	❌ nicht unterstützt
`x-ratelimit-reset-requests`	❌ nicht unterstützt
`x-ratelimit-reset-tokens`	❌ nicht unterstützt
`retry-after`	❌ nicht unterstützt

Mehr erfahren¶

Weitere Anwendungsbeispiele finden Sie in der OpenAI Chat Completions API-Referenz oder dem OpenAI Cookbook.

Zusätzlich zur Kompatibilität mit der Chat Completions API unterstützt Snowflake OpenRouter-kompatible Features für Claude-Modelle. Diese Features werden als zusätzliche Felder auf der Anforderung angezeigt:

Verwenden Sie für das Zwischenspeichern von Eingabeaufforderungen das Feld cache_control. Siehe die OpenRouter-Dokumentation zum Caching von Prompts.
Verwenden Sie für Reasoning-Token das Feld reasoning. Siehe die OpenRouter-Dokumentation zu Reasoning.

Messages API-Referenz¶

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

Generiert eine Antwort unter Verwendung eines Claude-Modells. Das Anforderungs- und Antwortformat folgt der Anthropic Messages API-Spezifikation.

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

Bemerkung

Die Messages API unterstützt nur Claude-Modelle. Für andere Modelle verwenden Sie die Chat Completions API.

Erforderliche Header¶

Authorization: Bearer token: Autorisierung für die Anforderung. token ist ein JSON-Web-Token (JWT), ein OAuth-Token oder ein programmgesteuertes Zugriffstoken. Weitere Details dazu finden Sie unter Authentifizierung von Snowflake REST APIs mit Snowflake.
Content-Type: application/json: Gibt an, dass der Body der Anfrage im JSON-Format vorliegt.
anthropic-version: 2023-06-01: Erforderlicher Anthropic API-Versions-Header.

Optionale Header¶

X-Snowflake-Authorization-Token-Type: type

Definiert die Art des Tokens für die Autorisierung.

Wenn Sie die Kopfzeile X-Snowflake-Authorization-Token-Type weglassen, bestimmt Snowflake den Token-Typ, indem es das Token untersucht.

Auch wenn diese Kopfzeile optional ist, können Sie sie angeben. Sie können die Kopfzeile auf einen der folgenden Werte setzen:

KEYPAIR_JWT (für Schlüsselpaar-Authentifizierung)
OAUTH (für OAuth)
PROGRAMMATIC_ACCESS_TOKEN (für programmatische Zugriffstokens)

anthropic-beta: feature

Aktiviert Beta-Features. Es werden nur Bedrock-kompatible Beta-Header unterstützt.

Erforderliche JSON-Felder¶


Feld	Typ	Beschreibung
`model`	string	Das zu verwendende Claude-Modell (siehe Verfügbarkeit der Modelle).
`max_tokens`	Ganzzahl	Die maximale Anzahl von zu generierenden Token.
`messages`	Array	Ein Array von Nachrichtenobjekten. Jede Nachricht enthält eine `role` (`user` oder `assistant`) und `content` (Zeichenfolge oder Array von Inhaltsblöcken).

Unterstützte Features¶

Die Messages API unterstützt das Anthropic Messages API-Standard-Feature-Set für Claude-Modelle, einschließlich:

Textgenerierung und Multi-Turn-Konversationen
Streaming ("stream": true)
Systemmeldungen (über das Feld system der obersten Ebene)
Toolaufruf (Anthropic-Format mit``name``, description, input_schema)
Bildeingabe (base64-Quellblöcke)
Prompt-Caching (cache_control für Inhaltsblöcke)
Erweitertes Thinking (thinking-Parameter mit budget_tokens)

Vollständige Details zum Anforderungs- und Antwortschema finden Sie in der ` Anthropic Messages API-Dokumentation <https://docs.anthropic.com/en/api/messages>`_.

Einschränkungen¶

Nur Claude-Modelle. OpenAI, Llama, Mistral und andere Modelle sind über diesen Endpunkt nicht verfügbar.
Keine flexible Verarbeitung oder Prioritätsstufe. Das Feld service_tier wird nicht unterstützt.
Nur Bedrock-Beta-Header. Nur Bedrock-kompatible anthropic-beta-Header-Werte werden unterstützt.
Fehlermeldungen werden von Snowflake und nicht von Anthropic generiert.

Statuscodes¶

200 OK: Anfrage erfolgreich abgeschlossen.
400 invalid_request_error: Der Anforderungstext ist fehlerhaft oder enthält ungültige Werte.
400 unknown model model_name: Das angegebene Modell existiert nicht oder ist kein Claude-Modell.
402 budget exceeded: Das Budget für den Modellverbrauch wurde überschritten.
403 Not Authorized: Konto nicht für REST API aktiviert, oder die Standardrolle hat nicht die Datenbankrolle snowflake.cortex_user.
429 too many requests: Das Nutzungskontingent wurde überschritten. Versuchen Sie es später noch einmal.
503 inference timed out: Die Anfrage hat zu lange gedauert.

Rateneinschränkungen¶

Um für alle Snowflake-Kunden eine hohe Leistung sicherzustellen, unterliegen die Cortex REST API-Anforderungen Einschränkungen bezüglich der Anforderungsraten. Für Anfragen, die diese Einschränkungen überschreiten, wird ggf. der HTTP-Antwortcode 429 ausgegeben. Snowflake kann diese Einschränkungen gelegentlich anpassen.

Die in den folgenden Tabellen aufgeführten Standardeinschränkungen gelten pro Konto und werden für jedes Modell unabhängig voneinander angewendet. Stellen Sie sicher, dass Ihre Anwendung 429-Antworten ordnungsgemäß verarbeitet, indem Sie die Anforderung mit einem exponentiellen Backoff erneut durchführen.

Wenn Sie diese Einschränkungen erhöhen müssen, wenden Sie sich an den Snowflake-Support.

Cortex REST API – Einschränkungen für Anfrageraten¶
Modell	Verarbeitete Token pro Minute (TPM)	Anfragen pro Minute (RPM)	Maximale Ausgabe (Token)
`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

Einschränkungen für Anfrageraten mit regionenübergreifender Inferenz erhöhen¶

Wenn Sie in Ihrem Snowflake-Konto regionenübergreifende Inferenz eingerichtet haben, sind die Rateneinschränkungen bei folgenden Modellen höher:

Rateneinschränkungen für die Cortex-REST-API mit regionenübergreifender Inferenz¶
Modell	Verarbeitete Token pro Minute (TPM)	Anfragen pro Minute (RPM)	Maximale Ausgabe (Token)
`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

Fehlerbehebung bei Ereignissen mit Rateneinschränkungen¶

Ein Verstoß gegen die TPM- oder RPM-Einschränkungen führt zu einem 429-Antwortcode. Wenn Ihre REST-API-Nutzung unter der Rateneinschränkung für Anfragen pro Minute liegt, aber dennoch ein 429-Antwortcode empfangen wurde, überprüfen Sie die Token-Nutzungsrate.

Die Cortex-REST-API implementiert Rateneinschränkungen mit dem Muster des Zählers für gleitende Fenster. Die Zähler werden in einem hochverfügbaren Redis-Cluster gespeichert, auf den nur Snowflake Cortex innerhalb des privaten Netzwerks von Snowflake zugreifen kann.

Der Zähler für gleitende Fenster geht davon aus, dass Clientdatenverkehr zur API im vorherigen Zeitfenster gleichmäßig verteilt ist. Bei starkem Datenverkehr könnte diese Annahme zu einer Überschätzung der Anfragerate führen, aber da das Zeitfenster kurz ist, gleicht sich dies schnell wieder aus. Wenden Sie sich an den Snowflake-Support, wenn Sie auf eine solche Überschätzung stoßen und die Einschränkungen erhöhen möchten.

Bekannte Probleme¶

Ablauf des Sitzungstokens¶

Wir empfehlen, sich mit einer der drei in Authentifizierung von Snowflake REST APIs mit Snowflake definierten Methoden zu authentifizieren. Wenn Sie sich jedoch für die Authentifizierung mit einem Snowflake-Sitzungstoken entscheiden, müssen Sie die Aktualisierung des Tokens handhaben, um einen API-Zugriff ohne Unterbrechung sicherzustellen.

Sitzungstoken laufen regelmäßig ab. Wenn eine Anforderung mit einem abgelaufenen Sitzungstoken ausgeführt wird, gibt die REST-API eine 200 OK-Antwort zurück, die den Fehlercode 390112 enthält. In diesem Fall wird die Operation nicht ausgeführt.

Um dieses Verhalten verarbeiten zu können, sollte Ihre Anwendung Folgendes bieten:

Überprüfen Sie jeweils die API-Antwort für den Fehlercode 390112, auch wenn der HTTP-Statuscode 200 OK ist.
Wenn der Fehlercode 390112 erkannt wird, aktualisieren Sie das Sitzungstoken, und versuchen Sie erneut die Anforderung.

Bemerkung

Dieses Verhalten betrifft nur Anwendungen, die Snowflake-Sitzungstoken verwenden. Wenn Sie sich mit der Schlüsselpaar-Authentifizierung, OAuth oder mit :ref:`programmgesteuerten Zugriffstoken (PATs) <label-sfrest_authenticating_pat>`authentifizieren, müssen Sie diese Fehlerbehandlung nicht implementieren.

Hinweise zu Kosten¶

Snowflake Cortex REST API-Anforderungen verursachen Kosten, die sich nach der Anzahl der verarbeiteten Token richten. Die Kosten für jede Funktion in Dollar pro Million Token finden Sie in der Snowflake Service Consumption Table.

Ein Token ist die kleinste Texteinheit, die von den Snowflake Cortex-LLM-Funktionen verarbeitet wird, und entspricht etwa vier Textzeichen. Das Verhältnis des ein-/ausgegebene Rohtextes zur Tokenanzahl kann je nach Modell variieren.

Sowohl für Eingabe- als auch für Ausgabe-Token fallen Computekosten an. Wenn Sie die API verwenden, um ein Konversations- oder Chat-Benutzererlebnis zu bieten, werden alle vorherigen Prompts und Antworten verarbeitet, um jede neue Antwort zu generieren, mit entsprechenden Kosten.