Guia de Integração da API DeepSeek: Requisitos OpenAI Compatíveis através do ECAIX

Este guia mostra como testar um ID de modelo DeepSeek através do ECAIX usando um endpoint compatível com a API OpenAI. Abrange o menor pedido de trabalho, exemplos em Python e curl, verificação de IDs de modelos, streaming, saída estruturada, ferramentas e um caminho diagnóstico para erros comuns.

O guia descreve o acesso ao gateway ECAIX para um ID de modelo exposto no catálogo atualizado no ECAIX. Não se afirma que o ECAIX seja o endpoint oficial da API DeepSeek ou que todas as funcionalidades da DeepSeek estejam disponíveis através de todas as rotas do gateway. Verifique a página do modelo vivo e a documentação do provedor antes de mover uma carga de trabalho para produção.

Início Rápido

Use esta sequência se já tiver uma aplicação com SDK OpenAI:

1. Abra a página do modelo DeepSeek v4.1 Flash e confirme que o ID está disponível.
2. Crie uma chave de API ECAIX.
3. Defina a URL base compatível com OpenAI em https://ecaix.com/api/ai/v1.
4. Mantenha o SDK e o código da aplicação inalterados, sempre que possível.
5. Execute o pedido mínimo abaixo.
6. Adicione streaming, saída JSON ou ferramentas apenas após o pedido básico funcionar.

Endpoint e ID do Modelo

Para clientes compatíveis com OpenAI, use:

Base URL: https://ecaix.com/api/ai/v1
Model:    deepseek-v4.1-flash

O ID do modelo não é uma promessa permanente em um artigo de blog. Confirme-o na diretório de modelos vivos antes de cada nova integração ou implantação. Se precisar de um membro diferente da família DeepSeek, copie o ID exato da página de detalhes do modelo em vez de adivinhar um sufixo.

O formato do endpoint também é importante. O SDK deve receber o caminho base terminando em /v1; o cliente adiciona /chat/completions ou outro caminho de operação. Não adicione /chat/completions ao base_url quando o SDK já o adiciona.

Python com o SDK OpenAI

Instale ou atualize o SDK Python OpenAI em seu ambiente virtual:

python -m pip install --upgrade openai

Em seguida, use a URL base ECAIX e a chave de API:

const client = new OpenAI({
  apiKey: process.env.ECAIX_API_KEY,
  baseURL: "https://ecaix.com/api/ai/v1",
});

const response = await client.chat.completions.create({
  model: "deepseek-v4.1-flash",
  messages: [
    { role: "user", content: "Return one short sentence about API testing." },
  ],
  max_tokens: 128,
});

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

Use código servidor para o pedido da API. Uma aplicação do navegador deve chamar seu próprio backend em vez de expor uma chave ECAIX em código JavaScript do lado do cliente.

Pedido Diagnóstico com curl

Se o SDK falhar, retire o SDK da equação e teste o endpoint diretamente. Salve os cabeçalhos e o corpo separadamente para distinguir um problema HTTP de um problema de formato de resposta.

curl -sS -D /tmp/ecaix-deepseek-headers.txt \
  -o /tmp/ecaix-deepseek-response.json \
  -w '\nHTTP %{http_code}\n' \
  "https://ecaix.com/api/ai/v1/chat/completions" \
  -H "Authorization: Bearer ${ECAIX_API_KEY}" \
  -H "content-type: application/json" \
  -d '{
    "model": "deepseek-v4.1-flash",
    "messages": [
      {"role": "user", "content": "Reply with one short sentence."}
    ],
    "max_tokens": 128
  }'

Não cole os cabeçalhos salvos ou a resposta em um problema público sem remover chaves de API, IDs de pedido, prompts, caminhos de repositório e dados de clientes.

Como diagnosticar a resposta

Use a seguinte ordem:

1. Código de status HTTP: determine se o pedido chegou a um endpoint válido.
2. Corpo da resposta: leia o código de erro do provedor ou gateway.
3. ID do modelo: copie o ID exato do diretório atual do modelo.
4. Autenticação: verifique o cabeçalho da chave, conta e permissões.
5. Formato do pedido: reduza o corpo para model, messages e um limite mínimo de saída.
6. Campos de funcionalidade: adicione streaming, JSON ou ferramentas um de cada vez.
7. Comportamento do SDK: compare o pedido do SDK com o pedido direto via curl.

Isso evita que um problema de biblioteca do cliente seja confundido com roteamento de modelo ou permissões de conta.

Respostas em Streaming

Se a aplicação precisar de saída incremental, adicione o streaming apenas após um pedido normal funcionar:

stream = client.chat.completions.create(
    model="deepseek-v4.1-flash",
    messages=[{"role": "user", "content": "Summarize API retries in three points."}],
    stream=True,
    max_tokens=256,
)

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

O comportamento exato dos eventos depende do endpoint e do SDK. Verifique como seu quadro de trabalho lida com um delta vazio, um evento final de uso, interrupção de conexão e término de estilo [DONE]. Não considere uma implementação de streaming pronta para produção até ter testado desconectamentos e retries.

Saída Estruturada e JSON

Se precisar de saída legível por máquina, comece com um pedido normal e depois adicione a opção mais simples de saída estruturada suportada pelo endpoint e pelo modelo. Valide o conteúdo retornado com um parser JSON real. Um prompt que diz "retorne JSON" não é o mesmo que uma resposta com esquema obrigatório.

import json

response = client.chat.completions.create(
    model="deepseek-v4.1-flash",
    messages=[
        {
            "role": "user",
            "content": "Return a JSON object with keys title and priority."
        }
    ],
    response_format={"type": "json_object"},
    max_tokens=128,
)

payload = json.loads(response.choices[0].message.content)
print(payload["title"])

Se response_format for aceito depende do modelo e da rota. Se o endpoint retornar um erro de parâmetro não suportado, remova o campo e verifique a documentação da rota antes de tentar outro formato.

Chamadas de Função e Ferramentas

A chamada de ferramentas precisa de um teste separado da geração de texto. Comece com uma função inofensiva e inspecione o nome retornado e os argumentos antes de executar qualquer coisa.

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_demo_status",
            "description": "Return a fixed status for a local compatibility test.",
            "parameters": {
                "type": "object",
                "properties": {},
                "additionalProperties": False,
            },
        },
    }
]

response = client.chat.completions.create(
    model="deepseek-v4.1-flash",
    messages=[{"role": "user", "content": "Check the demo status."}],
    tools=tools,
    tool_choice="auto",
    max_tokens=128,
)

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

Um modelo pode retornar uma resposta de texto válida enquanto a chamada de ferramentas falha devido à conversão de esquema, parâmetros não suportados ou comportamento específico do cliente. Nunca execute argumentos de ferramentas retornados em um sistema de produção sem validar o esquema e adicionar controles de autorização.

Caminhos compatíveis com OpenAI e Anthropic

O ECAIX expõe diferentes superfícies de compatibilidade para diferentes clientes:

Leia a documentação de Chat Completions, Respostas e Mensagens de Anthropic antes de escolher um caminho. O mesmo ID de modelo pode não expor campos ou comportamento idênticos em cada superfície de compatibilidade.

Detalhes Atuais do Modelo

Use as páginas de detalhes vivas para verificar capacidades e disponibilidade:

• DeepSeek v4.1 Flash
• DeepSeek v4 Pro 202606
• Qwen 3.8 Flash
• GLM 5.3

Estas páginas são mais confiáveis do que um artigo estático para IDs de modelos atuais, informações de contexto e links de preços.

Erros Comuns

Checklist de Segurança e Produção

Antes de passar para além de um projeto de teste, confirme:

• Chaves de API são armazenadas no lado servidor e podem ser rotadas.
• Prompts e respostas não contêm segredos não aprovados ou dados de clientes.
• Entende se o gateway registra pedidos e por quanto tempo os logs são mantidos.
• A disponibilidade e preços dos modelos foram verificados nas páginas vivas.
• Timeout, retries, idempotência e limites de taxa são manejados pela sua aplicação.
• Desconexões de streaming não criam jobs duplicados.
• Chamadas de ferramentas têm listas brancas, validação, autorização e logs de auditoria.
• Termos do provedor e gateway permitem a carga de trabalho que planeja enviar.

Registre a integração antes da liberação

Anote a data, versão do cliente, ID do modelo, endpoint, código de status HTTP e as funcionalidades de teste que realmente executou. Se um teste não foi realizado, marque-o como não verificado. Este registro facilita a comparação com a próxima atualização de modelo ou gateway e evita que um exemplo de blog antigo se torne uma suposição não suportada para produção.

Perguntas Frequentes

É o ECAIX o endpoint oficial da API DeepSeek?

Não. Este artigo documenta o acesso ao gateway ECAIX para um ID de modelo exposto no catálogo ECAIX. Use a documentação oficial da API DeepSeek para o endpoint nativo da DeepSeek, regras de conta e capacidades específicas do provedor.

Posso usar o SDK OpenAI sem reescrever minha aplicação?

Muitas aplicações com SDK OpenAI podem começar alterando apenas a URL base, a chave de API e o ID do modelo. Ainda é necessário testar suporte a campos, streaming, chamadas de ferramentas, formatos de