API ZDk AI Chat
Integre inteligência artificial avançada à sua aplicação com uma API REST simples, compatível com os formatos de mercado. Construída para escalar do MVP à produção.
Ambientes
A API Zedek opera em ambiente de produção. Utilize variáveis de ambiente para armazenar a URL base e sua chave, facilitando a troca entre projetos.
| Ambiente | URL Base | Observação |
|---|---|---|
| Produção | https://zedektechnology.com.br |
Único ambiente disponível |
Configuração recomendada
# .env ZEDEK_API_KEY=zdk_sua_chave_aqui ZEDEK_BASE_URL=https://zedektechnology.com.br
import os import requests BASE_URL = os.getenv("ZEDEK_BASE_URL", "https://zedektechnology.com.br") API_KEY = os.getenv("ZEDEK_API_KEY") headers = { "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json" }
// Carregue com dotenv: npm install dotenv import 'dotenv/config' const BASE_URL = process.env.ZEDEK_BASE_URL ?? 'https://zedektechnology.com.br' const API_KEY = process.env.ZEDEK_API_KEY const headers = { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' }
Autenticação
Todas as requisições requerem um API Key no header Authorization. As chaves têm o prefixo zdk_ e são geradas em Configurações → API dentro do app.
# Header obrigatório em todas as requisições Authorization: Bearer zdk_xxxxxxxxxxxxxxxxxxxx
Boas práticas de segurança
- Armazene a chave em variáveis de ambiente (
.env) — nunca em código-fonte - Gere uma chave por projeto para facilitar revogação seletiva
- Monitore o uso via
GET /v1/usagepara detectar consumo anômalo - Rotacione as chaves periodicamente em produção
- Em servidores, utilize secrets managers (AWS Secrets Manager, Vault, Railway Variables)
Quick Start — 3 minutos
Faça sua primeira chamada à API sem nenhuma dependência além do HTTP.
curl https://zedektechnology.com.br/v1/messages \ -H "Authorization: Bearer zdk_sua_chave" \ -H "Content-Type: application/json" \ -d '{ "model": "zedek-pro", "max_tokens": 1024, "messages": [ {"role": "user", "content": "Olá! O que você pode fazer?"} ] }'
import os, requests resp = requests.post( "https://zedektechnology.com.br/v1/messages", headers={ "Authorization": f"Bearer {os.getenv('ZEDEK_API_KEY')}", "Content-Type": "application/json" }, json={ "model": "zedek-pro", "max_tokens": 1024, "messages": [{"role": "user", "content": "Olá!"}] } ) print(resp.json()["content"][0]["text"])
const res = await fetch('https://zedektechnology.com.br/v1/messages', { method: 'POST', headers: { 'Authorization': `Bearer ${process.env.ZEDEK_API_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ model: 'zedek-pro', max_tokens: 1024, messages: [{ role: 'user', content: 'Olá!' }] }) }) const data = await res.json() console.log(data.content[0].text)
$ch = curl_init('https://zedektechnology.com.br/v1/messages'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . $_ENV['ZEDEK_API_KEY'], 'Content-Type: application/json' ], CURLOPT_POSTFIELDS => json_encode([ 'model' => 'zedek-pro', 'max_tokens' => 1024, 'messages' => [['role' => 'user', 'content' => 'Olá!']] ]) ]); $data = json_decode(curl_exec($ch), true); echo $data['content'][0]['text'];
Resposta
{
"id": "msg_01Xdv...",
"type": "message",
"role": "assistant",
"content": [{ "type": "text", "text": "Posso ajudar com análises, código, escrita..." }],
"model": "zedek-pro",
"stop_reason": "end_turn",
"usage": { "input_tokens": 10, "output_tokens": 87 }
}
IDE & Editores
A API Zedek é compatível com qualquer ferramenta que suporte o formato OpenAI Chat Completions. Configure seu editor favorito em segundos — basta apontar a URL base e inserir sua chave.
gpt-4o → zedek-pro, gpt-4o-mini → zedek-fast, o1/o3 → zedek-reason.VS Code — Continue
A extensão Continue é a mais popular para IA em editores. Instale via VS Code Marketplace e edite ~/.continue/config.json:
{
"models": [
{
"title": "ZDK IA Pro",
"provider": "openai",
"model": "zedek-pro",
"apiBase": "https://zedektechnology.com.br/v1",
"apiKey": "zdk_SUA_CHAVE"
},
{
"title": "ZDK IA Fast",
"provider": "openai",
"model": "zedek-fast",
"apiBase": "https://zedektechnology.com.br/v1",
"apiKey": "zdk_SUA_CHAVE"
}
],
"tabAutocompleteModel": {
"title": "ZDK Autocomplete",
"provider": "openai",
"model": "zedek-fast",
"apiBase": "https://zedektechnology.com.br/v1",
"apiKey": "zdk_SUA_CHAVE"
}
}
Cursor IDE
No Cursor, acesse Settings → Models → OpenAI API Key e configure:
| Campo | Valor |
|---|---|
| OpenAI API Key | zdk_SUA_CHAVE |
| Override API Base | https://zedektechnology.com.br/v1 |
| Model | zedek-pro (ou gpt-4o, mapeado automaticamente) |
VS Code — Cody
A extensão Cody do Sourcegraph suporta provedores OpenAI-compatíveis. Em settings.json do VS Code:
{
"cody.autocomplete.advanced.provider": "openai",
"cody.autocomplete.advanced.model": "zedek-fast",
"cody.autocomplete.advanced.serverEndpoint": "https://zedektechnology.com.br/v1",
"cody.autocomplete.advanced.accessToken": "zdk_SUA_CHAVE"
}
Qualquer extensão OpenAI-compatível
Extensões como CodeGPT, AI Assistant, Copilot alternatives e outros. Configure estas 3 informações:
| Campo | Valor |
|---|---|
| API Base URL | https://zedektechnology.com.br/v1 |
| API Key | zdk_SUA_CHAVE |
| Model | zedek-pro, zedek-fast ou zedek-reason |
export ZEDEK_API_KEY=zdk_sua_chave e referencia como $ZEDEK_API_KEY ou process.env.ZEDEK_API_KEY.Usando SDKs oficiais OpenAI
Qualquer SDK OpenAI oficial funciona apontando o base_url. Você não precisa mudar mais nada no código.
from openai import OpenAI client = OpenAI( base_url="https://zedektechnology.com.br/v1", api_key="zdk_SUA_CHAVE" ) resp = client.chat.completions.create( model="zedek-pro", messages=[{"role": "user", "content": "Crie uma API REST em FastAPI"}] ) print(resp.choices[0].message.content)
import OpenAI from "openai"; const client = new OpenAI({ baseURL: "https://zedektechnology.com.br/v1", apiKey: "zdk_SUA_CHAVE" }); const resp = await client.chat.completions.create({ model: "zedek-pro", messages: [{ role: "user", content: "Crie um componente React de login" }] }); console.log(resp.choices[0].message.content);
curl https://zedektechnology.com.br/v1/chat/completions \ -H "Authorization: Bearer zdk_SUA_CHAVE" \ -H "Content-Type: application/json" \ -d '{ "model": "zedek-pro", "messages": [{"role":"user","content":"Explique async/await"}], "stream": false }'
Modelos disponíveis
Escolha o modelo pelo perfil da tarefa. Use zedek-fast para latência mínima, zedek-pro para qualidade máxima e zedek-reason para problemas que exigem raciocínio encadeado.
Quando usar cada modelo
POST /v1/messages
Endpoint principal da Zedek API. Envia uma lista de mensagens e recebe a resposta do modelo.
Parâmetros do body (JSON)
| Campo | Tipo | Status | Descrição |
|---|---|---|---|
| model | string | REQUIRED | zedek-fast | zedek-pro | zedek-reason |
| messages | array | REQUIRED | Lista de mensagens. Cada item: {"role": "user"|"assistant", "content": "..."} |
| max_tokens | integer | REQUIRED | Máximo de tokens na resposta. Até 8.192 (fast/pro) ou 16.000 (reason) |
| system | string | OPTIONAL | System prompt personalizado. Define personalidade, escopo e regras do assistente |
| temperature | float | OPTIONAL | Criatividade. 0.0 (determinístico) a 1.0 (mais criativo). Padrão: 0.7 |
| stream | boolean | OPTIONAL | Retorna Server-Sent Events para streaming em tempo real. Padrão: false |
POST /v1/chat/completions
Interface compatível com o formato Chat Completions amplamente adotado. Ideal para migrar código existente sem alterações estruturais — basta trocar a URL base.
| Campo | Tipo | Status | Descrição |
|---|---|---|---|
| model | string | REQUIRED | zedek-fast | zedek-pro | zedek-reason |
| messages | array | REQUIRED | Array com roles system, user e assistant |
| stream | boolean | OPTIONAL | Streaming no formato padrão Chat Completions (data: [DONE]) |
import os, requests resp = requests.post( "https://zedektechnology.com.br/v1/chat/completions", headers={"Authorization": f"Bearer {os.getenv('ZEDEK_API_KEY')}", "Content-Type": "application/json"}, json={ "model": "zedek-pro", "messages": [ {"role": "system", "content": "Você é um assistente útil."}, {"role": "user", "content": "Olá!"} ] } ) print(resp.json()["choices"][0]["message"]["content"])
const res = await fetch('https://zedektechnology.com.br/v1/chat/completions', { method: 'POST', headers: { 'Authorization': `Bearer ${process.env.ZEDEK_API_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ model: 'zedek-pro', messages: [ { role: 'system', content: 'Você é um assistente útil.' }, { role: 'user', content: 'Olá!' } ] }) }) const { choices } = await res.json() console.log(choices[0].message.content)
curl https://zedektechnology.com.br/v1/chat/completions \ -H "Authorization: Bearer zdk_sua_chave" \ -H "Content-Type: application/json" \ -d '{ "model": "zedek-pro", "messages": [ {"role":"system","content":"Você é um assistente útil."}, {"role":"user","content":"Olá!"} ] }'
POST /v1/embeddings
Gera vetores numéricos que representam o significado semântico de um texto. Útil para busca por similaridade, clustering, classificação e sistemas de recomendação.
| Campo | Tipo | Status | Descrição |
|---|---|---|---|
| input | string | array | REQUIRED | Texto ou lista de textos para vetorizar (máx. 512 chars por item) |
| model | string | OPTIONAL | Use zedek-embed-v1 (padrão e único disponível) |
curl https://zedektechnology.com.br/v1/embeddings \ -H "Authorization: Bearer zdk_sua_chave" \ -H "Content-Type: application/json" \ -d '{"input": "inteligência artificial aplicada ao varejo"}' # Resposta: { "object": "list", "data": [{ "object": "embedding", "embedding": [0.023, -0.041, 0.089, ... 768 dimensões ...], "index": 0 }], "model": "zedek-embed-v1", "usage": { "prompt_tokens": 7, "total_tokens": 7 } }
GET /v1/models
Lista todos os modelos disponíveis com metadados.
curl https://zedektechnology.com.br/v1/models \
-H "Authorization: Bearer zdk_sua_chave"
GET /v1/usage
Retorna o consumo de tokens do período atual para sua API Key.
curl https://zedektechnology.com.br/v1/usage \ -H "Authorization: Bearer zdk_sua_chave" # Resposta: { "period": "2025-04", "input_tokens": 142500, "output_tokens": 87320, "total_tokens": 229820, "estimated_cost_brl": 0.347, "requests": 312 }
System Prompts
O system prompt é a instrução enviada antes da conversa. Define a personalidade, as regras e o escopo do seu assistente. É o principal mecanismo para especializar a ZDk AI Chat no seu domínio de negócio.
system (Messages API) ou como uma mensagem {"role":"system",...} (Chat Completions). Ele não aparece para o usuário final — apenas molda o comportamento.Anatomia de um bom system prompt
# Estrutura recomendada Você é [NOME DO ASSISTENTE], um assistente especializado em [DOMÍNIO] da empresa [EMPRESA]. ## Seu papel [Descreva o que o assistente faz e para quem] ## Regras de comportamento - [Regra 1 — ex: Responda sempre em português] - [Regra 2 — ex: Não forneça informações médicas definitivas] - [Regra 3 — ex: Direcione dúvidas complexas para atendimento humano] ## Escopo Você auxilia com: [lista do que pode responder] Você NÃO responde sobre: [lista do que está fora do escopo] ## Tom de voz [Formal/informal, empático, técnico, etc.] ## Contexto da empresa [Dados relevantes: produtos, políticas, horários, contatos]
Exemplos por segmento
Você é a assistente virtual da Loja XYZ, especializada em moda feminina.
Ajude clientes com: rastreamento de pedidos, trocas e devoluções,
tamanhos e disponibilidade, formas de pagamento e prazo de entrega.
Regras:
- Seja simpática e use linguagem descontraída
- Para pedidos acima de 7 dias sem atualização, oriente abrir chamado
- Não confirme cancelamentos — encaminhe para atendimento humano
- Prazo de entrega padrão: 5-10 dias úteis para todo o Brasil
Política de troca: até 30 dias após recebimento, produto sem uso.
Você é um assistente jurídico informativo do Escritório ABC.
Forneça orientações gerais sobre direito do consumidor, trabalhista
e civil. Explique conceitos, prazos legais e procedimentos.
Regras obrigatórias:
- Sempre informe que suas respostas são informativas, não constituem
parecer jurídico e não substituem consulta com advogado
- Não opine sobre casos específicos sem os documentos completos
- Para urgências (prisão, liminar), oriente contato imediato
- Use linguagem acessível, evite jargão técnico excessivo
Você é o assistente digital da Clínica Saúde Total.
Auxilie pacientes com: agendamento de consultas, informações sobre
especialidades, preparo para exames e dúvidas gerais de saúde.
Regras absolutas:
- NUNCA forneça diagnósticos ou prescrições
- Para sintomas graves (dor no peito, falta de ar, AVC), oriente
IMEDIATAMENTE o SAMU (192) ou UPA mais próxima
- Informações sobre medicamentos: apenas orientações gerais de bula
- Sempre reforce que apenas o médico pode diagnosticar e prescrever
Você é o assistente de RH da Empresa Beta, chamado "Beta Assist".
Apoie colaboradores com: políticas internas, benefícios, férias,
contracheque, treinamentos disponíveis e processos de onboarding.
Dados da empresa:
- Benefícios: VR R$35/dia, VT, plano de saúde Amil, gympass
- Férias: solicitação pelo portal RH com 30 dias de antecedência
- Folha: fechamento dia 25, pagamento dia 5 do mês seguinte
Encaminhe ao RH humano: demissões, assédio, conflitos, promoções.
Boas práticas
- Seja específico sobre o que o assistente pode e não pode fazer
- Inclua dados concretos (preços, prazos, políticas) diretamente no prompt
- Use temperature baixa (0.2–0.4) para assistentes que precisam de respostas consistentes
- Tokens do system prompt são cobrados em cada requisição — mantenha-o conciso
- Versione seus system prompts como código (git) para rastrear mudanças de comportamento
Gestão de Contexto
A API Zedek é stateless — ela não armazena o histórico da conversa. Cada requisição deve incluir todo o histórico relevante no array messages.
Padrão de conversa multi-turno
import os, requests history = [] # mantém o histórico da sessão def chat(user_message): history.append({"role": "user", "content": user_message}) resp = requests.post( "https://zedektechnology.com.br/v1/messages", headers={"Authorization": f"Bearer {os.getenv('ZEDEK_API_KEY')}", "Content-Type": "application/json"}, json={"model": "zedek-pro", "max_tokens": 1024, "system": "Você é um assistente prestativo.", "messages": history} ) assistant_reply = resp.json()["content"][0]["text"] history.append({"role": "assistant", "content": assistant_reply}) return assistant_reply print(chat("Meu nome é João.")) print(chat("Qual é o meu nome?")) # → "João"
const history = [] async function chat(userMessage) { history.push({ role: 'user', content: userMessage }) const res = await fetch('https://zedektechnology.com.br/v1/messages', { method: 'POST', headers: { 'Authorization': `Bearer ${process.env.ZEDEK_API_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ model: 'zedek-pro', max_tokens: 1024, system: 'Você é um assistente prestativo.', messages: history }) }) const { content } = await res.json() const reply = content[0].text history.push({ role: 'assistant', content: reply }) return reply }
Estratégia de truncamento
Com contexto de 128k tokens, conversas longas podem ultrapassar o limite. Estratégias recomendadas:
- Janela deslizante: mantenha as últimas N mensagens (ex: 20 turnos)
- Resumo periódico: a cada 10 turnos, peça ao modelo um resumo da conversa e substitua o histórico antigo pelo resumo
- Embeddings + RAG: armazene o histórico como vetores e recupere apenas o trecho relevante para cada pergunta
usage na resposta informa exatamente quantos tokens foram consumidos. Monitore-o para detectar quando o histórico precisa ser truncado antes de atingir o limite.Streaming SSE
Ative com "stream": true. Os tokens chegam em tempo real via Server-Sent Events, reduzindo o tempo percebido de resposta — essencial para chatbots e interfaces conversacionais.
import os, requests, json with requests.post( "https://zedektechnology.com.br/v1/messages", headers={"Authorization": f"Bearer {os.getenv('ZEDEK_API_KEY')}", "Content-Type": "application/json"}, json={"model": "zedek-pro", "max_tokens": 1024, "stream": True, "messages": [{"role": "user", "content": "Escreva um haiku sobre o Brasil"}]}, stream=True ) as resp: for line in resp.iter_lines(): if line.startswith(b"data:"): chunk = line[5:].strip() if chunk and chunk != b"[DONE]": data = json.loads(chunk) if data.get("type") == "content_block_delta": print(data["delta"].get("text", ""), end="", flush=True)
const res = await fetch('https://zedektechnology.com.br/v1/messages', { method: 'POST', headers: { 'Authorization': `Bearer ${process.env.ZEDEK_API_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ model: 'zedek-pro', max_tokens: 1024, stream: true, messages: [{ role: 'user', content: 'Escreva um haiku sobre o Brasil' }] }) }) const reader = res.body.getReader() const decoder = new TextDecoder() while (true) { const { done, value } = await reader.read() if (done) break const lines = decoder.decode(value).split('\n') for (const line of lines) { if (!line.startsWith('data:')) continue const chunk = line.slice(5).trim() if (!chunk || chunk === '[DONE]') continue const data = JSON.parse(chunk) if (data.type === 'content_block_delta') process.stdout.write(data.delta?.text ?? '') } }
// Streaming no navegador via fetch + ReadableStream async function streamChat(userMessage, onChunk) { const res = await fetch('/v1/messages', { // use seu proxy backend method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ model: 'zedek-pro', max_tokens: 1024, stream: true, messages: [{ role: 'user', content: userMessage }] }) }) const reader = res.body.getReader() const dec = new TextDecoder() while (true) { const { done, value } = await reader.read() if (done) break dec.decode(value).split('\n').forEach(line => { if (!line.startsWith('data:')) return try { const d = JSON.parse(line.slice(5)) if (d.type === 'content_block_delta') onChunk(d.delta?.text ?? '') } catch {} }) } } // Uso: streamChat("Olá!", text => document.getElementById('output').textContent += text)
curl https://zedektechnology.com.br/v1/messages \ -H "Authorization: Bearer zdk_sua_chave" \ -H "Content-Type: application/json" \ --no-buffer \ -d '{"model":"zedek-pro","max_tokens":512,"stream":true, "messages":[{"role":"user","content":"Olá!"}]}' # Eventos SSE recebidos: data: {"type":"content_block_delta","delta":{"type":"text_delta","text":"Olá"}} data: {"type":"content_block_delta","delta":{"type":"text_delta","text":"!"}} data: {"type":"message_stop"}
Contagem de Tokens
A cobrança é por tokens consumidos. Entender o que é um token ajuda a otimizar custos e evitar atingir limites de contexto.
O que é um token?
Tokens são fragmentos de texto — aproximadamente 4 caracteres em inglês ou 3–4 caracteres em português. Palavras comuns são geralmente 1 token; palavras longas ou raras podem ser 2–4 tokens.
Dicas para reduzir custos
- Use
zedek-fastpara tarefas simples — mesmo preço de input, menor latência - Limite
max_tokensao mínimo necessário para sua tarefa - Mantenha o system prompt enxuto — é cobrado em cada requisição
- Em batches de classificação, agrupe múltiplos itens em uma única chamada
- Monitore via
GET /v1/usagepara detectar consumo inesperado
Monitorando em tempo real
Toda resposta da API inclui o campo usage com os tokens consumidos naquela chamada:
# Python — lendo usage da resposta data = resp.json() usage = data["usage"] print(f"Input: {usage['input_tokens']} | Output: {usage['output_tokens']}")
Casos de Uso
A API Zedek é agnóstica de domínio — funciona para qualquer tipo de negócio ou aplicação. Explore os padrões mais comuns:
Rate Limits
Limites aplicados por API Key. Os headers X-RateLimit-* estão presentes em todas as respostas.
Limites da Zedek API
Headers de resposta
X-RateLimit-Limit: 60 X-RateLimit-Remaining: 58 X-RateLimit-Reset: 1714500060 # Unix timestamp do próximo reset
Retry com backoff exponencial
import time, requests def post_with_retry(url, headers, payload, retries=3): for attempt in range(retries): r = requests.post(url, headers=headers, json=payload) if r.status_code == 429: if attempt == retries - 1: raise Exception("Rate limit persistente") time.sleep(2 ** attempt) # 1s, 2s, 4s else: r.raise_for_status() return r.json()
async function postWithRetry(url, headers, body, retries = 3) { for (let i = 0; i < retries; i++) { const res = await fetch(url, { method: 'POST', headers, body: JSON.stringify(body) }) if (res.status === 429) { if (i === retries - 1) throw new Error('Rate limit persistente') await new Promise(r => setTimeout(r, 1000 * 2 ** i)) } else { if (!res.ok) throw new Error(`HTTP ${res.status}`) return res.json() } } }
Códigos de Erro
Erros retornam JSON com o campo error descritivo.
error na resposta.Authorization.X-RateLimit-Reset.Formato do erro
{
"error": "rate_limit_exceeded",
"message": "Limite de 60 requisições/minuto atingido.",
"retry_after": 23
}
SDKs & Integrações
A API Zedek usa formatos HTTP padrão de mercado — qualquer biblioteca HTTP funciona. Ela também é compatível com SDKs populares de IA, bastando configurar a URL base.
# Python pip install requests // Node.js — fetch nativo (Node 18+) // PHP — curl nativo // Go — net/http nativo
base_url — zero mudanças no códigopip install openai
npm install openai
# Configure: base_url = zedektechnology.com.br/v1Integração com frameworks de IA
A API Zedek é compatível com qualquer framework que suporte o formato Chat Completions via URL customizável. Configure a URL base e a chave nas variáveis de ambiente do framework.
https://zedektechnology.com.br/v1 e a api_key para sua chave zdk_. Nenhuma outra mudança é necessária.Changelog
Histórico de atualizações da API Zedek. Versões seguem Semantic Versioning.
- NEW Modelo
zedek-reasoncom raciocínio encadeado disponível - NEW Endpoint
POST /v1/embeddingscom vetores multilíngues de 768 dimensões - NEW Endpoint
GET /v1/usagepara monitoramento de consumo por API key - FIX Streaming SSE: tokens finais não eram emitidos em respostas longas
- NEW Suporte ao formato Chat Completions via
/v1/chat/completions - NEW Headers
X-RateLimit-*em todas as respostas - FIX Contexto de 128k tokens corretamente honrado no
zedek-pro
- NEW Parâmetro
temperaturedisponível em todos os endpoints - NEW
GET /v1/modelscom metadados de preço e contexto - FIX Latência de streaming reduzida em 40% no
zedek-fast
- NEW Lançamento da API Zedek com
POST /v1/messages - NEW Modelos
zedek-fastezedek-pro - NEW Streaming SSE nativo
- NEW Autenticação via API Key com prefixo
zdk_