Tài liệu API

Giới thiệu

Zubnet API cung cấp cho bạn quyền truy cập theo chương trình vào 408 Các mô hình AI để tạo văn bản, hình ảnh, video, âm nhạc, giọng nói và mã. Hoàn toàn tương thích với đặc tả OpenAI API — nếu bạn đang sử dụng OpenAI, bạn có thể chuyển sang Zubnet bằng cách thay đổi khóa URL và API cơ bản của mình.

Đế URL

https://api.zubnet.com/v1

Bắt đầu nhanh

# 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)

Xác thực

Mọi yêu cầu API đều phải xác thực bằng Bearer token trong header Authorization.

Authorization: Bearer YOUR_API_KEY

Bạn có thể tạo khóa API từ cài đặt tài khoản. Hãy bảo mật khóa của bạn — họ cấp quyền truy cập đầy đủ vào tài khoản của bạn.

Sử dụng Khóa nhà cung cấp của riêng bạn (BYOK)

Bạn có thể sử dụng khóa API của riêng mình từ các nhà cung cấp được hỗ trợ. Thêm chúng vào cài đặt không gian làm việc của bạn và chúng sẽ được sử dụng tự động cho các yêu cầu gửi tới các nhà cung cấp đó — ở mức đánh dấu bằng không. BYOK có sẵn trên các gói hỗ trợ nó.

Khi khóa BYOK được định cấu hình cho nhà cung cấp, khóa này sẽ được ưu tiên hơn khóa nền tảng. Không cần thay đổi đối với các yêu cầu API của bạn — độ phân giải chính hoàn toàn trong suốt.

Nhà cung cấp BYOK được hỗ trợ

Mô hình

Liệt kê tất cả các mô hình có sẵn.

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

Chat Completions

Tạo một phản hồi trò chuyện. Đây là điểm cuối chính để tạo văn bản, tương thích với định dạng Chat Completions của OpenAI.

Nội dung yêu cầu

Yêu cầu mẫu

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

Tạo mã

Tạo mã từ lời nhắc bằng ngôn ngữ tự nhiên. Trả về phản hồi truyền trực tiếp qua Server-Sent Events (SSE).

Nội dung yêu cầu

Yêu cầu mẫu

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): ..."
}

Tạo hình ảnh

Tạo hình ảnh từ lời nhắc văn bản bằng FLUX, Stable Diffusion, Ideogram và nhiều mô hình khác.

Các mô hình hiện có

Nội dung yêu cầu

Yêu cầu mẫu

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

Tạo video

Tạo video từ lời nhắc văn bản hoặc hình ảnh. Hỗ trợ quy trình văn bản thành video, hình ảnh thành video và video thành video.

Các mô hình hiện có

Nội dung yêu cầu

Ví dụ: Chuyển văn bản thành video

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

Ví dụ: Chuyển hình ảnh thành video

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

Hiểu nội dung video

Phân tích nội dung video bằng AI. Gửi video URL để phân tích và thăm dò kết quả. Hỗ trợ nhiều loại phân tích.

Gửi video để phân tích AI. Trả về ID công việc mà bạn có thể thăm dò kết quả.

Nội dung yêu cầu

Yêu cầu mẫu

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

Kiểm tra trạng thái của công việc phân tích video.

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

Sáng tác âm nhạc

Tạo nhạc gốc từ mô tả văn bản, lời bài hát hoặc thẻ phong cách.

Các mô hình hiện có

Nội dung yêu cầu

Yêu cầu mẫu

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

Hiệu ứng âm thanh

Tạo hiệu ứng âm thanh từ mô tả văn bản.

Nội dung yêu cầu

Yêu cầu mẫu

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

Chuyển văn bản thành giọng nói

Chuyển đổi văn bản thành âm thanh lời nói có âm thanh tự nhiên bằng giọng nói từ ElevenLabs, Cartesia, Speechify, v.v.

Yêu cầu mẫu

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

Phiên âm

Chuyển âm thanh thành văn bản.

Yêu cầu mẫu

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

Tách giọng

Trích xuất giọng hát rõ ràng từ âm thanh, loại bỏ tiếng ồn xung quanh và âm nhạc. Được cung cấp bởi ElevenLabs.

Yêu cầu mẫu

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

Tách stem

Tách âm thanh thành các thân riêng lẻ (giọng hát, trống, bass, guitar, piano, loại khác). Được cung cấp bởi ElevenLabs.

Yêu cầu mẫu

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

Giọng nói

Tạo và quản lý giọng nói tùy chỉnh để tạo văn bản thành giọng nói.

Tạo giọng nói tùy chỉnh bằng cách tải lên các mẫu âm thanh.

Liệt kê tất cả các giọng nói có sẵn trong không gian làm việc của bạn, bao gồm cả các giọng nói tùy chỉnh mà bạn đã tạo.

Cập nhật giọng nói tùy chỉnh (tên, cài đặt).

Xóa một giọng nói tùy chỉnh.

Nhúng

Tạo các phần nhúng văn bản để tìm kiếm ngữ nghĩa và tương tự.

Yêu cầu mẫu

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

Cơ sở kiến thức

Tạo và quản lý cơ sở kiến thức cho phương pháp tạo sinh tăng cường truy xuất (RAG). Tải lên tài liệu (PDF, DOCX, TXT, Markdown), thêm URL web hoặc văn bản thô, rồi truy vấn chúng trong Chat Completions.

Tạo nền tảng kiến thức mới.

Nội dung yêu cầu

Ví dụ: Tạo cơ sở kiến thức

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

Liệt kê tất cả các cơ sở kiến thức trong không gian làm việc của bạn.

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

Nhận thông tin chi tiết về một cơ sở kiến thức cụ thể, bao gồm cả tài liệu của nó.

Xóa cơ sở kiến thức và tất cả tài liệu của nó.

Nạp tài liệu vào cơ sở kiến thức. Hỗ trợ tải tệp lên, URL và văn bản thô.

Nội dung yêu cầu

Ví dụ: Nhập một tệp

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

Ví dụ: Nhập 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"
  }'

Ví dụ: Nhập văn bản thô

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

Liệt kê tất cả các tài liệu trong cơ sở tri thức.

Xóa một tài liệu cụ thể khỏi cơ sở kiến thức.

Đọc nội dung văn bản được trích xuất của một tài liệu cụ thể.

Sắp xếp lại

Xếp hạng lại danh sách tài liệu theo độ liên quan với truy vấn. Hữu ích để cải thiện kết quả tìm kiếm, quy trình RAG và hệ thống đề xuất.

Các mô hình hiện có

Nội dung yêu cầu

Yêu cầu mẫu

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

Thư viện

Thư viện là nơi chứa tất cả nội dung được tạo — hình ảnh, video, tác phẩm, tài liệu mã, bản ghi âm, v.v. Sử dụng nó để liệt kê các mục, kiểm tra trạng thái tạo không đồng bộ, cập nhật siêu dữ liệu và quản lý nội dung của bạn.

Liệt kê các mục trong thư viện của bạn theo loại nội dung.

Các loại nội dung

Tham số truy vấn

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

Lấy một mục thư viện theo ID. Đây là điểm cuối chính dành cho trạng thái tạo phiếu bầu không đồng bộ.

Trạng thái tạo nội dung

Cơ chế thăm dò

# 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!)

Cập nhật siêu dữ liệu của mục thư viện.

Xóa một mục thư viện và các tập tin liên quan của nó.

Lấy tổng số mục cho một loại nội dung. Hỗ trợ tương tự query và model bộ lọc giống như điểm cuối danh sách.

Trợ lý

Trợ lý là cấu hình trò chuyện có thể tái sử dụng với tên, mô hình, lời nhắc hệ thống và cài đặt riêng. Hãy dùng chúng để tạo các vai trò AI chuyên biệt cho từng công việc.

Tạo một trợ lý mới.

Liệt kê tất cả các trợ lý trong không gian làm việc của bạn.

Cập nhật cấu hình trợ lý (tên, mô hình, lời nhắc hệ thống, cài đặt).

Xóa một trợ lý.

Kho MCP

Duyệt và kích hoạt máy chủ MCP (Model Context Protocol) để mở rộng khả năng sử dụng công cụ cho tác nhân — từ tìm kiếm trên web và truy cập dữ liệu đến thực thi mã và tích hợp của bên thứ ba.

Duyệt qua danh mục máy chủ MCP.

Tham số truy vấn

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

Kích hoạt máy chủ MCP cho không gian làm việc của bạn. Cung cấp các giá trị cấu hình (khóa API, v.v.) như được xác định bởi máy chủ config_schema.

Nội dung yêu cầu

Yêu cầu mẫu

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

Liệt kê tất cả các máy chủ MCP được kích hoạt trong không gian làm việc của bạn.

Cập nhật cấu hình hoặc trạng thái của kích hoạt.

Vô hiệu hóa máy chủ MCP khỏi không gian làm việc của bạn.

Tác nhân AI

Tạo và quản lý tác nhân AI tự chủ hoạt động trên nhiều kênh liên lạc. Tác nhân có thể trả lời tin nhắn trên Telegram và Discord, chạy theo lịch và sử dụng cơ sở kiến thức cùng máy chủ MCP để mở rộng khả năng.

Tạo một tác nhân mới.

Nội dung yêu cầu

Yêu cầu mẫu

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

Liệt kê tất cả các tác nhân trong không gian làm việc. Hỗ trợ phân trang và lọc.

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

Nhận thông tin chi tiết đầy đủ về một tác nhân cụ thể, bao gồm các kênh, máy chủ MCP được liên kết và cơ sở kiến thức.

Cập nhật tác nhân. Mọi trường đều không bắt buộc — chỉ các trường được cung cấp mới được thay đổi.

Nội dung yêu cầu

Đối tượng quyền

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

Xóa một tác nhân cùng toàn bộ kênh, trình kích hoạt, tin nhắn và tích hợp của tác nhân đó.

Tích hợp

Liên kết cơ sở kiến thức với tác nhân để tạo phản hồi bằng RAG. Nội dung yêu cầu: { "knowledge_base_id": "uuid" }

Hủy liên kết cơ sở kiến thức khỏi một tác nhân.

Liên kết máy chủ MCP với tác nhân để mở rộng khả năng dùng công cụ. Nội dung yêu cầu: { "activation_id": "uuid" }

Hủy liên kết máy chủ MCP khỏi tác nhân.

Truy xuất lịch sử trò chuyện của một tác nhân.

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

Kênh của tác nhân

Kết nối tác nhân với các nền tảng liên lạc. Mỗi tác nhân hỗ trợ một kênh cho mỗi loại (một bot Telegram và một bot Discord).

Thêm kênh liên lạc cho một tác nhân.

Nội dung yêu cầu

Yêu cầu mẫu

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
}

Liệt kê mọi kênh được kết nối với một tác nhân.

Xóa một kênh khỏi tác nhân.

Trình kích hoạt tác nhân

Tự động hóa các hành động của tác nhân bằng trình kích hoạt. Trình kích hoạt theo lịch trình sử dụng biểu thức cron để chạy vào những thời điểm cụ thể; sự kiện kích hoạt cháy để đáp ứng với các sự kiện bên ngoài.

Tạo trình kích hoạt tự động cho một tác nhân.

Nội dung yêu cầu

Ví dụ: Kích hoạt tóm tắt hàng ngày

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
}

Liệt kê tất cả các kích hoạt cho một tác nhân.

Cập nhật trình kích hoạt. Tất cả các trường là tùy chọn. Đặt status đến 0 để tắt hoặc 1 để bật.

Xóa trình kích hoạt.

Không gian làm việc

Không gian làm việc là đơn vị tổ chức của đội ngũ. Mỗi không gian có số dư credit, gói đăng ký, khóa API và thành viên riêng. Bạn có thể quản lý không gian làm việc, mời thành viên và theo dõi mức sử dụng.

Tạo một không gian làm việc mới.

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

Cập nhật cài đặt của không gian làm việc. Yêu cầu quyền quản lý không gian làm việc.

Xóa một không gian làm việc. Yêu cầu quyền quản lý không gian làm việc.

Mời người dùng tham gia không gian làm việc qua email. Tối đa 20 lời mời đang chờ xử lý cho mỗi không gian làm việc.

Hủy lời mời đang chờ xử lý.

Xóa thành viên khỏi không gian làm việc hoặc rời khỏi không gian làm việc bằng cách sử dụng ID người dùng của riêng bạn.

Liệt kê số liệu thống kê sử dụng tổng hợp cho không gian làm việc. Hỗ trợ phân trang dựa trên con trỏ.

Liệt kê các mục sử dụng được chia thành từng khoản (các mục thư viện đã hoàn thành với chi phí > 0). Mỗi mục gồm loại, mô hình, tiêu đề, chi phí và dấu thời gian.

Lấy tổng số mục sử dụng.

Cuộc trò chuyện

Conversation nhóm các tin nhắn trò chuyện thành từng phiên. Trước tiên hãy tạo một conversation, sau đó gửi tin nhắn vào đó. Bạn cũng có thể quản lý conversation qua Thư viện API sử dụng conversations loại nội dung.

Tạo một cuộc trò chuyện mới. Trả về đối tượng hội thoại có danh sách tin nhắn trống.

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

Gửi tin nhắn đến cuộc trò chuyện và nhận phản hồi AI qua Server-Sent Events (SSE). Xem Chat Completions phần để biết chi tiết định dạng sự kiện SSE.

Nội dung yêu cầu

Yêu cầu mẫu

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

Tài khoản

Quản lý hồ sơ người dùng của bạn và tạo khóa API theo chương trình.

Cập nhật thông tin hồ sơ của bạn.

Tạo khóa API mới. Yêu cầu xác nhận mật khẩu để bảo mật. Khóa API đầy đủ được trả về chỉ một lần trong phản hồi này — lưu trữ nó một cách an toàn.

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

Thanh toán

Duyệt các gói có sẵn, xem lịch sử đơn hàng, bắt đầu thanh toán và quản lý đăng ký.

Liệt kê các gói thuê bao có sẵn.

Liệt kê đơn hàng của không gian làm việc hiện tại. Hỗ trợ phân trang bằng con trỏ.

Bắt đầu thanh toán gói đăng ký hoặc mua credit. Yêu cầu quyền quản lý không gian làm việc.

Hủy đăng ký không gian làm việc hiện tại. Yêu cầu quyền quản lý không gian làm việc.

Báo cáo nội dung

Báo cáo nội dung không phù hợp hoặc vi phạm chính sách trong thư viện công cộng.

Gửi báo cáo nội dung. Mỗi người dùng chỉ có thể báo cáo một mục nhất định một lần.

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

Thêm điểm cuối

Phạm vi API đầy đủ còn lớn hơn các phần trên. Những điểm cuối sau đang hoạt động và dùng cùng phương thức xác thực:

Lỗi

API sử dụng mã trạng thái HTTP tiêu chuẩn và trả về thông báo lỗi chi tiết.

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

Giới hạn tỷ lệ

Giới hạn tỷ lệ thay đổi tùy theo gói. Tiêu đề được bao gồm trong mọi phản hồi:

Nếu bạn đạt đến giới hạn tốc độ, hãy đợi đến thời gian đặt lại hoặc liên hệ với chúng tôi để tăng giới hạn của bạn.