Zubnet / API 文档

简介

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

身份认证

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

Authorization: Bearer YOUR_API_KEY

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

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

您可以使用受支持供应商提供的自有 API 密钥。在工作区设置中添加后，向这些供应商发出的请求将自动使用这些密钥 — 零加价。BYOK在支持的套餐中可用。

你可以使用受支持供应商的 API 密钥。在工作区设置中添加它们，它们会自动用于对应供应商的请求, , 零加价。BYOK 在支持的方案中可用。 — 当为某个供应商配置了 BYOK 密钥时，它优先于平台密钥使用。你的 API 请求无需任何更改, , 密钥解析完全透明。

支持的 BYOK 供应商

Anthropic Google Gemini DeepSeek Mistral Alibaba Moonshot MiniMax Z.ai Xiaomi ElevenLabs Speechify Cartesia Resemble StabilityAI Black Forest Labs Ideogram PixVerse Vidu Suno ByteDance

模型

GET /v1/models

列出所有可用模型。

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"
    },
    ...
  ]
}

对话补全

POST /v1/chat/completions

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

请求体

参数	类型	描述
`model`必填	string	使用的模型 ID（例如 "claude-sonnet-5"、"deepseek-chat"、"gemini-2.5-pro"）
`messages`必填	数组	消息对象数组，包含 `role` 和 `content`
`temperature`可选	数字	采样温度 (0-2)。默认值：0.7
`max_tokens`可选	整数	最大生成 Token 数 (1-128000)。默认值：4096
`stream`可选	布尔值	通过 SSE 流式传输响应。默认值：true
`top_p`可选	数字	核采样参数 (0-1)。默认值：1
`frequency_penalty`可选	数字	频率惩罚 (-2 到 2)。默认值：0
`presence_penalty`可选	数字	存在惩罚 (-2 到 2)。默认值：0
`stop`可选	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-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
  }
}

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

代码生成

POST /api/ai/completions/code

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

请求体

参数	类型	描述
`prompt`必填	string	待生成代码的自然语言描述
`language`必填	string	编程语言（例如 "python"、"javascript"、"rust"）
`temperature`可选	数字	采样温度 (0-2)
`max_tokens`可选	整数	最大生成 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-5",
  "cost": 1,
  "title": "Prime Number Checker",
  "content": "def is_prime(n): ..."
}

图像生成

POST /v1/images/generations

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

可用模型

seedream-5.0-pro flux-pro-1.1-ultra grok-imagine-image qwen-image-2.0 ideogram-3.0 glm-image recraftv4

请求体

参数	类型	描述
`model`必填	string	使用的图像模型
`prompt`必填	string	待生成图像的文字描述
`n`可选	整数	生成图像数量。默认值：1
`size`可选	string	图像尺寸（例如 "1024x1024"、"1792x1024"）
`response_format`可选	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"
  }'

响应

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

文件 URL 会过期。 返回的 url 有效期约为一小时（见 expires_at）。生成的 id 是永久句柄：随时轮询 GET /v1/images/{id} 即可获取新链接。

异步模型 — 202 Accepted

部分模型（FLUX、Runway、Luma、Leonardo、Vidu、Bria 增强/放大）采用异步生成：先接受任务，稍后完成。对这些模型，端点返回 202 Accepted 和一个轮询句柄，而不是图像 — 这是对 OpenAI 契约的有意扩展，OpenAI 并没有这样的路由：

响应 — 202 Accepted

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

GET /v1/images/{id}

轮询一次异步启动的生成。报告 queued, processing, completed 或 failed；完成后，图像 URL 会以与同步响应相同的 data 结构出现。仅限调用方 API 密钥所属的工作区 — 不存在的 id 或属于其他工作区的 id 都会返回同样的 404.

Response — 已完成

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

POST /v1/images/edits

使用文本提示编辑图像 — 即 OpenAI 的 images.edit 契约，以 multipart/form-data发送。适用于接受输入图像的模型（其模型卡片列出了图像编辑）： gpt-image-2.5-sunburst, gpt-image-2.5-flare, gpt-image-2, p-image-edit, gen4_image 等。其他任何模型都会返回 400。同步与异步模型遵循与生成相同的 200 / 202 契约。

表单字段

字段	类型	描述
`model`必填	string	接受输入图像的图像模型
`prompt`必填	string	需要修改的内容
`image`必填	文件	要编辑的图像（PNG、JPEG 或 WebP）。在模型允许的情况下，发送 `image[]` 可传入多张
`mask`可选	文件	带 alpha 通道的 PNG，与图像尺寸相同；透明像素标记需要重绘的区域。仅限 gpt-image 模型
`size`可选	string	输出尺寸（例如 "1024x1024"、"1536x1024"）
`quality`可选	string	gpt-image 系列可选 "low"、"medium" 或 "high"
`n`可选	整数	要生成的编辑数量。默认：1

请求示例

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

视频生成

POST /api/ai/videos

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

可用模型

luma/ray-3.2-1080p seedance-2.0 wan2.7-t2v veo-3.1-generate-001 grok-imagine-video-1.5 minimax/hailuo-2.3 pixverse-v6 vidu-q3-pro

请求体

参数	类型	描述
`model`必填	string	使用的视频模型
`prompt`必填*	string	视频的文字描述。*唇形同步或超分辨率模型不需要
`frames`可选	文件[]	图像转视频的输入图像。每张最大 10MB (jpg, png, webp)
`video`可选	文件	视频转视频的输入视频。最大 100MB (mp4, webm, mov)
`audio`可选	文件	唇形同步模型的音频文件。最大 25MB
`aspect_ratio`可选	string	宽高比（例如 "16:9"、"9:16"、"1:1"）
`duration`可选	整数	视频时长（秒）
`negative_prompt`可选	string	视频中要避免的内容（视模型而定）
`resolution`可选	string	输出分辨率，如 "480p"、"720p"、"1080p"、"4k"（视模型而定）
`quality`可选	string	质量/速度档位（如支持，"speed" 或 "quality"）
`audio`可选	string	"on"/"off"——支持的模型可生成同步音频（Seedance 2.0、PixVerse、CogVideoX…）
`seed`可选	整数	再现性种子（如支持）
`style`可选	string	风格预设（支持的模型，如 Vidu："general"/"anime"）
各模型还接受自身特有选项（fps、multi_clip、mode、loop、motion_mode、宽高比…）——与应用中该模型显示的选择器完全一致。未知参数将被忽略。

示例：文本生成视频

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=seedance-2.0" \
  -F "prompt=Camera slowly zooms in" \
  -F "frames=@my-image.png"

视频生成是异步的。响应包含 state 字段（“处理中”, “已完成”, “失败”）和 progress 百分比。轮询资源库端点检查完成状态。

响应

{
  "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_url`必填	string	待分析视频的公开 HTTPS URL
`type`可选	string	分析类型： `summary` (默认), `topics`, `chapters`,或 `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"
  }'

响应

{
  "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 lyria-3-clip-preview lyria-3.5 stable-audio-2

请求体

参数	类型	描述
`model`必填	string	使用的音乐模型
`prompt`可选	string	音乐描述或待谱曲的歌词
`tags`可选	string	类型和风格标签（例如，"lo-fi, chill, jazz"）
`instrumental`可选	布尔值	仅生成器乐（无人声）。默认值：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 秒片段。

响应

[
  {
    "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
  }
]

音效

POST /api/ai/sound-effects

从文字描述生成音效。

请求体

参数	类型	描述
`model`必填	string	使用的音效模型
`prompt`必填	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"
  }'

响应

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

文字转语音

POST /v1/audio/speech

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

参数	类型	描述
`model`必填	string	TTS 模型（例如 "tts-1"、"tts-1-hd"、"elevenlabs"）
`input`必填	string	待转语音的文本（最大 5000 字符）
`voice`必填	string	使用的语音 ID（例如 "alloy"、"echo"、"nova" 或自定义语音 ID）
`response_format`可选	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

将音频转录为文字。

参数	类型	描述
`model`必填	string	转录模型（例如 "whisper-1"）
`file`必填	文件	待转录的音频文件。最大 25MB (mp3, mp4, wav, webm, ogg, flac)
`language`可选	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"

响应

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

人声分离

POST /api/ai/isolated-voices

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

参数	类型	描述
`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"

响应

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

音轨分离

POST /api/ai/stem-separations

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

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

请求示例

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

语音

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

POST /api/voices

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

GET /api/voices

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

PUT /api/voices/{id}

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

DELETE /api/voices/{id}

删除自定义语音。

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

向量嵌入

POST /v1/embeddings

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

参数	类型	描述
`model`必填	string	嵌入模型（例如 "text-embedding-3-small"）
`input`必填	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

创建新知识库。

请求体

参数	类型	描述
`name`必填	string	知识库名称
`description`可选	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"
  }'

响应

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

GET /api/knowledge-bases

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

响应

[
  {
    "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 和原始文本。

请求体

参数	类型	描述
`file`选项 1	文件	多部分文件上传（PDF、DOCX、TXT、MD, , 最大 10MB） — 语音录音（mp3、wav、webm、ogg, , 最大 10MB）
`title`必填	string	文档标题（URL 和文本类型必填）
`type`选项 2/3	string	"url" 或 "text"（用于非文件导入）
`url`选项 2	string	获取并导入的 URL（当类型为 "url" 时）
`content`选项 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

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

重排序

POST /v1/reranking

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

可用模型

rerank-2.5 rerank-2.5-lite jina-reranker-v3 jina-reranker-m0

请求体

参数	类型	描述
`model`必填	string	使用的重排模型
`query`必填	string	用于文档排名的搜索查询
`documents`必填	数组	待重排的文档字符串数组
`top_n`可选	整数	返回的最优结果数量。默认值：全部

请求示例

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

结果按相关性分数降序排列。 index 字段指每个文档在原始输入数组中的位置。

素材库

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

GET /api/library/{type}

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

内容类型

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

查询参数

参数	类型	描述
`limit`可选	整数	每页结果数（最大 100）
`starting_after`可选	string	正向分页游标（项目 UUID）
`ending_before`可选	string	反向分页游标（项目 UUID）
`sort`可选	string	排序字段和方向（例如 "created_at:desc"）
`query`可选	string	全文搜索（最大 255 字符）
`model`可选	string	按生成模型过滤

响应

{
  "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"
    },
    ...
  ]
}

GET /api/library/{type}/{id}

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

生成状态

状态	值	描述
`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}

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

参数	类型	描述
`title`可选	string	项目标题
`visibility`可选	整数	0（私有）或 1（公开）
`is_favorited`可选	布尔值	添加或移除收藏
`meta`可选	对象	自定义元数据（类型、情绪、标签、描述、作者等）

DELETE /api/library/{type}/{id}

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

GET /api/library/{type}/count

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

助手

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

POST /api/assistants

创建新助手。

GET /api/assistants

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

PUT /api/assistants/{id}

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

DELETE /api/assistants/{id}

删除助手。

MCP 商店

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

GET /api/mcp-store/servers

浏览 MCP 服务器目录。

查询参数

参数	类型	描述
`category`可选	string	按类别过滤（搜索、数据、开发、基础设施、通信、商务、创意、生产力、社交、工具）
`query`可选	string	按名称或描述搜索

响应

{
  "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_id`必填	string	待激活 MCP 服务器的 UUID
`config`可选	对象	与服务器 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 已创建)

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

配置中的密钥字段在 API 响应中会被掩码。每个工作区只能激活一个给定服务器一次。返回的 id 是 activation_id 可在关联 MCP 服务器到智能体时使用。

GET /api/mcp-store/activations

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

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

更新激活配置或状态。

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

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

智能体

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

POST /api/agents

创建新智能体。

请求体

参数	类型	描述
`name`必填	string	智能体名称（最大 64 字符）
`model`必填	string	使用的模型 ID（例如 "claude-sonnet-5"、"deepseek-chat"）
`system_prompt`可选	string	定义智能体行为和个性的自定义系统提示词
`mode`可选	string	"quick" 或 "advanced"。默认值："quick"
`avatar`可选	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-5",
    "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-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": []
}

GET /api/agents

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

参数	类型	描述
`limit`查询	整数	每页结果数。默认值：25
`cursor`查询	string	分页游标
`sort`查询	string	"name"、"created_at" 或 "last_active_at"。默认值："created_at"
`direction`查询	string	"asc" 或 "desc"
`status`查询	整数	按状态过滤：0（停用）、1（活跃）、2（暂停）

响应

{
  "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,
      ...
    }
  ]
}

GET /api/agents/{id}

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

PUT /api/agents/{id}

更新一个智能体，所有字段均为可选 — 更新智能体。所有字段可选, , 仅更新提供的字段。

请求体

参数	类型	描述
`name`可选	string	智能体名称（最大 64）
`model`可选	string	模型 ID
`system_prompt`可选	string\|null	系统提示词（设为 null 清除）
`status`可选	整数	0（停用）、1（活跃）或 2（暂停）
`mode`可选	string	"quick" 或 "advanced"
`permissions`可选	对象	智能体权限（见下文）

权限对象

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

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

集成

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

检索智能体的对话历史。

参数	类型	描述
`limit`查询	整数	返回的消息数量。默认值：25，最大值：100

响应

{
  "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
    }
  ]
}

智能体需要在你的方案中启用智能体功能。方案限制适用于智能体数量、每个智能体的渠道数和触发器数。

智能体渠道

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

POST /api/agents/{id}/channels

为智能体添加通信渠道。

请求体

参数	类型	描述
`type`必填	string	"telegram" 或 "discord"
`token`必填	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

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

请求体

参数	类型	描述
`name`必填	string	触发器名称（最大 128）
`type`必填	string	"scheduled" 或 "event"
`prompt`必填	string	触发器触发时发送给智能体的提示词
`cron_expression`可选	string	Cron 计划（例如 "0 9 * * 1-5" 表示工作日上午 9 点）
`timezone`可选	string	用于 cron 计算的 IANA 时区。默认值："UTC"
`channel_id`可选	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

创建新工作区。

参数	类型	描述
`name`必填	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}

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

参数	类型	描述
`name`可选	string	工作区名称（最大 50 字符）
`api_spending_limit`可选	数字	每月 API 消费上限（null 表示无限制）
`{provider}_api_key`可选	string	供应商的 BYOK API 密钥（例如 `openai_api_key`, `anthropic_api_key`)

DELETE /api/workspaces/{id}

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

POST /api/workspaces/{id}/invitations

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

参数	类型	描述
`email`必填	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 的已完成资源库项目）。每条记录包含类型、模型、标题、费用和时间戳。 > 0)。每条记录包含类型、模型、标题、费用和时间戳。

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

获取使用项目的总数。

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

对话

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

POST /api/ai/conversations

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

响应

{
  "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 事件格式详情。

请求体

参数	类型	描述
`model`必填	string	用于响应的模型
`content`可选	string	消息文本
`assistant_id`可选	string	用于此消息的助手 UUID
`parent_id`可选	string	父消息的 UUID（用于分支对话）
`file`可选	文件	附件（图像、文档、音视频, , 最大 25MB） — 最大 25MB)
`recording`可选	文件	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 。列出或删除对话请使用素材库类型为 conversations.

账户

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

PUT /api/account

更新你的资料信息。

参数	类型	描述
`first_name`可选	string	名字（最大 50 字符）
`last_name`可选	string	姓氏（最大 50 字符）
`language`可选	string	首选语言代码（例如 "en"、"fr"）
`preferences`可选	对象	用户偏好设置

POST /api/account/rest-api-keys

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

参数	类型	描述
`current_password`必填	string	你当前的账户密码

响应

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

Response api_key 的值仅在此响应中完整显示。后续 API 调用返回掩码版本。请像密码一样对待它。

账单

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

GET /api/billing/plans

列出可用的订阅方案。

参数	类型	描述
`billing_cycle`可选	string	按账单周期过滤

GET /api/billing/orders

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

参数	类型	描述
`status`可选	string	按订单状态过滤
`billing_cycle`可选	string	按账单周期过滤

POST /api/billing/checkout

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

参数	类型	描述
`id`可选	string	待订阅方案的 UUID（如果没有 `amount`)
`amount`可选	整数	积分购买金额，以分为单位（最低 1000，如果没有 `id`)
`gateway`可选	string	支付网关： `stripe` 或 `paypal`

DELETE /api/billing/subscription

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

内容举报

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

POST /api/content-reports

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

参数	类型	描述
`item_id`必填	string	待举报资源库项目的 UUID
`reason`必填	整数	原因代码：0（垃圾信息）、1（骚扰）、2（暴力）、3（色情内容）、4（其他）
`description`可选	string	补充详情（最大 2000 字符）

响应 (201 已创建)

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

重复举报（同一用户 + 同一项目）返回 409 Conflict 错误。

错误

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

代码	描述
`400`	请求错误 — 无效参数
`401`	未授权 — 无效或缺失的 API 密钥
`403`	禁止访问 — 积分不足或模型不在你的方案中
`404`	未找到 — 模型或资源未找到
`413`	请求体过大 — 文件超过大小限制
`429`	请求过多 — 超出速率限制
`500`	服务器内部错误
`503`	服务不可用 — 暂时过载

错误响应格式

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

速率限制

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

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

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

`POST /api/ai/three-d`	3D 模型生成（Tripo、Meshy…）
`POST /api/ai/tts · POST /api/ai/speeches`	文字转语音（原生接口 + 预设）
`POST /api/ai/transcriptions`	批量音频转录（可选模型）
`GET /api/ai/transcriptions/realtime/token · POST /api/ai/transcriptions/realtime/save`	麦克风实时转录（会话令牌 + 保存）
`POST /api/ai/translations · GET /api/ai/translation-languages`	文本翻译 + 支持的语言
`POST /api/ai/document-extractions`	文档文本提取（OCR）
`GET /api/ai/video-understanding/{jobId}`	视频理解任务状态
`/api/library-stacks`	资料库堆栈（合集）——完整 CRUD
`/api/chatroom`	团队聊天室（共享 AI 对话）
`/api/automation`	自动化工作流（构建 + 运行）