Cortex Chat Completions API¶

Cortex Chat Completions API は、OpenAI Chat Completions API のモデルに依存しないスーパーセットであり、ツール、ライブラリ、サードパーティ AI アプリケーションの広大なエコシステムとの互換性を実現します。

Cortex Chat Completions API は、Cortex REST API のコンパニオン API で、OpenAI モデルのサポートが強化されています。Cortex REST API について詳しくは、Cortex REST API をご覧ください。

OpenAI SDK 入門¶

重要

OpenAI ライブラリドキュメントで指定されている、次のいずれかの言語の OpenAI SDK の公式バージョンを使用していることを確認してください。

Python
TypeScript/JavaScript

開始するにあたり、次のものが必要です。

Snowflakeアカウント URL。これは、OpenAI クライアントのベース URL を構築するために使用されます。
Snowflake Programmaticアクセストークン（PAT）。これは、Cortex Chat Completions API への認証に使用されます。PAT の作成の詳細については、プログラムアクセストークンの生成をご参照ください。
リクエストで使用する有効なモデル名。サポートされているモデルのリストについては、モデルの可用性を参照してください。

簡単なコード例¶

以下の例では、Python、JavaScript/TypeScript 、curl を使ってOpenAI SDKs にリクエストする方法を示しています。

PythonSDK を使い始めるには、次のコードを使用します。

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="<model_name>",
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)

Copy

上記のコードで、次の値を指定します。

base_url:<account-identifier> をお客様のSnowflakeアカウント識別子に置き換えてください。
api_key:<SNOWFLAKE_PAT> をお客様の Snowflake Programmaticアクセストークン（PAT）に置き換えてください。
model:<model_name> を使用したいモデル名に置き換えてください。サポートされているモデルのリストについては、モデルの可用性を参照してください。

JavaScript/TypeScript SDK を使い始めるには、次のコードを使用します。

import OpenAI from "openai";

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

const response = await openai.chat.completions.create({
  model: "claude-3-7-sonnet",
  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);

Copy

上記のコードで、次の値を指定します。

baseURL:<account-identifier> をお客様のSnowflakeアカウント識別子に置き換えてください。
apikey:SNOWFLAKE_PAT をお客様の Snowflake個人用アクセストークン（PAT）に置き換えてください。
model:<model_name> を使用したいモデル名に置き換えてください。サポートされているモデルのリストについては、モデルの可用性を参照してください。

以下の curl コマンドを使用して、Snowflakeホストモデルにリクエストを行います。

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

Copy

上記のコードで、次の値を指定します。

<account-identifier>:<account-identifier> をお客様のSnowflakeアカウント識別子に置き換えてください。
<SNOWFLAKE_PAT>:<SNOWFLAKE_PAT> をお客様の Snowflake個人用アクセストークン（PAT）に置き換えてください。
<model_name>:<model_name> を使用したいモデル名に置き換えてください。サポートされているモデルのリストについては、モデルの可用性を参照してください。

応答のストリーミング¶

リクエストの stream パラメーターを True に設定することで、REST API からの応答をストリーミングすることができます。

以下のPythonコードは、REST API からの応答をストリーミングします。

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="<model_name>",
  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)

Copy

次の JavaScript/TypeScript コードは、REST API からの応答をストリーミングします。

import OpenAI from "openai";

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

const stream = await openai.chat.completions.create({
    model: "<model_name>",
    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) {
  console.log(event);
}

Copy

次の curl コマンドは、Snowflakeホストモデルからの応答をストリーミングします。

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

Copy

制限事項¶

以下は、Snowflakeホストモデルで OpenAI SDK を使用する際の制限事項です。

Chat Completionsのみがサポートされています。
未設定の場合、max_completion_tokens のデフォルトは4096です。Cortex Chat Completions API の理論上の最大値は131,072です。各モデルには独自の出力トークン制限があり、131,072を下回る場合があります。
ツール呼び出しは、OpenAI およびClaudeモデルでサポートされています。ツール呼び出しを効果的に使う例については、思考の連鎖によるツール呼び出しの例を参照してください。
オーディオはサポートされていません。
画像認識は、OpenAI およびClaudeモデルのみサポートされています。画像は会話ごとに20枚まで、最大リクエストサイズは20 MiB です。
プロンプトキャッシュ用の短期キャッシュ制御ポイントは、Claudeモデルのみでサポートされています。OpenAI モデルは暗黙的なキャッシュをサポートしています。
Claudeモデルのみが、応答で推論の詳細を返すことをサポートしています。
エラーメッセージは、OpenAI ではなく、Snowflakeによって生成されます。報告されたエラーは、ロギングとデバッグの目的のみに使用することをお勧めします。

詳細な互換性チャート¶

以下の表は、異なるSnowflakeホストモデルでCortex Chat Completions API を使用する場合、どのリクエストと応答のフィールドとヘッダーがサポートされるかをまとめたものです。

リクエストフィールド¶
フィールド	OpenAI モデル	Claudeモデル	その他のモデル
`model`	✔ サポート対象	✔ サポート対象	✔ サポート対象
`messages`	サブフィールドを見る	サブフィールドを見る	サブフィールドを見る
`messages[].audio`	❌ エラー	❌ は無視されました	❌ は無視されました
`messages[].role`	✔ サポート対象	✔ ユーザー/アシスタント/システムのみ	✔ ユーザー/アシスタント/システムのみ
`messages[].content` （string）	✔ サポート対象	✔ サポート対象	✔ サポート対象
:code:`messages[].content[]`（配列）	サブフィールドを見る	サブフィールドを見る	サブフィールドを見る
`messages[].content[].text`	✔ サポート対象	✔ サポート対象	✔ サポート対象
`messages[].content[].type`	✔ サポート対象	✔ サポート対象	✔ サポート対象
`messages[].content[].image_url`	✔ サポート対象	✔ サポート対象	❌ エラー
`messages[].content[].cache_control`	❌ は無視されました	✔ サポート対象（短期のみ）	❌ は無視されました
`messages[].content[].file`	❌ エラー	❌ エラー	❌ は無視されました
`messages[].content[].input_audio`	❌ エラー	❌ は無視されました	❌ は無視されました
`messages[].content[].refusal`	✔ サポート対象	❌ は無視されました	❌ は無視されました
`messages[].function_call`	✔ サポート対象（非推奨）	❌ は無視されました	❌ は無視されました
`messages[].name`	✔ サポート対象	❌ は無視されました	❌ は無視されました
`messages[].refusal`	✔ サポート対象	❌ は無視されました	❌ は無視されました
`messages[].tool_call_id`	✔ サポート対象	✔ サポート対象	❌ は無視されました
`messages[].tool_calls`	✔ サポート対象	✔ `function` ツールのみ	❌ は無視されました
`messages[].reasoning_details`	❌ は無視されました	✔ OpenRouter 形式 `reasoning.text`	❌ は無視されました
`audio`	❌ エラー	❌ は無視されました	❌ は無視されました
`frequency_penalty`	✔ サポート対象	❌ は無視されました	❌ は無視されました
`logit_bias`	✔ サポート対象	❌ は無視されました	❌ は無視されました
`logprobs`	✔ サポート対象	❌ は無視されました	❌ は無視されました
`max_tokens`	❌ エラー（非推奨）	❌ エラー（非推奨）	❌ エラー（非推奨）
`max_completion_tokens`	✔ サポート対象（デフォルト4096、最大131072）	✔ サポート対象（デフォルト4096、最大131072）	✔ サポート対象（デフォルト4096、最大131072）
`metadata`	❌ は無視されました	❌ は無視されました	❌ は無視されました
`modalities`	❌ は無視されました	❌ は無視されました	❌ は無視されました
`n`	✔ サポート対象	❌ は無視されました	❌ は無視されました
`parallel_tool_calls`	✔ サポート対象	❌ は無視されました	❌ は無視されました
`prediction`	✔ サポート対象	❌ は無視されました	❌ は無視されました
`presence_penalty`	✔ サポート対象	❌ は無視されました	❌ は無視されました
`prompt_cache_key`	✔ サポート対象	❌ は無視されました	❌ は無視されました
`reasoning_effort`	✔ サポート対象	❌ は無視されました（`reasoning` オブジェクトを使用）	❌ は無視されました
`reasoning`	サブフィールドを見る	サブフィールドを見る	サブフィールドを見る
`reasoning.effort`	✔ サポート対象（`reasoning_effort` をオーバーライド）	✔ は `reasoning.max_tokens` に変換されます	❌ は無視されました
`reasoning.max_tokens`	❌ は無視されました	✔ サポート対象	❌ は無視されました
`response_format`	✔ サポート対象	✔ Only `json_schema`	❌ は無視されました
`safety_identifier`	❌ は無視されました	❌ は無視されました	❌ は無視されました
`service_tier`	❌ エラー	❌ エラー	❌ エラー
`stop`	✔ サポート対象	❌ は無視されました	❌ は無視されました
`store`	❌ エラー	❌ エラー	❌ エラー
`stream`	✔ サポート対象	✔ サポート対象	✔ サポート対象
`stream_options`	サブフィールドを見る	サブフィールドを見る	サブフィールドを見る
`stream_options.include_obfuscation`	❌ は無視されました	❌ は無視されました	❌ は無視されました
`stream_options.include_usage`	✔ サポート対象	✔ サポート対象	✔ サポート対象
`temperature`	✔ サポート対象	✔ サポート対象	✔ サポート対象
`tool_choice`	✔ サポート対象	✔ `function` ツールのみ	❌ は無視されました
`tools`	✔ サポート対象	✔ `function` ツールのみ	❌ エラー
`top_logprobs`	✔ サポート対象	❌ は無視されました	❌ は無視されました
`top_p`	✔ サポート対象	✔ サポート対象	✔ サポート対象
`verbosity`	✔ サポート対象	❌ は無視されました	❌ は無視されました
`web_search_options`	❌ エラー	❌ は無視されました	❌ は無視されました

応答フィールド¶
フィールド	OpenAI モデル	Claudeモデル	その他のモデル
`id`	✔ サポート対象	✔ サポート対象	✔ サポート対象
`object`	✔ サポート対象	✔ サポート対象	✔ サポート対象
`created`	✔ サポート対象	✔ サポート対象	✔ サポート対象
`model`	✔ サポート対象	✔ サポート対象	✔ サポート対象
`choices`	サブフィールドを見る	サブフィールドを見る	サブフィールドを見る
`choices[].index`	✔ サポート対象	✔ 単一選択のみ	✔ 単一選択のみ
`choices[].finish_reason`	✔ サポート対象	❌ サポート対象外	✔ `stop` のみ
`choices[].logprobs`	✔ サポート対象	❌ サポート対象外	❌ サポート対象外
:code:`choices[].message`（非ストリーミング）	サブフィールドを見る	サブフィールドを見る	サブフィールドを見る
`choices[].message.content`	✔ サポート対象	✔ サポート対象	✔ サポート対象
`choices[].message.role`	✔ サポート対象	✔ サポート対象	✔ サポート対象
`choices[].message.refusal`	✔ サポート対象	❌ サポート対象外	❌ サポート対象外
`choices[].message.annotations`	❌ サポート対象外	❌ サポート対象外	❌ サポート対象外
`choices[].message.audio`	❌ サポート対象外	❌ サポート対象外	❌ サポート対象外
`choices[].message.function_call`	✔ サポート対象	❌ サポート対象外	❌ サポート対象外
`choices[].message.tool_calls`	✔ サポート対象	✔ `function` ツールのみ	❌ サポート対象外
`choices[].message.reasoning`	❌ サポート対象外	✔ OpenRouter 形式	❌ サポート対象外
:code:`choices[].delta`（ストリーミング）	サブフィールドを見る	サブフィールドを見る	サブフィールドを見る
`choices[].delta.content`	✔ サポート対象	✔ サポート対象	✔ サポート対象
`choices[].delta.role`	✔ サポート対象	❌ サポート対象外	❌ サポート対象外
`choices[].delta.refusal`	✔ サポート対象	❌ サポート対象外	❌ サポート対象外
`choices[].delta.function_call`	✔ サポート対象	❌ サポート対象外	❌ サポート対象外
`choices[].delta.tool_calls`	✔ サポート対象	✔ `function` ツールのみ	❌ サポート対象外
`choices[].delta.reasoning`	❌ サポート対象外	✔ OpenRouter 形式	❌ サポート対象外
`usage`	サブフィールドを見る	サブフィールドを見る	サブフィールドを見る
`usage.prompt_tokens`	✔ サポート対象	✔ サポート対象	✔ サポート対象
`usage.completion_tokens`	✔ サポート対象	✔ サポート対象	✔ サポート対象
`usage.total_tokens`	✔ サポート対象	✔ サポート対象	✔ サポート対象
`usage.prompt_tokens_details`	サブフィールドを見る	サブフィールドを見る	サブフィールドを見る
`usage.prompt_tokens_details.audio_tokens`	❌ サポート対象外	❌ サポート対象外	❌ サポート対象外
`usage.prompt_tokens_details.cached_tokens`	✔ キャッシュ読み取りのみ	✔ キャッシュ読み取り＋書き込み	❌ サポート対象外
`usage.completion_tokens_details`	サブフィールドを見る	サブフィールドを見る	サブフィールドを見る
`usage.completion_tokens_details.accepted_prediction_tokens`	✔ サポート対象	❌ サポート対象外	❌ サポート対象外
`usage.completion_tokens_details.audio_tokens`	❌ サポート対象外	❌ サポート対象外	❌ サポート対象外
`usage.completion_tokens_details.reasoning_tokens`	✔ サポート対象	❌ サポート対象外	❌ サポート対象外
`usage.completion_tokens_details.rejected_prediction_tokens`	✔ サポート対象	❌ サポート対象外	❌ サポート対象外
`service_tier`	✔ サポート対象	❌ サポート対象外	❌ サポート対象外
`system_fingerprint`	✔ サポート対象	❌ サポート対象外	❌ サポート対象外

リクエストヘッダー¶
ヘッダー	サポート
`Authorization`	✔ 必須
`Content-Type`	✔ サポート対象（`application/json`）
`Accept`	✔ サポート対象（`application/json`、`text/event-stream`）

応答のヘッダ¶
ヘッダー	サポート
`openai-organization`	❌ サポート対象外
`openai-version`	❌ サポート対象外
`openai-processing-ms`	❌ サポート対象外
`x-ratelimit-limit-requests`	❌ サポート対象外
`x-ratelimit-limit-tokens`	❌ サポート対象外
`x-ratelimit-remaining-requests`	❌ サポート対象外
`x-ratelimit-remaining-tokens`	❌ サポート対象外
`x-ratelimit-reset-requests`	❌ サポート対象外
`x-ratelimit-reset-tokens`	❌ サポート対象外
`retry-after`	❌ サポート対象外

詳細¶

使用例の完全な大要については、`OpenAI の Chat CompletionsAPI reference<https://platform.openai.com/docs/guides/completions/>`_ または `OpenAI Cookbook<https://cookbook.openai.com/>`_ を参照してください。

Chat Completions API との互換性に加え、SnowflakeはClaudeモデルのOpenRouter 互換機能をサポートしています。これらの機能はリクエストの追加フィールドとして公開されます。

プロンプトキャッシングには、cache_control フィールドを使用します。詳細については、`OpenRouter プロンプトキャッシングドキュメント<https://openrouter.ai/docs/features/prompt-caching>`_ を参照してください。
推論トークンには、reasoning フィールドを使用します。詳しくは、OpenRouter 推論ドキュメントを参照してください。