Documentação da API

Introdução

A API da Zubnet oferece acesso programático a 408 modelos de IA para geração de texto, imagem, vídeo, música, voz e código. É totalmente compatível com a especificação da API OpenAI — se você já usa a OpenAI, pode mudar para a Zubnet alterando sua URL base e chave de API.

URL Base

https://api.zubnet.com/v1

Início Rápido

# Using curl
curl https://api.zubnet.com/v1/chat/completions \
  -H "Authorization: Bearer $ZUBNET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

# Using Python with OpenAI SDK
from openai import OpenAI

client = OpenAI(
    api_key="your-zubnet-api-key",
    base_url="https://api.zubnet.com/v1"
)

response = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "Hello!"}]
)

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

Autenticação

Todas as requisições da API exigem autenticação via token Bearer no cabeçalho Authorization.

Authorization: Bearer YOUR_API_KEY

Você pode gerar chaves de API nas suas configurações da conta. Mantenha suas chaves seguras — elas concedem acesso total à sua conta.

Usando Suas Próprias Chaves de Provedor (BYOK)

Você pode usar suas próprias chaves de API de provedores compatíveis. Adicione-as nas configurações do seu espaço de trabalho e elas serão usadas automaticamente para requisições a esses provedores — sem custo adicional. BYOK está disponível nos planos que o suportam.

Quando uma chave BYOK está configurada para um provedor, ela tem prioridade sobre a chave da plataforma. Nenhuma alteração é necessária nas suas requisições de API — a resolução da chave é totalmente transparente.

Provedores BYOK Compatíveis

Modelos

Lista todos os modelos disponíveis.

curl https://api.zubnet.com/v1/models \
  -H "Authorization: Bearer $ZUBNET_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "claude-sonnet-5",
      "object": "model",
      "created": 1699900000,
      "owned_by": "anthropic"
    },
    {
      "id": "deepseek-chat",
      "object": "model",
      "created": 1699900000,
      "owned_by": "deepseek"
    },
    ...
  ]
}

Completions de Chat

Crie uma completion de chat. Este é o endpoint principal para geração de texto, compatível com o formato de chat completions da OpenAI.

Corpo da Requisição

Exemplo de Requisição

curl https://api.zubnet.com/v1/chat/completions \
  -H "Authorization: Bearer $ZUBNET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is the capital of France?"}
    ],
    "temperature": 0.7,
    "max_tokens": 150
  }'

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1699900000,
  "model": "claude-sonnet-5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The capital of France is Paris."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 8,
    "total_tokens": 33
  }
}

Geração de Código

Gere código a partir de um prompt em linguagem natural. Retorna uma resposta em streaming via Server-Sent Events (SSE).

Corpo da Requisição

Exemplo de Requisição

curl https://zubnet.com/api/ai/completions/code \
  -H "Authorization: Bearer $ZUBNET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A function that checks if a number is prime",
    "language": "python"
  }'

{
  "object": "code_document",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "model": "claude-sonnet-5",
  "cost": 1,
  "title": "Prime Number Checker",
  "content": "def is_prime(n): ..."
}

Geração de Imagens

Gere imagens a partir de prompts de texto usando modelos do FLUX, Stable Diffusion, Ideogram e mais.

Modelos Disponíveis

Corpo da Requisição

Exemplo de Requisição

curl https://api.zubnet.com/v1/images/generations \
  -H "Authorization: Bearer $ZUBNET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-pro-1.1-ultra",
    "prompt": "A serene mountain lake at sunset, photorealistic",
    "n": 1,
    "size": "1024x1024"
  }'

{
  "created": 1699900000,
  "data": [
    {
      "url": "https://zubnet.com/files/abc123.png",
      "revised_prompt": "A serene mountain lake..."
    }
  ]
}

Modelos assíncronos — 202 Accepted

Alguns modelos (FLUX, Runway, Luma, Kling, Leonardo, Vidu, Bria enhance/upscale) geram de forma assíncrona: aceitam o trabalho e o concluem instantes depois. Para eles, o endpoint responde 202 Accepted com um identificador de consulta em vez da imagem — uma extensão deliberada do contrato da OpenAI, que não tem essa rota:

{
  "id": "01934f2e-7c1b-7e55-9f3a-2d1c0b4a8f66",
  "status": "queued",
  "poll": "/v1/images/01934f2e-7c1b-7e55-9f3a-2d1c0b4a8f66"
}

Consulte uma geração iniciada de forma assíncrona. Informa queued, processing, completed ou failed; quando concluída, a URL da imagem aparece no mesmo formato data da resposta síncrona. Restrito ao workspace da chave de API chamadora — um id que não existe ou pertence a outro workspace responde o mesmo 404.

{
  "id": "01934f2e-7c1b-7e55-9f3a-2d1c0b4a8f66",
  "status": "completed",
  "created": 1699900000,
  "data": [
    {
      "url": "https://zubnet.com/files/abc123.png"
    }
  ]
}

Edite uma imagem com um prompt de texto — o contrato images.edit da OpenAI, enviado como multipart/form-data. Disponível nos modelos que aceitam uma imagem de entrada (a ficha do modelo lista edição de imagens): gpt-image-2.5-sunburst, gpt-image-2.5-flare, gpt-image-2, p-image-edit, gen4_image, luma/photon-1 e outros. Qualquer outro modelo responde 400. Modelos síncronos e assíncronos seguem os mesmos contratos 200 / 202 das gerações.

Campos do formulário

Exemplo de Requisição

curl https://api.zubnet.com/v1/images/edits \
  -H "Authorization: Bearer $ZUBNET_API_KEY" \
  -F "model=gpt-image-2.5-sunburst" \
  -F "prompt=Turn the sky into a starry night, keep everything else" \
  -F "image=@photo.png"

{
  "created": 1699900000,
  "data": [
    {
      "url": "https://zubnet.com/files/def456.png",
      "revised_prompt": "Turn the sky into a starry night, keep everything else"
    }
  ]
}

Geração de Vídeo

Gere vídeos a partir de prompts de texto ou imagens. Suporta fluxos de texto para vídeo, imagem para vídeo e vídeo para vídeo.

Modelos Disponíveis

Corpo da Requisição

Exemplo: Texto para Vídeo

curl https://zubnet.com/api/ai/videos \
  -H "Authorization: Bearer $ZUBNET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-generate-001",
    "prompt": "A drone shot flying over a coral reef at golden hour",
    "aspect_ratio": "16:9",
    "duration": 8
  }'

Exemplo: Imagem para Vídeo

curl https://zubnet.com/api/ai/videos \
  -H "Authorization: Bearer $ZUBNET_API_KEY" \
  -F "model=kling-v2-5-turbo" \
  -F "prompt=Camera slowly zooms in" \
  -F "frames=@my-image.png"

{
  "object": "video",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "model": "veo-3.1-generate-001",
  "state": "processing",
  "progress": 0,
  "cost": 5,
  "output_file": null,
  "created_at": "2026-02-25T12:00:00Z"
}

Compreensão de Vídeo

Analise conteúdo de vídeo usando IA. Envie uma URL de vídeo para análise e consulte os resultados. Suporta vários tipos de análise.

Envie um vídeo para análise com IA. Retorna um ID de tarefa que pode ser consultado para resultados.

Corpo da Requisição

Exemplo de Requisição

curl https://zubnet.com/api/ai/video-understanding \
  -H "Authorization: Bearer $ZUBNET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://example.com/video.mp4",
    "type": "summary"
  }'

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued"
}

Verifique o status de uma tarefa de análise de vídeo.

{
  "status": "completed",
  "result": {
    "type": "summary",
    "content": "The video shows a product demonstration..."
  }
}

Composição Musical

Gere músicas originais a partir de descrições textuais, letras ou tags de estilo.

Modelos Disponíveis

Corpo da Requisição

Exemplo de Requisição

curl https://zubnet.com/api/ai/compositions \
  -H "Authorization: Bearer $ZUBNET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno/v5",
    "prompt": "An upbeat synthwave track about coding at 3am",
    "tags": "synthwave, electronic, upbeat",
    "instrumental": true
  }'

[
  {
    "object": "composition",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "model": "suno/v5",
    "title": "Midnight Code",
    "tags": "synthwave, electronic, upbeat",
    "cost": 2,
    "output_file": {
      "url": "https://zubnet.com/files/abc123.mp3"
    }
  },
  {
    "object": "composition",
    "id": "550e8400-e29b-41d4-a716-446655440001",
    // ... second variant
  }
]

Efeitos Sonoros

Gere efeitos sonoros a partir de descrições textuais.

Corpo da Requisição

Exemplo de Requisição

curl https://zubnet.com/api/ai/sound-effects \
  -H "Authorization: Bearer $ZUBNET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sound-effect-model",
    "prompt": "Thunder rumbling in the distance followed by heavy rain"
  }'

{
  "object": "sound_effect",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "model": "sound-effect-model",
  "cost": 1,
  "output_file": {
    "url": "https://zubnet.com/files/abc123.mp3"
  }
}

Texto para Fala

Converta texto em áudio de fala natural usando vozes da ElevenLabs, Cartesia, Speechify e mais.

Exemplo de Requisição

curl https://api.zubnet.com/v1/audio/speech \
  -H "Authorization: Bearer $ZUBNET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tts-1-hd",
    "input": "Welcome to Zubnet, the future of AI.",
    "voice": "nova"
  }' --output speech.mp3

Transcrição

Transcreva áudio para texto.

Exemplo de Requisição

curl https://api.zubnet.com/v1/audio/transcriptions \
  -H "Authorization: Bearer $ZUBNET_API_KEY" \
  -F "model=whisper-1" \
  -F "file=@recording.mp3"

{
  "object": "transcription",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "model": "whisper-1",
  "content": "Hello, this is a test recording..."
}

Isolamento de Voz

Extraia vocais limpos do áudio, removendo ruído de fundo e música. Powered by ElevenLabs.

Exemplo de Requisição

curl https://zubnet.com/api/ai/isolated-voices \
  -H "Authorization: Bearer $ZUBNET_API_KEY" \
  -F "file=@noisy-recording.mp3"

{
  "object": "isolated_voice",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "cost": 1,
  "input_file": {
    "url": "https://zubnet.com/files/input.mp3"
  },
  "output_file": {
    "url": "https://zubnet.com/files/isolated.mp3"
  }
}

Separação de Faixas

Separe o áudio em faixas individuais (vocais, bateria, baixo, guitarra, piano, outros). Powered by ElevenLabs.

Exemplo de Requisição

curl https://zubnet.com/api/ai/stem-separations \
  -H "Authorization: Bearer $ZUBNET_API_KEY" \
  -F "file=@song.mp3"

{
  "object": "stem_separation",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "cost": 1,
  "input_file": {
    "url": "https://zubnet.com/files/song.mp3"
  },
  "output_file": {
    "url": "https://zubnet.com/files/stems.zip"
  }
}

Vozes

Crie e gerencie vozes personalizadas para geração de texto para fala.

Crie uma voz personalizada fazendo upload de amostras de áudio.

Liste todas as vozes disponíveis no seu espaço de trabalho, incluindo vozes personalizadas que você criou.

Atualize uma voz personalizada (nome, configurações).

Excluir uma voz personalizada.

Embeddings

Crie embeddings de texto para busca semântica e similaridade.

Exemplo de Requisição

curl https://api.zubnet.com/v1/embeddings \
  -H "Authorization: Bearer $ZUBNET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-small",
    "input": "The quick brown fox jumps over the lazy dog"
  }'

Bases de Conhecimento

Crie e gerencie bases de conhecimento para geração aumentada por recuperação (RAG). Faça upload de documentos (PDF, DOCX, TXT, Markdown) ou adicione URLs da web e texto bruto, e depois consulte-os nas suas completions de chat.

Crie uma nova base de conhecimento.

Corpo da Requisição

Exemplo: Criar uma Base de Conhecimento

curl https://zubnet.com/api/knowledge-bases \
  -H "Authorization: Bearer $ZUBNET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My KB",
    "description": "Optional description"
  }'

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "My KB",
  "description": "Optional description",
  "status": "active"
}

Liste todas as bases de conhecimento no seu espaço de trabalho.

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My KB",
    "description": "Optional description",
    "status": "active"
  },
  ...
]

Obtenha detalhes de uma base de conhecimento específica, incluindo seus documentos.

Excluir uma base de conhecimento e todos os seus documentos.

Ingira um documento em uma base de conhecimento. Suporta upload de arquivos, URLs e texto bruto.

Corpo da Requisição

Exemplo: Ingerir um Arquivo

curl https://zubnet.com/api/knowledge-bases/550e8400-.../documents \
  -H "Authorization: Bearer $ZUBNET_API_KEY" \
  -F "file=@report.pdf"

Exemplo: Ingerir uma URL

curl https://zubnet.com/api/knowledge-bases/550e8400-.../documents \
  -H "Authorization: Bearer $ZUBNET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Zubnet Docs",
    "type": "url",
    "url": "https://zubnet.com/developers.html"
  }'

Exemplo: Ingerir Texto Bruto

curl https://zubnet.com/api/knowledge-bases/550e8400-.../documents \
  -H "Authorization: Bearer $ZUBNET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Company Policy",
    "type": "text",
    "content": "All employees must complete security training annually..."
  }'

Liste todos os documentos em uma base de conhecimento.

Exclua um documento específico de uma base de conhecimento.

Leia o conteúdo de texto extraído de um documento específico.

Reranking

Reordene uma lista de documentos por relevância a uma consulta. Útil para melhorar resultados de busca, pipelines RAG e sistemas de recomendação.

Modelos Disponíveis

Corpo da Requisição

Exemplo de Requisição

curl https://api.zubnet.com/v1/reranking \
  -H "Authorization: Bearer $ZUBNET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "rerank-v4.0-pro",
    "query": "How do I reset my password?",
    "documents": [
      "To reset your password, go to Settings > Security > Change Password.",
      "Our pricing plans start at $9/month for individuals.",
      "Password requirements: minimum 8 characters, one uppercase letter.",
      "Contact support at help@example.com for account issues."
    ],
    "top_n": 3
  }'

{
  "object": "list",
  "results": [
    {
      "index": 0,
      "relevance_score": 0.953
    },
    {
      "index": 2,
      "relevance_score": 0.714
    },
    {
      "index": 3,
      "relevance_score": 0.389
    }
  ],
  "model": "rerank-v4.0-pro"
}

Biblioteca

A biblioteca é onde todo o conteúdo gerado fica — imagens, vídeos, composições, documentos de código, transcrições e mais. Use-a para listar itens, verificar o status de geração assíncrona, atualizar metadados e gerenciar seu conteúdo.

Liste itens da sua biblioteca por tipo de conteúdo.

Tipos de Conteúdo

Parâmetros de Consulta

{
  "object": "list",
  "data": [
    {
      "id": "550e8400-...",
      "object": "video",
      "model": "veo-3.1-generate-001",
      "title": "Coral reef drone shot",
      "state": 3,
      "progress": 100,
      "cost": 5,
      "output_file": {
        "url": "https://zubnet.com/files/abc123.mp4",
        "size": 8421376,
        "extension": "mp4"
      },
      "created_at": "2026-03-01T12:00:00Z"
    },
    ...
  ]
}

Obtenha um único item da biblioteca por ID. Este é o endpoint principal para consultando status de geração assíncrona.

Estados de Geração

Padrão de Consulta

# 1. Start async generation
curl -X POST https://zubnet.com/api/ai/videos \
  -H "Authorization: Bearer $ZUBNET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "veo-3.1-generate-001", "prompt": "A coral reef"}'
# Returns: {"id": "550e8400-...", "state": 1, ...}

# 2. Poll for completion
curl https://zubnet.com/api/library/videos/550e8400-... \
  -H "Authorization: Bearer $ZUBNET_API_KEY"
# Returns: {"state": 2, "progress": 45, ...}  (still processing)
# Returns: {"state": 3, "progress": 100, "output_file": {"url": "..."}}  (done!)

Atualize os metadados de um item da biblioteca.

Excluir um item da biblioteca e seus arquivos associados.

Obtenha a contagem total de itens para um tipo de conteúdo. Suporta os mesmos query e model filtros do endpoint de listagem.

Assistentes

Assistentes são presets de chat reutilizáveis com nome personalizado, modelo, prompt de sistema e configurações. Use-os para criar personas de IA especializadas para diferentes tarefas.

Crie um novo assistente.

Liste todos os assistentes no seu espaço de trabalho.

Atualize a configuração de um assistente (nome, modelo, prompt do sistema, configurações).

Excluir um assistente.

Loja MCP

Navegue e ative servidores MCP (Model Context Protocol) para dar aos seus agentes capacidades estendidas de ferramentas — desde busca na web e acesso a dados até execução de código e integrações de terceiros.

Navegue pelo catálogo de servidores MCP.

Parâmetros de Consulta

{
  "object": "list",
  "data": [
    {
      "id": "550e8400-...",
      "name": "GitHub",
      "description": "Access GitHub repositories, issues, and pull requests",
      "category": "developer",
      "config_schema": [
        {"name": "api_key", "type": "secret", "label": "API Key", "required": true}
      ],
      "tools": ["list_repos", "create_issue", "search_code"],
      "is_official": true
    },
    ...
  ]
}

Ative um servidor MCP para o seu espaço de trabalho. Forneça valores de configuração (chaves de API, etc.) conforme definido pelo config_schema.

Corpo da Requisição

Exemplo de Requisição

curl https://zubnet.com/api/mcp-store/activations \
  -H "Authorization: Bearer $ZUBNET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "server_id": "550e8400-e29b-41d4-a716-446655440000",
    "config": {
      "api_key": "ghp_xxxxxxxxxxxx"
    }
  }'

{
  "id": "act-uuid-...",
  "server_id": "550e8400-...",
  "status": 1,
  "config": {
    "api_key": "••••••••"
  },
  "server": {
    "name": "GitHub",
    ...
  },
  "created_at": "2026-03-01T12:00:00Z"
}

Liste todos os servidores MCP ativados no seu espaço de trabalho.

Atualize a configuração ou status de uma ativação.

Desative um servidor MCP do seu espaço de trabalho.

Agentes

Crie e gerencie agentes de IA autônomos que operam em canais de comunicação. Os agentes podem responder a mensagens no Telegram e Discord, executar com gatilhos agendados e aproveitar bases de conhecimento e servidores MCP para capacidades aprimoradas.

Crie um novo agente.

Corpo da Requisição

Exemplo de Requisição

curl https://zubnet.com/api/agents \
  -H "Authorization: Bearer $ZUBNET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Bot",
    "model": "claude-sonnet-5",
    "system_prompt": "You are a friendly support agent. Answer questions clearly and concisely.",
    "mode": "advanced"
  }'

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Support Bot",
  "slug": "support-bot",
  "avatar": null,
  "model": "claude-sonnet-5",
  "system_prompt": "You are a friendly support agent...",
  "status": 1,
  "mode": "advanced",
  "permissions": {
    "time_windows": [],
    "frequency_cap": {
      "max_messages_per_hour": 60,
      "max_messages_per_day": 500
    },
    "channel_preferences": {},
    "allowed_actions": {
      "can_use_tools": true,
      "can_access_kb": true,
      "max_tool_calls_per_message": 5
    }
  },
  "cost": 0,
  "last_active_at": null,
  "created_at": 1709136000,
  "updated_at": null,
  "user": {
    "id": "a1b2c3d4-...",
    "first_name": "Jane",
    "last_name": "Doe",
    "avatar": "https://zubnet.com/files/avatar.jpg"
  },
  "channels": []
}

Liste todos os agentes no espaço de trabalho. Suporta paginação e filtragem.

{
  "object": "list",
  "data": [
    {
      "id": "550e8400-...",
      "name": "Support Bot",
      "slug": "support-bot",
      "model": "claude-sonnet-5",
      "status": 1,
      "mode": "advanced",
      "cost": 12.50,
      "last_active_at": 1709222400,
      "created_at": 1709136000,
      ...
    }
  ]
}

Obtenha detalhes completos de um agente específico, incluindo seus canais, servidores MCP vinculados e bases de conhecimento.

Atualize um agente. Todos os campos são opcionais — apenas os campos fornecidos são alterados.

Corpo da Requisição

Objeto de Permissões

{
  "permissions": {
    "time_windows": [
      {
        "days": [1, 2, 3, 4, 5],  // 0=Sun, 6=Sat
        "timezone": "America/New_York",
        "start_hour": 9,            // 0-23
        "end_hour": 17              // 1-24
      }
    ],
    "frequency_cap": {
      "max_messages_per_hour": 60,    // 1-1000
      "max_messages_per_day": 500     // 1-10000
    },
    "channel_preferences": {
      "default_channel": "telegram",
      "proactive_channels": ["telegram", "discord"]
    },
    "allowed_actions": {
      "can_use_tools": true,
      "can_access_kb": true,
      "max_tool_calls_per_message": 5  // 0-50
    }
  }
}

Exclua um agente. Isso também remove todos os seus canais, gatilhos, mensagens e integrações.

Integrações

Vincule uma base de conhecimento a um agente para respostas com RAG. Body: { "knowledge_base_id": "uuid" }

Desvincule uma base de conhecimento de um agente.

Vincule um servidor MCP a um agente para uso estendido de ferramentas. Body: { "activation_id": "uuid" }

Desvincule um servidor MCP de um agente.

Recupere o histórico de conversas de um agente.

{
  "object": "list",
  "data": [
    {
      "id": "msg-uuid-...",
      "direction": "inbound",
      "content": "How do I reset my password?",
      "external_user_name": "john_doe",
      "cost": 0,
      "model": null,
      "created_at": 1709222400
    },
    {
      "id": "msg-uuid-...",
      "direction": "outbound",
      "content": "Go to Settings > Security > Change Password...",
      "cost": 0.25,
      "model": "claude-sonnet-5",
      "created_at": 1709222401
    }
  ]
}

Canais do Agente

Conecte agentes a plataformas de comunicação. Cada agente suporta um canal por tipo (um bot Telegram, um bot Discord).

Adicione um canal de comunicação a um agente.

Corpo da Requisição

Exemplo de Requisição

curl https://zubnet.com/api/agents/550e8400-.../channels \
  -H "Authorization: Bearer $ZUBNET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "telegram",
    "token": "7123456789:AAH..."
  }'

{
  "id": "ch-uuid-...",
  "type": "telegram",
  "status": 1,
  "metadata": {},
  "last_error": null,
  "last_message_at": null,
  "created_at": 1709136000
}

Liste todos os canais conectados a um agente.

Remova um canal de um agente.

Gatilhos do Agente

Automatize ações do agente com gatilhos. Gatilhos agendados usam expressões cron para executar em horários específicos; gatilhos de evento disparam em resposta a eventos externos.

Crie um gatilho automatizado para um agente.

Corpo da Requisição

Exemplo: Gatilho de Resumo Diário

curl https://zubnet.com/api/agents/550e8400-.../triggers \
  -H "Authorization: Bearer $ZUBNET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily Summary",
    "type": "scheduled",
    "prompt": "Summarize the key metrics for today and send them to the team.",
    "cron_expression": "0 18 * * 1-5",
    "timezone": "America/New_York"
  }'

{
  "id": "tr-uuid-...",
  "name": "Daily Summary",
  "type": "scheduled",
  "status": 1,
  "cron_expression": "0 18 * * 1-5",
  "timezone": "America/New_York",
  "prompt": "Summarize the key metrics for today...",
  "channel_id": null,
  "last_run_at": null,
  "next_run_at": 1709236800,
  "run_count": 0,
  "created_at": 1709136000
}

Liste todos os gatilhos de um agente.

Atualize um gatilho. Todos os campos são opcionais. Defina status como 0 para desabilitar ou 1 para habilitar.

Excluir um gatilho.

Espaços de Trabalho

Espaços de trabalho são a unidade organizacional da sua equipe. Cada espaço de trabalho tem seu próprio saldo de créditos, assinatura, chaves de API e membros. Gerencie espaços de trabalho, convide membros da equipe e acompanhe o uso.

Crie um novo espaço de trabalho.

{
  "id": "550e8400-...",
  "name": "My Team",
  "subscription": null,
  "api_spending_limit": null,
  "api_spending_current": 0,
  "owner": { "id": "...", "email": "..." },
  "created_at": "2026-03-01T12:00:00Z"
}

Atualize as configurações de um espaço de trabalho. Requer permissão de gerenciamento do espaço de trabalho.

Excluir um espaço de trabalho. Requer permissão de gerenciamento do espaço de trabalho.

Convide um usuário para entrar no espaço de trabalho por e-mail. Máximo de 20 convites pendentes por espaço de trabalho.

Cancele um convite pendente.

Remova um membro do espaço de trabalho, ou saia do espaço de trabalho usando seu próprio ID de usuário.

Liste estatísticas de uso agregadas do espaço de trabalho. Suporta paginação baseada em cursor.

Liste entradas de uso detalhadas (itens da biblioteca concluídos com custo > 0). Cada entrada inclui tipo, modelo, título, custo e timestamp.

Obtenha a contagem total de itens de uso.

Conversas

Conversas agrupam mensagens de chat em sessões. Crie uma conversa primeiro e depois envie mensagens para ela. As conversas também podem ser gerenciadas através da Biblioteca API usando o conversations tipo de conteúdo.

Crie uma nova conversa. Retorna o objeto de conversa com uma lista de mensagens vazia.

{
  "object": "conversation",
  "id": "550e8400-...",
  "title": null,
  "cost": 0,
  "messages": [],
  "created_at": "2026-03-01T12:00:00Z"
}

Envie uma mensagem para uma conversa e receba uma resposta de IA via Server-Sent Events (SSE). Veja a Completions de Chat seção para detalhes do formato de eventos SSE.

Corpo da Requisição

Exemplo de Requisição

curl https://zubnet.com/api/ai/conversations/550e8400-.../messages \
  -H "Authorization: Bearer $ZUBNET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1",
    "content": "Explain quantum computing in simple terms"
  }'

Conta

Gerencie seu perfil de usuário e gere chaves de API programaticamente.

Atualize as informações do seu perfil.

Gere uma nova chave de API. Requer confirmação de senha por segurança. A chave de API completa é retornada apenas uma vez nesta resposta — armazene-a com segurança.

{
  "id": "550e8400-...",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane@example.com",
  "api_key": "zub_live_a1b2c3d4e5f6..."
}

Faturamento

Explore os planos disponíveis, veja o histórico de pedidos, inicie o checkout e gerencie assinaturas.

Lista os planos de assinatura disponíveis.

Liste pedidos do espaço de trabalho atual. Suporta paginação baseada em cursor.

Inicie um checkout para um plano de assinatura ou compra de créditos. Requer permissão de gerenciamento do espaço de trabalho.

Cancele a assinatura atual do espaço de trabalho. Requer permissão de gerenciamento do espaço de trabalho.

Denúncias de Conteúdo

Denuncie conteúdo inadequado ou que viole as políticas na biblioteca pública.

Envie uma denúncia de conteúdo. Cada usuário pode denunciar um determinado item apenas uma vez.

{
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

Mais endpoints

A superfície completa vai além das seções acima. Estes endpoints estão ativos e usam a mesma autenticação:

Erros

A API usa códigos de status HTTP padrão e retorna mensagens de erro detalhadas.

{
  "error": {
    "message": "Invalid API key provided",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

Limites de Requisição

Os limites de requisição variam por plano. Cabeçalhos são incluídos em cada resposta:

Se você atingir um limite de requisição, aguarde até o momento de reinicialização ou entre em contato conosco para aumentar seus limites.