APIドキュメント

はじめに

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プロバイダー

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

モデル

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任意 整数 生成する最大トークン数(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", ...}

コード生成

POST /api/ai/completions/code

自然言語プロンプトからコードを生成します。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"
  }'
このエンドポイントは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 gemini-2.5-flash-image 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",
      "revised_prompt": "A serene mountain lake..."
    }
  ]
}

動画生成

POST /api/ai/videos

テキストプロンプトまたは画像から動画を生成。テキストから動画、画像から動画、動画から動画のワークフローをサポート。

利用可能なモデル

sora-2 seedance-2.0 kling-v3-pro veo-3.1-generate-001 grok-imagine-video-1.5 minimax/hailuo-2.3 pixverse-v6 vidu-q3-pro

リクエストボディ

パラメータ タイプ 説明
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を提出して分析を依頼し、結果をポーリングします。複数の分析タイプをサポートしています。

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 minimax/music-2.0 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秒クリップを1つ返します。
レスポンス
[
  {
    "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 音声に変換するテキスト(最大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

文字起こし

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 Text-to-Speechエンドポイントのパラメータ。

埋め込み

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)をアップロードするか、Web 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)
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..."
  }'
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 の最後の項目の 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)サーバーを閲覧して有効化し、エージェントに拡張ツール機能を提供 — Web検索やデータアクセスからコード実行、サードパーティ統合まで。

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サーバーを有効化します。サーバーの定義に従い、設定値(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"
    }
  }'
レスポンス(201 Created)
{
  "id": "act-uuid-...",
  "server_id": "550e8400-...",
  "status": 1,
  "config": {
    "api_key": "••••••••"
  },
  "server": {
    "name": "GitHub",
    ...
  },
  "created_at": "2026-03-01T12:00:00Z"
}
設定内のシークレットフィールドはAPIレスポンスでマスクされます。各ワークスペースは特定のサーバーを1回のみアクティブ化できます。返される idactivation_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 Created)
{
  "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

ワークスペース内のすべてのエージェントを一覧表示します。ページネーションとフィルタリングをサポートします。

パラメータ タイプ 説明
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,
      ...
    }
  ]
}
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

エージェントの会話履歴を取得します。

パラメータ タイプ 説明
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つ)。

POST /api/agents/{id}/channels

エージェントに通信チャネルを追加します。

リクエストボディ

パラメータ タイプ 説明
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..."
  }'
レスポンス(201 Created)
{
  "id": "ch-uuid-...",
  "type": "telegram",
  "status": 1,
  "metadata": {},
  "last_error": null,
  "last_message_at": null,
  "created_at": 1709136000
}
Botトークンは有効化前にプラットフォーム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スケジュール(例:平日午前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"
  }'
レスポンス(201 Created)
{
  "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 Created)
{
  "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)。各エントリにはタイプ、モデル、タイトル、コスト、タイムスタンプが含まれます。

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

使用量アイテムの総数を取得します。

利用状況およびワークスペース管理のエンドポイントにはワークスペースが必要です 管理 権限(ワークスペースのオーナーまたは管理者)。

会話

会話はチャットメッセージをセッションにグループ化します。まず会話を作成し、そこにメッセージを送信します。会話は、コンテンツタイプを使用してライブラリAPIを通じて管理することもできます。 ライブラリ 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)
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"
  }'
メッセージはSSEでストリーミングされます。使用: multipart/form-data ファイルのアップロード時。会話の一覧表示または削除には、 ライブラリ タイプ付きAPI 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キーが返されます 1回のみ このレスポンス内 — 安全に保管します。

パラメータ タイプ 説明
current_password必須 string 現在のアカウントパスワード
レスポンス
{
  "id": "550e8400-...",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane@example.com",
  "api_key": "zub_live_a1b2c3d4e5f6..."
}
この 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

コンテンツレポートを提出します。各ユーザーは特定のアイテムについて1回のみ報告できます。

パラメータ タイプ 説明
item_id必須 string 報告するライブラリアイテムのUUID
reason必須 整数 理由コード:0(スパム)、1(嫌がらせ)、2(暴力)、3(性的コンテンツ)、4(その他)
description任意 string 追加の詳細(最大2,000文字)
レスポンス(201 Created)
{
  "id": "550e8400-e29b-41d4-a716-446655440000"
}
重複レポート(同じユーザー+同じ項目)は次を返します: 409 Conflict エラー。

その他のエンドポイント

完全なサーフェスは上記のセクションよりも広範です。これらのエンドポイントは稼働中であり、同じ認証を使用します。

POST /api/ai/three-d3Dモデル生成(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/subscriptionsGraphQL 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タイムスタンプ

レート制限に達した場合は、リセット時刻まで待機するか、制限の引き上げについてお問い合わせください。

サポートが必要ですか?

いつでもサポートいたします

APIについてご質問がありますか?FAQをご確認いただくか、直接お問い合わせください。