はじめに
Zubnet APIでは、テキスト、画像、動画、音楽、音声、コード生成に対応する408種類のAIモデルへプログラムからアクセスできます。OpenAI API仕様と完全に互換性があります。すでにOpenAIをご利用の場合、ベース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-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トークンによる認証が必要です。
Authorization: Bearer YOUR_API_KEY
APIキーは以下から生成できます。 アカウント設定。キーは安全に保管してください — これらはアカウントへの完全なアクセスを許可します。
独自のプロバイダーキーの使用(BYOK)
対応プロバイダーの独自のAPIキーを使用できます。ワークスペース設定に追加すると、それらのプロバイダーへのリクエストに自動的に使用されます。 — マークアップなしでご利用いただけます。BYOKは対応プランでご利用いただけます。
プロバイダーにBYOKキーが設定されている場合、プラットフォームキーよりも優先されます。APIリクエストに変更は必要ありません。 — キーの解決は完全に透過的です。
対応BYOKプロバイダー
モデル
利用可能なすべてのモデルを一覧表示します。
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"
},
...
]
}
チャットコンプリーション
チャットコンプリートを作成します。これはテキスト生成の主要なエンドポイントで、OpenAIのチャットコンプリート形式と互換性があります。
リクエストボディ
| パラメータ | タイプ | 説明 |
|---|---|---|
model必須 |
string | 使用するモデルID(例: "claude-sonnet-5"、"deepseek-chat"、"gemini-2.5-pro") |
messages必須 |
配列 | メッセージオブジェクトの配列( role および content |
temperature任意 |
数値 | サンプリング温度(0〜2)。デフォルト: 0.7 |
max_tokens任意 |
整数 | 生成する最大トークン数(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
}
}
ストリーミング
がtrueの場合 stream がtrueの場合、レスポンスはServer-Sent Events(SSE)として配信されます。各イベントには名前付きのタイプとJSONペイロードがあります:
| イベント | 説明 |
|---|---|
token |
モデルからのテキストトークン/デルタ |
reasoning-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", ...}
コード生成
自然言語プロンプトからコードを生成します。Server-Sent Events(SSE)を介してストリーミング応答を返します。
リクエストボディ
| パラメータ | タイプ | 説明 |
|---|---|---|
prompt必須 |
string | 生成するコードの自然言語による説明 |
language必須 |
string | プログラミング言語(例:"python"、"javascript"、"rust") |
temperature任意 |
数値 | サンプリング温度(0〜2) |
max_tokens任意 |
整数 | 生成する最大トークン数(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" }'
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): ..."
}
画像生成
FLUX、Stable Diffusion、Ideogramなどのモデルを使用して、テキストプロンプトから画像を生成します。
利用可能なモデル
リクエストボディ
| パラメータ | タイプ | 説明 |
|---|---|---|
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",
"revised_prompt": "A serene mountain lake..."
}
]
}
動画生成
テキストプロンプトまたは画像から動画を生成。テキストから動画、画像から動画、動画から動画のワークフローをサポート。
利用可能なモデル
リクエストボディ
| パラメータ | タイプ | 説明 |
|---|---|---|
model必須 |
string | 使用する動画モデル |
prompt必須* |
string | 動画のテキスト説明。*リップシンクまたはアップスケールモデルには不要 |
frames任意 |
file[] | 画像から動画への生成に使用する入力画像。各ファイル最大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、Kling、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=kling-v2-5-turbo" \ -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を提出して分析を依頼し、結果をポーリングします。複数の分析タイプをサポートしています。
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"
}
動画分析ジョブのステータスを確認します。
{
"status": "completed",
"result": {
"type": "summary",
"content": "The video shows a product demonstration..."
}
}
音楽作曲
テキスト説明、歌詞、またはスタイルタグからオリジナル音楽を生成。
利用可能なモデル
リクエストボディ
| パラメータ | タイプ | 説明 |
|---|---|---|
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 }'
[
{
"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
}
]
効果音
テキスト説明から効果音を生成。
リクエストボディ
| パラメータ | タイプ | 説明 |
|---|---|---|
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"
}
}
テキスト読み上げ
ElevenLabs、Cartesia、Speechifyなどの音声を使用して、テキストを自然な音声オーディオに変換します。
| パラメータ | タイプ | 説明 |
|---|---|---|
model必須 |
string | TTSモデル(例: "tts-1"、"tts-1-hd"、"elevenlabs") |
input必須 |
string | 音声に変換するテキスト(最大5,000文字) |
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
文字起こし
音声をテキストに書き起こします。
| パラメータ | タイプ | 説明 |
|---|---|---|
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..."
}
音声分離
音声からクリーンなボーカルを抽出し、背景ノイズや音楽を除去します。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"
}
}
ステム分離
オーディオを個別のステム(ボーカル、ドラム、ベース、ギター、ピアノ、その他)に分離します。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"
}
}
音声
テキスト読み上げ生成用のカスタムボイスを作成・管理します。
音声サンプルをアップロードしてカスタムボイスを作成します。
作成したカスタムボイスを含む、ワークスペースで利用可能なすべてのボイスを一覧表示します。
カスタムボイスを更新します(名前、設定)。
カスタムボイスを削除します。
voice Text-to-Speechエンドポイントのパラメータ。
埋め込み
セマンティック検索と類似性検索用のテキスト埋め込みを作成します。
| パラメータ | タイプ | 説明 |
|---|---|---|
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)をアップロードするか、Web URLや生のテキストを追加し、チャットコンプリートでクエリを実行できます。
新しいナレッジベースを作成します。
リクエストボディ
| パラメータ | タイプ | 説明 |
|---|---|---|
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"
}
ワークスペース内のすべてのナレッジベースを一覧表示します。
[
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "My KB",
"description": "Optional description",
"status": "active"
},
...
]
ドキュメントを含む、特定のナレッジベースの詳細を取得します。
ナレッジベースとそのすべてのドキュメントを削除します。
ドキュメントをナレッジベースに取り込みます。ファイルアップロード、URL、および生のテキストに対応しています。
リクエストボディ
| パラメータ | タイプ | 説明 |
|---|---|---|
fileオプション1 |
ファイル | マルチパートファイルアップロード(PDF、DOCX、TXT、MD — 最大10MB) |
title必須 |
string | ドキュメントタイトル(URLおよびテキストタイプに必須) |
typeオプション2/3 |
string | "url"または"text"(ファイル取り込み以外) |
urlオプション2 |
string | 取得して取り込むURL(タイプが"url"の場合) |
contentオプション3 |
string | 取り込む生のテキストコンテンツ(typeが"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..." }'
ナレッジベース内のすべてのドキュメントを一覧表示します。
ナレッジベースから特定のドキュメントを削除します。
特定のドキュメントから抽出されたテキストコンテンツを読み取ります。
再ランキング
クエリに対する関連性に基づいてドキュメントのリストを再ランキングします。検索結果、RAGパイプライン、レコメンデーションシステムの改善に有用です。
利用可能なモデル
リクエストボディ
| パラメータ | タイプ | 説明 |
|---|---|---|
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 フィールドは、元の入力配列における各ドキュメントの位置を指します。
ライブラリ
ライブラリは生成されたすべてのコンテンツが保存される場所です — 画像、動画、コンポジション、コードドキュメント、文字起こしなど。アイテムの一覧表示、非同期生成ステータスの確認、メタデータの更新、コンテンツの管理に使用します。
コンテンツタイプ別にライブラリのアイテムを一覧表示します。
コンテンツタイプ
クエリパラメータ
| パラメータ | タイプ | 説明 |
|---|---|---|
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"
},
...
]
}
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 の最後の項目の starting_after 次のページを取得します。offset/pageパラメータはありません。
ライブラリアイテムのメタデータを更新します。
| パラメータ | タイプ | 説明 |
|---|---|---|
title任意 |
string | 項目タイトル |
visibility任意 |
整数 | 0(非公開)または1(公開) |
is_favorited任意 |
ブール値 | お気に入りに追加または削除 |
meta任意 |
オブジェクト | カスタムメタデータ(ジャンル、ムード、タグ、説明、著者など) |
ライブラリ項目とその関連ファイルを削除します。
コンテンツタイプのアイテム総数を取得します。リストエンドポイントと同じ query および model リストエンドポイントと同じフィルター。
アシスタント
アシスタントは、カスタム名、モデル、システムプロンプト、設定を備えた再利用可能なチャットプリセットです。タスクごとに特化したAIペルソナを作成するためにご活用ください。
新しいアシスタントを作成します。
ワークスペース内のすべてのアシスタントを一覧表示します。
アシスタントの設定を更新します(名前、モデル、システムプロンプト、設定)。
アシスタントを削除します。
MCPストア
MCP(Model Context Protocol)サーバーを閲覧して有効化し、エージェントに拡張ツール機能を提供 — Web検索やデータアクセスからコード実行、サードパーティ統合まで。
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
},
...
]
}
ワークスペースのMCPサーバーを有効化します。サーバーの定義に従い、設定値(APIキーなど)を入力してください。 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" } }'
{
"id": "act-uuid-...",
"server_id": "550e8400-...",
"status": 1,
"config": {
"api_key": "••••••••"
},
"server": {
"name": "GitHub",
...
},
"created_at": "2026-03-01T12:00:00Z"
}
id は activation_id MCPサーバーをエージェントにリンクする際に使用します。
ワークスペースで有効化されたすべてのMCPサーバーを一覧表示します。
アクティベーションの設定またはステータスを更新します。
ワークスペースからMCPサーバーを無効化します。
エージェント
複数のコミュニケーションチャネルで動作する自律型AIエージェントを作成・管理します。エージェントはTelegramやDiscordのメッセージに応答し、スケジュールされたトリガーで実行され、ナレッジベースやMCPサーバーを活用して機能を拡張できます。
新しいエージェントを作成します。
リクエストボディ
| パラメータ | タイプ | 説明 |
|---|---|---|
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" }'
{
"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": []
}
ワークスペース内のすべてのエージェントを一覧表示します。ページネーションとフィルタリングをサポートします。
| パラメータ | タイプ | 説明 |
|---|---|---|
limitquery |
整数 | ページあたりの結果数。デフォルト: 25 |
cursorquery |
string | ページネーションカーソル |
sortquery |
string | "name"、"created_at"、または"last_active_at"。デフォルト: "created_at" |
directionquery |
string | "asc"または"desc" |
statusquery |
整数 | ステータスでフィルタリング: 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,
...
}
]
}
チャンネル、リンクされたMCPサーバー、ナレッジベースを含む、特定のエージェントの完全な詳細を取得します。
エージェントを更新します。すべてのフィールドは任意です — 提供されたフィールドのみが変更されます。
リクエストボディ
| パラメータ | タイプ | 説明 |
|---|---|---|
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
}
}
}
エージェントを削除します。これにより、関連するすべてのチャンネル、トリガー、メッセージ、連携も削除されます。
インテグレーション
RAGを活用した応答のために、ナレッジベースをエージェントにリンクします。本文: { "knowledge_base_id": "uuid" }
エージェントからナレッジベースのリンクを解除します。
拡張ツール利用のために、MCPサーバーをエージェントにリンクします。本文: { "activation_id": "uuid" }
エージェントからMCPサーバーのリンクを解除します。
エージェントの会話履歴を取得します。
| パラメータ | タイプ | 説明 |
|---|---|---|
limitquery |
整数 | 返すメッセージの数。デフォルト: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
}
]
}
エージェントチャネル
エージェントをコミュニケーションプラットフォームに接続。各エージェントはタイプごとに1つのチャネルをサポートします(Telegramボット1つ、Discordボット1つ)。
エージェントに通信チャネルを追加します。
リクエストボディ
| パラメータ | タイプ | 説明 |
|---|---|---|
type必須 |
string | "telegram"または"discord" |
token必須 |
string | Telegram BotFatherまたはDiscord Developer PortalからのBotトークン(最大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..." }'
{
"id": "ch-uuid-...",
"type": "telegram",
"status": 1,
"metadata": {},
"last_error": null,
"last_message_at": null,
"created_at": 1709136000
}
エージェントに接続されたすべてのチャネルを一覧表示します。
エージェントからチャンネルを削除します。
エージェントトリガー
トリガーでエージェントのアクションを自動化します。スケジュールトリガーはcron式を使用して特定の時刻に実行され、イベントトリガーは外部イベントに応じて発火します。
エージェントの自動トリガーを作成します。
リクエストボディ
| パラメータ | タイプ | 説明 |
|---|---|---|
name必須 |
string | トリガー名(最大128文字) |
type必須 |
string | "scheduled"または"event" |
prompt必須 |
string | トリガー発火時にエージェントに送信されるプロンプト |
cron_expression任意 |
string | Cronスケジュール(例:平日午前9時の場合は「0 9 * * 1-5」) |
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" }'
{
"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
}
エージェントのすべてのトリガーを一覧表示します。
トリガーを更新します。すべてのフィールドは任意です。無効化するには status 無効にするには0、有効にするには1を設定します。
トリガーを削除します。
ワークスペース
ワークスペースはチームの組織単位です。各ワークスペースには独自のクレジット残高、サブスクリプション、APIキー、メンバーがあります。ワークスペースの管理、チームメンバーの招待、使用状況の追跡が行えます。
新しいワークスペースを作成します。
| パラメータ | タイプ | 説明 |
|---|---|---|
name必須 |
string | ワークスペース名(最大50文字) |
{
"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"
}
ワークスペースの設定を更新します。ワークスペース管理権限が必要です。
| パラメータ | タイプ | 説明 |
|---|---|---|
name任意 |
string | ワークスペース名(最大50文字) |
api_spending_limit任意 |
数値 | 月間API利用上限額(無制限の場合はnull) |
{provider}_api_key任意 |
string | プロバイダー用のBYOK APIキー(例: openai_api_key, anthropic_api_key) |
ワークスペースを削除します。ワークスペース管理権限が必要です。
メールでユーザーをワークスペースに招待します。ワークスペースあたりの保留中の招待は最大20件です。
| パラメータ | タイプ | 説明 |
|---|---|---|
email必須 |
string | 招待するユーザーのメールアドレス |
保留中の招待をキャンセルします。
ワークスペースからメンバーを削除するか、自身のユーザーIDを使用してワークスペースから退出します。
ワークスペースの集計利用統計を一覧表示します。カーソルベースのページネーションをサポートします。
項目別の利用エントリ(コスト付きの完了したライブラリアイテム)を一覧表示します > 0)。各エントリにはタイプ、モデル、タイトル、コスト、タイムスタンプが含まれます。
使用量アイテムの総数を取得します。
会話
会話はチャットメッセージをセッションにグループ化します。まず会話を作成し、そこにメッセージを送信します。会話は、コンテンツタイプを使用してライブラリAPIを通じて管理することもできます。 ライブラリ APIを使用して conversations コンテンツタイプ。
新しい会話を作成します。空のメッセージリストを持つ会話オブジェクトを返します。
{
"object": "conversation",
"id": "550e8400-...",
"title": null,
"cost": 0,
"messages": [],
"created_at": "2026-03-01T12:00:00Z"
}
会話にメッセージを送信し、Server-Sent Events(SSE)経由でAIの応答を受信します。詳細は チャットコンプリーション SSEイベント形式の詳細については、チャットコンプリートセクションを参照してください。
リクエストボディ
| パラメータ | タイプ | 説明 |
|---|---|---|
model必須 |
string | レスポンスに使用するモデル |
content任意 |
string | メッセージテキスト |
assistant_id任意 |
string | このメッセージに使用するアシスタントのUUID |
parent_id任意 |
string | 親メッセージのUUID(分岐会話用) |
file任意 |
ファイル | 添付ファイル(画像、ドキュメント、音声/動画) — 最大25MB) |
recording任意 |
ファイル | 音声録音(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" }'
multipart/form-data ファイルのアップロード時。会話の一覧表示または削除には、 ライブラリ タイプ付きAPI conversations.
アカウント
ユーザープロフィールを管理し、APIキーをプログラムで生成します。
プロフィール情報を更新します。
| パラメータ | タイプ | 説明 |
|---|---|---|
first_name任意 |
string | 名(最大50文字) |
last_name任意 |
string | 姓(最大50文字) |
language任意 |
string | 優先言語コード(例:"en"、"fr") |
preferences任意 |
オブジェクト | ユーザー設定 |
新しいAPIキーを生成します。セキュリティのためパスワード確認が必要です。完全なAPIキーが返されます 1回のみ このレスポンス内 — 安全に保管します。
| パラメータ | タイプ | 説明 |
|---|---|---|
current_password必須 |
string | 現在のアカウントパスワード |
{
"id": "550e8400-...",
"first_name": "Jane",
"last_name": "Doe",
"email": "jane@example.com",
"api_key": "zub_live_a1b2c3d4e5f6..."
}
api_key 値はこのレスポンスでのみ完全に表示されます。以降のAPI呼び出しではマスクされたバージョンが返されます。パスワードと同様に扱ってください。
請求
利用可能なプランを閲覧し、注文履歴を確認し、チェックアウトを開始し、サブスクリプションを管理します。
利用可能なサブスクリプションプランを一覧表示します。
| パラメータ | タイプ | 説明 |
|---|---|---|
billing_cycle任意 |
string | 請求サイクルでフィルタリング |
現在のワークスペースの注文を一覧表示します。カーソルベースのページネーションをサポートします。
| パラメータ | タイプ | 説明 |
|---|---|---|
status任意 |
string | 注文ステータスでフィルタリング |
billing_cycle任意 |
string | 請求サイクルでフィルタリング |
サブスクリプションプランまたはクレジット購入のチェックアウトを開始します。ワークスペースの管理権限が必要です。
| パラメータ | タイプ | 説明 |
|---|---|---|
id任意 |
string | サブスクライブするプランのUUID(以下がない場合は必須: amount) |
amount任意 |
整数 | セント単位のクレジット購入金額(最低1000、次の条件がない場合は必須: id) |
gateway任意 |
string | 決済ゲートウェイ: stripe または paypal |
現在のワークスペースのサブスクリプションをキャンセルします。ワークスペース管理権限が必要です。
コンテンツレポート
公開ライブラリ内の不適切なコンテンツまたはポリシーに違反するコンテンツを報告します。
コンテンツレポートを提出します。各ユーザーは特定のアイテムについて1回のみ報告できます。
| パラメータ | タイプ | 説明 |
|---|---|---|
item_id必須 |
string | 報告するライブラリアイテムのUUID |
reason必須 |
整数 | 理由コード:0(スパム)、1(嫌がらせ)、2(暴力)、3(性的コンテンツ)、4(その他) |
description任意 |
string | 追加の詳細(最大2,000文字) |
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
409 Conflict エラー。
その他のエンドポイント
完全なサーフェスは上記のセクションよりも広範です。これらのエンドポイントは稼働中であり、同じ認証を使用します。
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会話) |
POST /api/graphql · GET /api/graphql/subscriptions | GraphQL API(クエリ+サブスクリプション) |
/api/automation | 自動化ワークフロー(構築+実行) |
エラー
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 |
1分あたりの許可リクエスト数 |
X-RateLimit-Remaining |
現在のウィンドウ内の残りリクエスト数 |
X-RateLimit-Reset |
制限がリセットされるUnixタイムスタンプ |
レート制限に達した場合は、リセット時刻まで待機するか、制限の引き上げについてお問い合わせください。