API Cortex Chat Completions¶

A API Cortex Chat Completions é um superconjunto independente de modelo da API OpenAI Chat Completions, permitindo compatibilidade com um vasta ecossistema de ferramentas, bibliotecas e aplicativos de AI de terceiros.

A API Cortex Chat Completions é uma API complementar à API REST do Cortex, com maior suporte para modelos OpenAI. Para saber mais sobre a API REST do Cortex, consulte Cortex REST API.

Introdução ao OpenAI SDK¶

Importante

Certifique-se de que você está usando uma versão oficial do OpenAI SDK conforme especificado na documentação das bibliotecas do OpenAI, como em uma das seguintes linguagens:

Python
TypeScript/JavaScript

Para começar, você precisa de:

URL da sua conta Snowflake. Ele será usado para construir o URL básico para o cliente OpenAI.
Um token de acesso programático do Snowflake (PAT). Ele será usado para autenticar na API Cortex Chat Completions. Para obter mais informações sobre a criação de um PAT, consulte Geração de um token de acesso programático.
Um nome de modelo válido a ser usado na solicitação. Para obter uma lista de modelos compatíveis, consulte Disponibilidade do modelo.

Exemplos de código simples¶

Os exemplos a seguir mostram como fazer solicitações a OpenAI SDKs com Python, JavaScript/TypeScript e curl.

Use o código a seguir para começar com o Python SDK:

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

No código anterior, especifique valores para o seguinte:

base_url: Substitua <account-identifier> pelo identificador da sua conta Snowflake.
api_key: Substitua <SNOWFLAKE_PAT> pelo seu token de acesso programático do Snowflake (PAT).
model: Substitua <model_name> pelo nome do modelo que você deseja usar. Para obter uma lista de modelos compatíveis, consulte Disponibilidade do modelo.

Use o código a seguir para começar a usar o 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

No código anterior, especifique valores para o seguinte:

baseURL: Substitua <account-identifier> pelo identificador da sua conta Snowflake.
apikey: Substitua SNOWFLAKE_PAT pelo seu token de acesso pessoal (PAT) do Snowflake.
model: Substitua <model_name> pelo nome do modelo que você deseja usar. Para obter uma lista de modelos compatíveis, consulte Disponibilidade do modelo.

Use o seguinte comando curl para fazer uma solicitação ao modelo hospedado no 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

No código anterior, especifique valores para o seguinte:

<account-identifier>: Substitua <account-identifier> pelo identificador da sua conta Snowflake.
<SNOWFLAKE_PAT>: Substitua <SNOWFLAKE_PAT> pelo seu token de acesso pessoal (PAT) do Snowflake.
<model_name>: Substitua <model_name> pelo nome do modelo que você deseja usar. Para obter uma lista de modelos compatíveis, consulte Disponibilidade do modelo.

Respostas do fluxo¶

Você pode transmitir respostas da API REST definindo o parâmetro stream para True na solicitação.

O seguinte código Python transmite uma resposta da API REST:

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

O seguinte código JavaScript/TypeScript transmite uma resposta da API REST:

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

O seguinte comando curl transmite uma resposta do modelo hospedado no 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

Limitações¶

Os itens a seguir são as limitações no uso do OpenAI SDK com modelos hospedados pelo Snowflake:

Somente conclusões de bate-papo são compatíveis.
Se não for definido, max_completion_tokens assume o padrão de 4096. O máximo teórico para a API Cortex Chat Completions é 131.072. Cada modelo tem seus próprios limites de token de saída que podem ser inferiores a 131.072.
A chamada de ferramenta é compatível com modelos do OpenAI e do Claude. Para um exemplo que usa a chamada de ferramenta de forma eficaz, consulte Chamada de ferramenta com exemplo de cadeia de pensamento.
Não há suporte para áudio.
A compreensão da imagem é compatível somente com modelos do OpenAI e do Claude. As imagens são limitadas a 20 por conversação com um de tamanho máximo de solicitação de 20 MiB.
Somente os modelos do Claude oferecem suporte a pontos de controle de cache efêmeros para cache de prompt. Os modelos do OpenAI oferecem suporte ao cache implícito.
Somente os modelos Claude oferecem suporte ao retorno de seus detalhes de raciocínio na resposta.
As mensagens de erro são geradas pelo Snowflake, não pelo OpenAI. Recomenda-se usar os erros relatados apenas para fins de registro e depuração.

Tabela de compatibilidade detalhada¶

As tabelas a seguir resumem quais campos de solicitação e resposta e cabeçalhos são suportados ao usar a API Cortex Chat Completions com diferentes modelos hospedados pelo Snowflake.

Campos da solicitação¶
Campo	Modelos do OpenAI	Modelos do Claude	Outros modelos
`model`	Suporte para ✔	Suporte para ✔	Suporte para ✔
`messages`	Consulte os subcampos	Consulte os subcampos	Consulte os subcampos
`messages[].audio`	❌ Erro	❌ Ignorado	❌ Ignorado
`messages[].role`	Suporte para ✔	✔ Somente usuário/assistente/sistema	✔ Somente usuário/assistente/sistema
`messages[].content` (string)	Suporte para ✔	Suporte para ✔	Suporte para ✔
`messages[].content[]` (matriz)	Consulte os subcampos	Consulte os subcampos	Consulte os subcampos
`messages[].content[].text`	Suporte para ✔	Suporte para ✔	Suporte para ✔
`messages[].content[].type`	Suporte para ✔	Suporte para ✔	Suporte para ✔
`messages[].content[].image_url`	Suporte para ✔	Suporte para ✔	❌ Erro
`messages[].content[].cache_control`	❌ Ignorado	✔ Compatível (somente efêmero)	❌ Ignorado
`messages[].content[].file`	❌ Erro	❌ Erro	❌ Ignorado
`messages[].content[].input_audio`	❌ Erro	❌ Ignorado	❌ Ignorado
`messages[].content[].refusal`	Suporte para ✔	❌ Ignorado	❌ Ignorado
`messages[].function_call`	✔ Compatível (obsoleto)	❌ Ignorado	❌ Ignorado
`messages[].name`	Suporte para ✔	❌ Ignorado	❌ Ignorado
`messages[].refusal`	Suporte para ✔	❌ Ignorado	❌ Ignorado
`messages[].tool_call_id`	Suporte para ✔	Suporte para ✔	❌ Ignorado
`messages[].tool_calls`	Suporte para ✔	✔ Somente ferramentas `function`	❌ Ignorado
`messages[].reasoning_details`	❌ Ignorado	✔ Formato OpenRouter `reasoning.text`	❌ Ignorado
`audio`	❌ Erro	❌ Ignorado	❌ Ignorado
`frequency_penalty`	Suporte para ✔	❌ Ignorado	❌ Ignorado
`logit_bias`	Suporte para ✔	❌ Ignorado	❌ Ignorado
`logprobs`	Suporte para ✔	❌ Ignorado	❌ Ignorado
`max_tokens`	❌ Erro (obsoleto)	❌ Erro (obsoleto)	❌ Erro (obsoleto)
`max_completion_tokens`	✔ Compatível (4096 padrão, 131072 máximo)	✔ Compatível (4096 padrão, 131072 máximo)	✔ Compatível (4096 padrão, 131072 máximo)
`metadata`	❌ Ignorado	❌ Ignorado	❌ Ignorado
`modalities`	❌ Ignorado	❌ Ignorado	❌ Ignorado
`n`	Suporte para ✔	❌ Ignorado	❌ Ignorado
`parallel_tool_calls`	Suporte para ✔	❌ Ignorado	❌ Ignorado
`prediction`	Suporte para ✔	❌ Ignorado	❌ Ignorado
`presence_penalty`	Suporte para ✔	❌ Ignorado	❌ Ignorado
`prompt_cache_key`	Suporte para ✔	❌ Ignorado	❌ Ignorado
`reasoning_effort`	Suporte para ✔	❌ Ignorado (usar o objeto `reasoning`)	❌ Ignorado
`reasoning`	Consulte os subcampos	Consulte os subcampos	Consulte os subcampos
`reasoning.effort`	✔ Compatível (substitui `reasoning_effort`)	✔ Convertido em `reasoning.max_tokens`	❌ Ignorado
`reasoning.max_tokens`	❌ Ignorado	Suporte para ✔	❌ Ignorado
`response_format`	Suporte para ✔	✔ Only `json_schema`	❌ Ignorado
`safety_identifier`	❌ Ignorado	❌ Ignorado	❌ Ignorado
`service_tier`	❌ Erro	❌ Erro	❌ Erro
`stop`	Suporte para ✔	❌ Ignorado	❌ Ignorado
`store`	❌ Erro	❌ Erro	❌ Erro
`stream`	Suporte para ✔	Suporte para ✔	Suporte para ✔
`stream_options`	Consulte os subcampos	Consulte os subcampos	Consulte os subcampos
`stream_options.include_obfuscation`	❌ Ignorado	❌ Ignorado	❌ Ignorado
`stream_options.include_usage`	Suporte para ✔	Suporte para ✔	Suporte para ✔
`temperature`	Suporte para ✔	Suporte para ✔	Suporte para ✔
`tool_choice`	Suporte para ✔	✔ Somente ferramentas `function`	❌ Ignorado
`tools`	Suporte para ✔	✔ Somente ferramentas `function`	❌ Erro
`top_logprobs`	Suporte para ✔	❌ Ignorado	❌ Ignorado
`top_p`	Suporte para ✔	Suporte para ✔	Suporte para ✔
`verbosity`	Suporte para ✔	❌ Ignorado	❌ Ignorado
`web_search_options`	❌ Erro	❌ Ignorado	❌ Ignorado

Campos de resposta:¶
Campo	Modelos do OpenAI	Modelos do Claude	Outros modelos
`id`	Suporte para ✔	Suporte para ✔	Suporte para ✔
`object`	Suporte para ✔	Suporte para ✔	Suporte para ✔
`created`	Suporte para ✔	Suporte para ✔	Suporte para ✔
`model`	Suporte para ✔	Suporte para ✔	Suporte para ✔
`choices`	Consulte os subcampos	Consulte os subcampos	Consulte os subcampos
`choices[].index`	Suporte para ✔	✔ Somente escolha única	✔ Somente escolha única
`choices[].finish_reason`	Suporte para ✔	❌ Sem suporte	✔ Somente `stop`
`choices[].logprobs`	Suporte para ✔	❌ Sem suporte	❌ Sem suporte
`choices[].message` (sem streaming)	Consulte os subcampos	Consulte os subcampos	Consulte os subcampos
`choices[].message.content`	Suporte para ✔	Suporte para ✔	Suporte para ✔
`choices[].message.role`	Suporte para ✔	Suporte para ✔	Suporte para ✔
`choices[].message.refusal`	Suporte para ✔	❌ Sem suporte	❌ Sem suporte
`choices[].message.annotations`	❌ Sem suporte	❌ Sem suporte	❌ Sem suporte
`choices[].message.audio`	❌ Sem suporte	❌ Sem suporte	❌ Sem suporte
`choices[].message.function_call`	Suporte para ✔	❌ Sem suporte	❌ Sem suporte
`choices[].message.tool_calls`	Suporte para ✔	✔ Somente ferramentas `function`	❌ Sem suporte
`choices[].message.reasoning`	❌ Sem suporte	✔ Formato OpenRouter	❌ Sem suporte
`choices[].delta` (streaming)	Consulte os subcampos	Consulte os subcampos	Consulte os subcampos
`choices[].delta.content`	Suporte para ✔	Suporte para ✔	Suporte para ✔
`choices[].delta.role`	Suporte para ✔	❌ Sem suporte	❌ Sem suporte
`choices[].delta.refusal`	Suporte para ✔	❌ Sem suporte	❌ Sem suporte
`choices[].delta.function_call`	Suporte para ✔	❌ Sem suporte	❌ Sem suporte
`choices[].delta.tool_calls`	Suporte para ✔	✔ Somente ferramentas `function`	❌ Sem suporte
`choices[].delta.reasoning`	❌ Sem suporte	✔ Formato OpenRouter	❌ Sem suporte
`usage`	Consulte os subcampos	Consulte os subcampos	Consulte os subcampos
`usage.prompt_tokens`	Suporte para ✔	Suporte para ✔	Suporte para ✔
`usage.completion_tokens`	Suporte para ✔	Suporte para ✔	Suporte para ✔
`usage.total_tokens`	Suporte para ✔	Suporte para ✔	Suporte para ✔
`usage.prompt_tokens_details`	Consulte os subcampos	Consulte os subcampos	Consulte os subcampos
`usage.prompt_tokens_details.audio_tokens`	❌ Sem suporte	❌ Sem suporte	❌ Sem suporte
`usage.prompt_tokens_details.cached_tokens`	✔ Somente leituras de cache	✔ Leitura + gravação de cache	❌ Sem suporte
`usage.completion_tokens_details`	Consulte os subcampos	Consulte os subcampos	Consulte os subcampos
`usage.completion_tokens_details.accepted_prediction_tokens`	Suporte para ✔	❌ Sem suporte	❌ Sem suporte
`usage.completion_tokens_details.audio_tokens`	❌ Sem suporte	❌ Sem suporte	❌ Sem suporte
`usage.completion_tokens_details.reasoning_tokens`	Suporte para ✔	❌ Sem suporte	❌ Sem suporte
`usage.completion_tokens_details.rejected_prediction_tokens`	Suporte para ✔	❌ Sem suporte	❌ Sem suporte
`service_tier`	Suporte para ✔	❌ Sem suporte	❌ Sem suporte
`system_fingerprint`	Suporte para ✔	❌ Sem suporte	❌ Sem suporte

Cabeçalhos de solicitação¶
Cabeçalho	Suporte
`Authorization`	✔ Obrigatório
`Content-Type`	✔ Compatível (`application/json`)
`Accept`	✔ Compatível (`application/json`, `text/event-stream`)

Cabeçalhos de resposta¶
Cabeçalho	Suporte
`openai-organization`	❌ Sem suporte
`openai-version`	❌ Sem suporte
`openai-processing-ms`	❌ Sem suporte
`x-ratelimit-limit-requests`	❌ Sem suporte
`x-ratelimit-limit-tokens`	❌ Sem suporte
`x-ratelimit-remaining-requests`	❌ Sem suporte
`x-ratelimit-remaining-tokens`	❌ Sem suporte
`x-ratelimit-reset-requests`	❌ Sem suporte
`x-ratelimit-reset-tokens`	❌ Sem suporte
`retry-after`	❌ Sem suporte

Saiba mais¶

Para obter um compêndio completo de exemplos de uso, consulte a referência da API Chat Completions do OpenAI ou o OpenAI Cookbook.

Além de oferecer compatibilidade com a API Chat Completions, o Snowflake oferece suporte a recursos compatíveis com OpenRouter para modelos do Claude. Esses recursos são expostos como campos extras na solicitação.

Para cache de prompt, use o campo cache_control. Consulte a documentação sobre armazenamento de prompts em cache do OpenRouter para obter mais informações.
Para tokens de raciocínio, use o campo reasoning. Consulte a documentação sobre raciocínio do OpenRouter para obter mais informações.