关注我们
EN
EN English
FR Français
ES Español

API 文档

目录

简介

Zubnet API 为你提供对 361 个 AI 模型的编程访问，涵盖文本、图像、视频、音乐、语音和代码生成。完全兼容 OpenAI API 规范——如果你已经在使用 OpenAI，只需更改 base URL 和 API 密钥即可切换到 Zubnet。

基础 URL

https://api.zubnet.com/v1

快速开始

# 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-4-20250514",
    "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-4-20250514",
    messages=[{"role": "user", "content": "Hello!"}]
)

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

身份认证

所有 API 请求需要通过 Authorization 标头中的 Bearer token 进行身份验证。

Authorization: Bearer YOUR_API_KEY

你可以从你的 账户设置生成 API 密钥。请妥善保管密钥——它们拥有你账户的完整访问权限。

使用你自己的供应商密钥 (BYOK)

你可以使用受支持供应商的 API 密钥。在工作区设置中添加它们，它们会自动用于对应供应商的请求——零加价。BYOK 在支持的方案中可用。

当为某个供应商配置了 BYOK 密钥时，它优先于平台密钥使用。你的 API 请求无需任何更改——密钥解析完全透明。

支持的 BYOK 供应商

Anthropic Google Gemini DeepSeek Mistral Cohere AI21 Nvidia Alibaba Moonshot MiniMax Sambanova Zhipu ElevenLabs Speechify Hume Cartesia Resemble StabilityAI Black Forest Labs Ideogram HiDream PixVerse Vidu Kling Suno ByteDance

Models

GET /v1/models

列出所有可用模型。

curl https://api.zubnet.com/v1/models \
  -H "Authorization: Bearer $ZUBNET_API_KEY"
Response
{
  "object": "list",
  "data": [
    {
      "id": "claude-sonnet-4-20250514",
      "object": "model",
      "created": 1699900000,
      "owned_by": "anthropic"
    },
    {
      "id": "deepseek-chat",
      "object": "model",
      "created": 1699900000,
      "owned_by": "deepseek"
    },
    ...
  ]
}

对话补全

POST /v1/chat/completions

创建对话补全。这是文本生成的主要端点，兼容 OpenAI 对话补全格式。

请求体

参数 类型 描述
modelrequired string 使用的模型 ID（例如 "claude-sonnet-4-20250514"、"deepseek-chat"、"gemini-2.5-pro"）
messagesrequired array 消息对象数组，包含 role and content
temperatureoptional number 采样温度 (0-2)。默认值：0.7
max_tokensoptional integer 最大生成 Token 数 (1-128000)。默认值：4096
streamoptional boolean 通过 SSE 流式传输响应。默认值：true
top_poptional number 核采样参数 (0-1)。默认值：1
frequency_penaltyoptional number 频率惩罚 (-2 到 2)。默认值：0
presence_penaltyoptional number 存在惩罚 (-2 到 2)。默认值：0
stopoptional string/array 停止序列

请求示例

curl https://api.zubnet.com/v1/chat/completions \
  -H "Authorization: Bearer $ZUBNET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is the capital of France?"}
    ],
    "temperature": 0.7,
    "max_tokens": 150
  }'
Response
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1699900000,
  "model": "claude-sonnet-4-20250514",
  "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
  }
}

流式传输

当 stream 为 true 时，响应以 Server-Sent Events (SSE) 形式传送。每个事件有一个命名类型和 JSON 载荷：

Event 描述
token 模型返回的文本 token/增量
reasoning-token 扩展思考 token（适用于支持推理的模型）
call 带名称和参数的工具/函数调用
message 最终完整消息对象（流结束时发送）
error 流式传输失败时的错误消息 
// SSE event format
event: token
data: {"data": "Hello", "attributes": {}}

event: token
data: {"data": " world", "attributes": {}}

event: message
data: {"id": "msg-uuid", "content": "Hello world", ...}

代码生成

POST /api/ai/completions/code

从自然语言提示生成代码。通过 Server-Sent Events (SSE) 返回流式响应。

请求体

参数 类型 描述
promptrequired string 待生成代码的自然语言描述
languagerequired string 编程语言（例如 "python"、"javascript"、"rust"）
temperatureoptional number 采样温度 (0-2)
max_tokensoptional integer 最大生成 Token 数 (1-128000)

请求示例

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"
  }'
此端点通过 SSE 流式传输。你会收到包含增量内容的 chunk 事件，最后是包含完整生成代码的 document 事件。
最终响应对象
{
  "object": "code_document",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "model": "claude-sonnet-4-20250514",
  "cost": 1,
  "title": "Prime Number Checker",
  "content": "def is_prime(n): ..."
}

图像生成

POST /v1/images/generations

使用 FLUX、Stable Diffusion、Ideogram 等模型从文本提示生成图像。

可用模型

flux-pro-1.1-ultra flux-pro-1.1 flux-2-pro flux-kontext-pro gen4_image ideogram-v3 hidream-i1-full

请求体

参数 类型 描述
modelrequired string 使用的图像模型
promptrequired string 待生成图像的文字描述
noptional integer 生成图像数量。默认值：1
sizeoptional string 图像尺寸（例如 "1024x1024"、"1792x1024"）
response_formatoptional string "url" 或 "b64_json"。默认值："url"

请求示例

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"
  }'
Response
{
  "created": 1699900000,
  "data": [
    {
      "url": "https://cdn.zubnet.com/files/abc123.png",
      "revised_prompt": "A serene mountain lake..."
    }
  ]
}

视频生成

POST /api/ai/videos

从文本提示或图像生成视频。支持文本生成视频、图像生成视频和视频生成视频工作流。

可用模型

veo-3.1-generate-001 veo-3.0-generate-001 kling-v2-5-turbo kling-v2-1-pro gen4_turbo gen4_aleph vidu-q2-pro pixverse-v4

请求体

参数 类型 描述
modelrequired string 使用的视频模型
promptrequired* string 视频的文字描述。*唇形同步或超分辨率模型不需要
framesoptional file[] 图像转视频的输入图像。每张最大 10MB (jpg, png, webp)
videooptional file 视频转视频的输入视频。最大 100MB (mp4, webm, mov)
audiooptional file 唇形同步模型的音频文件。最大 25MB
aspect_ratiooptional string 宽高比（例如 "16:9"、"9:16"、"1:1"）
durationoptional integer 视频时长（秒）

示例：文本生成视频

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
  }'

示例：图像生成视频

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"
视频生成是异步的。响应包含 state 字段（“processing”、“completed”、“failed”）和 progress 百分比。轮询资源库端点检查完成状态。
Response
{
  "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"
}

视频理解

使用 AI 分析视频内容。提交视频 URL 进行分析并轮询结果。支持多种分析类型。

POST /api/ai/video-understanding

提交视频进行 AI 分析。返回一个可轮询结果的任务 ID。

请求体

参数 类型 描述
video_urlrequired string 待分析视频的公开 HTTPS URL
typeoptional string 分析类型： summary (default), topics, chapters, or highlights

请求示例

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"
  }'
Response
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued"
}
GET /api/ai/video-understanding/{jobId}

检查视频分析任务的状态。

响应（已完成）
{
  "status": "completed",
  "result": {
    "type": "summary",
    "content": "The video shows a product demonstration..."
  }
}
视频 URL 必须是可公开访问的 HTTPS 链接。出于安全考虑，私有/内部 URL 会被拒绝。结果缓存 1 小时。

音乐创作

POST /api/ai/compositions

从文字描述、歌词或风格标签生成原创音乐。

可用模型

suno/v5 suno/v4.5-plus suno/v4.5 suno/v4 lyria-002

请求体

参数 类型 描述
modelrequired string 使用的音乐模型
promptoptional string 音乐描述或待谱曲的歌词
tagsoptional string 类型和风格标签（例如，"lo-fi, chill, jazz"）
instrumentaloptional boolean 仅生成器乐（无人声）。默认值：false

请求示例

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
  }'
Suno 模型通常每次请求返回 2 个作品变体。Lyria 返回一个 48kHz 的 30 秒片段。
Response
[
  {
    "object": "composition",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "model": "suno/v5",
    "title": "Midnight Code",
    "tags": "synthwave, electronic, upbeat",
    "cost": 2,
    "output_file": {
      "url": "https://cdn.zubnet.com/files/abc123.mp3"
    }
  },
  {
    "object": "composition",
    "id": "550e8400-e29b-41d4-a716-446655440001",
    // ... second variant
  }
]

音效

POST /api/ai/sound-effects

从文字描述生成音效。

请求体

参数 类型 描述
modelrequired string 使用的音效模型
promptrequired string 待生成音效的描述

请求示例

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"
  }'
Response
{
  "object": "sound_effect",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "model": "sound-effect-model",
  "cost": 1,
  "output_file": {
    "url": "https://cdn.zubnet.com/files/abc123.mp3"
  }
}

文字转语音

POST /v1/audio/speech

使用 ElevenLabs、Cartesia、Speechify 等的语音，将文字转换为自然发音的语音。

参数 类型 描述
modelrequired string TTS 模型（例如 "tts-1"、"tts-1-hd"、"elevenlabs"）
inputrequired string 待转语音的文本（最大 5000 字符）
voicerequired string 使用的语音 ID（例如 "alloy"、"echo"、"nova" 或自定义语音 ID）
response_formatoptional string 音频格式：mp3、opus、aac、flac。默认值：mp3

请求示例

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

语音转录

POST /v1/audio/transcriptions

将音频转录为文字。

参数 类型 描述
modelrequired string 转录模型（例如 "whisper-1"）
filerequired file 待转录的音频文件。最大 25MB (mp3, mp4, wav, webm, ogg, flac)
languageoptional string 语言代码（例如 "en"、"fr"、"es"）

请求示例

curl https://api.zubnet.com/v1/audio/transcriptions \
  -H "Authorization: Bearer $ZUBNET_API_KEY" \
  -F "model=whisper-1" \
  -F "file=@recording.mp3"
Response
{
  "object": "transcription",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "model": "whisper-1",
  "content": "Hello, this is a test recording..."
}

人声分离

POST /api/ai/isolated-voices

从音频中提取干净的人声，去除背景噪音和音乐。由 ElevenLabs 驱动。

参数 类型 描述
filerequired file 音频文件。最大 25MB (mp3, mp4, wav, m4a, webm, ogg, flac)

请求示例

curl https://zubnet.com/api/ai/isolated-voices \
  -H "Authorization: Bearer $ZUBNET_API_KEY" \
  -F "file=@noisy-recording.mp3"
Response
{
  "object": "isolated_voice",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "cost": 1,
  "input_file": {
    "url": "https://cdn.zubnet.com/files/input.mp3"
  },
  "output_file": {
    "url": "https://cdn.zubnet.com/files/isolated.mp3"
  }
}

音轨分离

POST /api/ai/stem-separations

将音频分离为独立音轨（人声、鼓、贝斯、吉他、钢琴、其他）。由 ElevenLabs 驱动。

参数 类型 描述
filerequired file 音频文件。最大 25MB (mp3, mp4, wav, m4a, webm, ogg, flac)
stem_variationoptional string 分离模式。默认值："six_stems_v1"（人声、鼓、贝斯、吉他、钢琴、其他）

请求示例

curl https://zubnet.com/api/ai/stem-separations \
  -H "Authorization: Bearer $ZUBNET_API_KEY" \
  -F "file=@song.mp3"
Response
{
  "object": "stem_separation",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "cost": 1,
  "input_file": {
    "url": "https://cdn.zubnet.com/files/song.mp3"
  },
  "output_file": {
    "url": "https://cdn.zubnet.com/files/stems.zip"
  }
}

Voices

创建和管理文字转语音的自定义语音。

POST /api/voices

通过上传音频样本创建自定义语音。

GET /api/voices

列出你工作区中可用的所有语音，包括你创建的自定义语音。

PUT /api/voices/{id}

更新自定义语音（名称、设置）。

DELETE /api/voices/{id}

删除自定义语音。

自定义语音 ID 可以在 voice 参数中用于文字转语音端点。

向量嵌入

POST /v1/embeddings

创建文本嵌入，用于语义搜索和相似度计算。

参数 类型 描述
modelrequired string 嵌入模型（例如 "text-embedding-3-small"）
inputrequired string/array 待嵌入的文本（字符串或字符串数组）

请求示例

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"
  }'

知识库

创建和管理知识库，用于检索增强生成 (RAG)。上传文档（PDF、DOCX、TXT、Markdown）或添加网页 URL 和原始文本，然后在对话补全中查询。

POST /api/knowledge-bases

创建新知识库。

请求体

参数 类型 描述
namerequired string 知识库名称
descriptionoptional string 知识库描述

示例：创建知识库

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"
  }'
Response
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "My KB",
  "description": "Optional description",
  "status": "active"
}
GET /api/knowledge-bases

列出你工作区中的所有知识库。

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

获取特定知识库的详细信息，包括其文档。

DELETE /api/knowledge-bases/{id}

删除知识库及其所有文档。

POST /api/knowledge-bases/{id}/documents

将文档导入知识库。支持文件上传、URL 和原始文本。

请求体

参数 类型 描述
fileoption 1 file 多部分文件上传（PDF、DOCX、TXT、MD——最大 10MB）
titlerequired string 文档标题（URL 和文本类型必填）
typeoption 2/3 string "url" 或 "text"（用于非文件导入）
urloption 2 string 获取并导入的 URL（当类型为 "url" 时）
contentoption 3 string 待导入的原始文本内容（当类型为 "text" 时）

示例：导入文件

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

示例：导入 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"
  }'

示例：导入原始文本

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..."
  }'
GET /api/knowledge-bases/{id}/documents

列出知识库中的所有文档。

DELETE /api/knowledge-bases/{id}/documents/{docId}

从知识库中删除特定文档。

GET /api/knowledge-bases/{id}/documents/{docId}/content

读取特定文档的提取文本内容。

Reranking

POST /v1/reranking

按与查询的相关性重新排列文档列表。适用于改进搜索结果、RAG 管道和推荐系统。

可用模型

rerank-v4.0-pro rerank-v4.0-fast jina-reranker-v3 jina-reranker-m0 rerank-2.5 rerank-2.5-lite

请求体

参数 类型 描述
modelrequired string 使用的重排模型
queryrequired string 用于文档排名的搜索查询
documentsrequired array 待重排的文档字符串数组
top_noptional integer 返回的最优结果数量。默认值：全部

请求示例

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
  }'
Response
{
  "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"
}
结果按相关性分数降序排列。index 字段指每个文档在原始输入数组中的位置。

Library

资源库是所有生成内容的存放地——图像、视频、作品、代码文档、转录等。用它来列出项目、检查异步生成状态、更新元数据和管理你的内容。

GET /api/library/{type}

按内容类型列出你资源库中的项目。

内容类型

images videos compositions sound-effects documents code-documents speeches transcriptions isolated-voices stem-separations conversations

查询参数

参数 类型 描述
limitoptional integer 每页结果数（最大 100）
starting_afteroptional string 正向分页游标（项目 UUID）
ending_beforeoptional string 反向分页游标（项目 UUID）
sortoptional string 排序字段和方向（例如 "created_at:desc"）
queryoptional string 全文搜索（最大 255 字符）
modeloptional string 按生成模型过滤
Response
{
  "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://cdn.zubnet.com/files/abc123.mp4",
        "size": 8421376,
        "extension": "mp4"
      },
      "created_at": "2026-03-01T12:00:00Z"
    },
    ...
  ]
}
GET /api/library/{type}/{id}

通过 ID 获取单个资源库项目。这是 轮询异步生成状态.

生成状态

State Value 描述
draft 0 尚未提交
queued 1 等待处理
processing 2 正在生成
completed 3 完成 — output_file 可用
failed 4 生成失败

轮询模式

# 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!)
分页基于游标。使用 id（最后一项的 ID）作为 starting_after 获取下一页。没有 offset/page 参数。
POST /api/library/{type}/{id}

更新资源库项目的元数据。

参数 类型 描述
titleoptional string 项目标题
visibilityoptional integer 0（私有）或 1（公开）
is_favoritedoptional boolean 添加或移除收藏
metaoptional object 自定义元数据（类型、情绪、标签、描述、作者等）
DELETE /api/library/{type}/{id}

删除资源库项目及其关联文件。

GET /api/library/{type}/count

获取某内容类型的项目总数。支持与 query and model 列表端点相同的过滤器。

Assistants

助手是可复用的对话预设，包含自定义名称、模型、系统提示词和设置。用它们为不同任务创建专业 AI 角色。

POST /api/assistants

创建新助手。

GET /api/assistants

列出你工作区中的所有助手。

PUT /api/assistants/{id}

更新助手配置（名称、模型、系统提示词、设置）。

DELETE /api/assistants/{id}

删除助手。

MCP Store

浏览并激活 MCP（Model Context Protocol）服务器，为你的智能体提供扩展工具能力——从网络搜索和数据访问到代码执行和第三方集成。

GET /api/mcp-store/servers

浏览 MCP 服务器目录。

查询参数

参数 类型 描述
categoryoptional string 按类别过滤（搜索、数据、开发、基础设施、通信、商务、创意、生产力、社交、工具）
queryoptional string 按名称或描述搜索
Response
{
  "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
    },
    ...
  ]
}
POST /api/mcp-store/activations

为你的工作区激活 MCP 服务器。按服务器的 config_schema.

请求体

参数 类型 描述
server_idrequired string 待激活 MCP 服务器的 UUID
configoptional object 与服务器 config_schema 匹配的配置值

请求示例

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"
    }
  }'
响应 (201 Created)
{
  "id": "act-uuid-...",
  "server_id": "550e8400-...",
  "status": 1,
  "config": {
    "api_key": "••••••••"
  },
  "server": {
    "name": "GitHub",
    ...
  },
  "created_at": "2026-03-01T12:00:00Z"
}
配置中的密钥字段在 API 响应中会被掩码。每个工作区只能激活一个给定服务器一次。返回的 id is the activation_id 可在关联 MCP 服务器到智能体时使用。
GET /api/mcp-store/activations

列出你工作区中已激活的所有 MCP 服务器。

PUT /api/mcp-store/activations/{id}

更新激活配置或状态。

DELETE /api/mcp-store/activations/{id}

从你的工作区停用 MCP 服务器。

Agents

创建和管理跨通信渠道运行的自主 AI 智能体。智能体可以响应 Telegram 和 Discord 上的消息，按计划触发器运行，并利用知识库和 MCP 服务器扩展能力。

POST /api/agents

创建新智能体。

请求体

参数 类型 描述
namerequired string 智能体名称（最大 64 字符）
modelrequired string 使用的模型 ID（例如 "claude-sonnet-4-20250514"、"deepseek-chat"）
system_promptoptional string 定义智能体行为和个性的自定义系统提示词
modeoptional string "quick" 或 "advanced"。默认值："quick"
avataroptional string 头像 URL（最大 512 字符）

请求示例

curl https://zubnet.com/api/agents \
  -H "Authorization: Bearer $ZUBNET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Bot",
    "model": "claude-sonnet-4-20250514",
    "system_prompt": "You are a friendly support agent. Answer questions clearly and concisely.",
    "mode": "advanced"
  }'
响应 (201 已创建)
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Support Bot",
  "slug": "support-bot",
  "avatar": null,
  "model": "claude-sonnet-4-20250514",
  "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://cdn.zubnet.com/files/avatar.jpg"
  },
  "channels": []
}
GET /api/agents

列出工作区中的所有智能体。支持分页和过滤。

参数 类型 描述
limitquery integer 每页结果数。默认值：25
cursorquery string 分页游标
sortquery string "name"、"created_at" 或 "last_active_at"。默认值："created_at"
directionquery string "asc" 或 "desc"
statusquery integer 按状态过滤：0（停用）、1（活跃）、2（暂停）
Response
{
  "object": "list",
  "data": [
    {
      "id": "550e8400-...",
      "name": "Support Bot",
      "slug": "support-bot",
      "model": "claude-sonnet-4-20250514",
      "status": 1,
      "mode": "advanced",
      "cost": 12.50,
      "last_active_at": 1709222400,
      "created_at": 1709136000,
      ...
    }
  ]
}
GET /api/agents/{id}

获取特定智能体的完整详情，包括其渠道、关联的 MCP 服务器和知识库。

PUT /api/agents/{id}

更新智能体。所有字段可选——仅更新提供的字段。

请求体

参数 类型 描述
nameoptional string 智能体名称（最大 64）
modeloptional string Model ID
system_promptoptional string|null 系统提示词（设为 null 清除）
statusoptional integer 0（停用）、1（活跃）或 2（暂停）
modeoptional string "quick" 或 "advanced"
permissionsoptional object 智能体权限（见下文）

权限对象

{
  "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
    }
  }
}
DELETE /api/agents/{id}

删除智能体。这也会移除其所有渠道、触发器、消息和集成。

Integrations

POST /api/agents/{id}/knowledge-bases

将知识库关联到智能体以支持 RAG 驱动的响应。请求体： { "knowledge_base_id": "uuid" }

DELETE /api/agents/{id}/knowledge-bases/{kid}

取消知识库与智能体的关联。

POST /api/agents/{id}/mcp-servers

将 MCP 服务器关联到智能体以扩展工具使用。请求体： { "activation_id": "uuid" }

DELETE /api/agents/{id}/mcp-servers/{activationId}

取消 MCP 服务器与智能体的关联。

GET /api/agents/{id}/messages

检索智能体的对话历史。

参数 类型 描述
limitquery integer 返回的消息数量。默认值：25，最大值：100
Response
{
  "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-4-20250514",
      "created_at": 1709222401
    }
  ]
}
智能体需要在你的方案中启用智能体功能。方案限制适用于智能体数量、每个智能体的渠道数和触发器数。

智能体渠道

将智能体连接到通信平台。每个智能体每种类型支持一个渠道（一个 Telegram 机器人，一个 Discord 机器人）。

POST /api/agents/{id}/channels

为智能体添加通信渠道。

请求体

参数 类型 描述
typerequired string "telegram" 或 "discord"
tokenrequired string 来自 Telegram BotFather 或 Discord Developer Portal 的 Bot token（最大 256）

请求示例

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..."
  }'
响应 (201 已创建)
{
  "id": "ch-uuid-...",
  "type": "telegram",
  "status": 1,
  "metadata": {},
  "last_error": null,
  "last_message_at": null,
  "created_at": 1709136000
}
Bot token 在激活前会通过平台 API 验证并静态加密。Telegram 会自动配置 webhook。渠道状态：0 = 停用，1 = 活跃，2 = 错误。
GET /api/agents/{id}/channels

列出连接到智能体的所有渠道。

DELETE /api/agents/{id}/channels/{channelId}

从智能体移除渠道。

智能体触发器

使用触发器自动化智能体操作。计划触发器使用 cron 表达式在特定时间运行；事件触发器响应外部事件触发。

POST /api/agents/{id}/triggers

为智能体创建自动触发器。

请求体

参数 类型 描述
namerequired string 触发器名称（最大 128）
typerequired string "scheduled" or "event"
promptrequired string 触发器触发时发送给智能体的提示词
cron_expressionoptional string Cron 计划（例如 "0 9 * * 1-5" 表示工作日上午 9 点）
timezoneoptional string 用于 cron 计算的 IANA 时区。默认值："UTC"
channel_idoptional string 发送触发器输出的渠道

示例：每日摘要触发器

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"
  }'
响应 (201 已创建)
{
  "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
}
GET /api/agents/{id}/triggers

列出智能体的所有触发器。

PUT /api/agents/{id}/triggers/{triggerId}

更新触发器。所有字段可选。设置 status 为 0 禁用或 1 启用。

DELETE /api/agents/{id}/triggers/{triggerId}

删除触发器。

计划触发器通过消息队列异步执行。每次执行前会检查智能体是否活跃以及工作区是否有足够积分。

工作区

工作区是团队的组织单元。每个工作区拥有独立的积分余额、订阅、API 密钥和成员。管理工作区、邀请团队成员、追踪使用情况。

POST /api/workspaces

创建新工作区。

参数 类型 描述
namerequired string 工作区名称（最大 50 字符）
响应 (201 已创建)
{
  "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"
}
POST /api/workspaces/{id}

更新工作区设置。需要工作区管理权限。

参数 类型 描述
nameoptional string 工作区名称（最大 50 字符）
api_spending_limitoptional number 每月 API 消费上限（null 表示无限制）
{provider}_api_keyoptional string 供应商的 BYOK API 密钥（例如 openai_api_key, anthropic_api_key)
DELETE /api/workspaces/{id}

删除工作区。需要工作区管理权限。

POST /api/workspaces/{id}/invitations

通过邮箱邀请用户加入工作区。每个工作区最多 20 个待处理邀请。

参数 类型 描述
emailrequired string 受邀用户的邮箱地址
DELETE /api/workspaces/{id}/invitations/{invitationId}

取消待处理的邀请。

DELETE /api/workspaces/{id}/users/{userId}

从工作区移除成员，或使用你自己的用户 ID 离开工作区。

GET /api/workspaces/{id}/logs/usage

列出工作区的汇总使用统计。支持基于游标的分页。

GET /api/workspaces/{id}/logs/usage/items

列出逐项使用记录（成本 > 0 的已完成资源库项目）。每条记录包含类型、模型、标题、费用和时间戳。

GET /api/workspaces/{id}/logs/usage/items/count

获取使用项目的总数。

使用情况和工作区管理端点需要工作区 manage 权限（工作区所有者或管理员）。

Conversations

对话将聊天消息分组为会话。先创建对话，然后向其发送消息。对话也可以通过 Library API 使用 conversations 内容类型进行管理。

POST /api/ai/conversations

创建新对话。返回带空消息列表的对话对象。

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

向对话发送消息并通过 Server-Sent Events (SSE) 接收 AI 响应。参见 对话补全 部分了解 SSE 事件格式详情。

请求体

参数 类型 描述
modelrequired string 用于响应的模型
contentoptional string 消息文本
assistant_idoptional string 用于此消息的助手 UUID
parent_idoptional string 父消息的 UUID（用于分支对话）
fileoptional file 附件（图像、文档、音视频——最大 25MB）
recordingoptional file 语音录音（mp3、wav、webm、ogg——最大 10MB）

请求示例

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"
  }'
消息通过 SSE 流式传输。上传文件时使用 multipart/form-data 。列出或删除对话请使用 Library API with type conversations.

Account

管理你的用户资料并通过编程方式生成 API 密钥。

PUT /api/account

更新你的资料信息。

参数 类型 描述
first_nameoptional string 名字（最大 50 字符）
last_nameoptional string 姓氏（最大 50 字符）
languageoptional string 首选语言代码（例如 "en"、"fr"）
preferencesoptional object 用户偏好设置
POST /api/account/rest-api-keys

生成新的 API 密钥。出于安全需要密码确认。完整的 API 密钥 此响应中 在此响应中 — 请安全存储。

参数 类型 描述
current_passwordrequired string 你当前的账户密码
Response
{
  "id": "550e8400-...",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane@example.com",
  "api_key": "zub_live_a1b2c3d4e5f6..."
}
api_key 的值仅在此响应中完整显示。后续 API 调用返回掩码版本。请像密码一样对待它。

Billing

浏览可用方案、查看订单历史、发起结账和管理订阅。

GET /api/billing/plans

列出可用的订阅方案。

参数 类型 描述
billing_cycleoptional string 按账单周期过滤
GET /api/billing/orders

列出当前工作区的订单。支持基于游标的分页。

参数 类型 描述
statusoptional string 按订单状态过滤
billing_cycleoptional string 按账单周期过滤
POST /api/billing/checkout

发起订阅方案或积分购买的结账。需要工作区管理权限。

参数 类型 描述
idoptional string 待订阅方案的 UUID（如果没有 amount)
amountoptional integer 积分购买金额，以分为单位（最低 1000，如果没有 id)
gatewayoptional string 支付网关： stripe or paypal
DELETE /api/billing/subscription

取消当前工作区的订阅。需要工作区管理权限。

Content Reports

举报公共资源库中不当或违规内容。

POST /api/content-reports

提交内容举报。每个用户只能对同一项目举报一次。

参数 类型 描述
item_idrequired string 待举报资源库项目的 UUID
reasonrequired integer 原因代码：0（垃圾信息）、1（骚扰）、2（暴力）、3（色情内容）、4（其他）
descriptionoptional string 补充详情（最大 2000 字符）
响应 (201 已创建)
{
  "id": "550e8400-e29b-41d4-a716-446655440000"
}
重复举报（同一用户 + 同一项目）返回 409 Conflict error.

Errors

API 使用标准 HTTP 状态码并返回详细错误信息。

Code 描述
400 请求错误 — 无效参数
401 未授权 — 无效或缺失的 API 密钥
403 禁止访问 — 积分不足或模型不在你的方案中
404 未找到 — 模型或资源未找到
413 请求体过大 — 文件超过大小限制
429 请求过多 — 超出速率限制
500 服务器内部错误
503 服务不可用 — 暂时过载
错误响应格式
{
  "error": {
    "message": "Invalid API key provided",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

速率限制

速率限制因方案而异。每个响应都包含以下标头：

Header 描述
X-RateLimit-Limit 每分钟允许的请求数
X-RateLimit-Remaining 当前窗口剩余请求数
X-RateLimit-Reset 限制重置的 Unix 时间戳

如果达到速率限制，请等待重置时间或联系我们提高限额。

需要帮助？

我们随时为你服务

对 API 有疑问？查看我们的常见问题或直接联系我们。