メディアAPI
メディアファイル一覧API
ワークスペースのメディアライブラリにあるファイルを、ダウンロードURLとともに新しい順に取得します。種類で絞り込んだり名前で検索したりして、以前アップロードしたファイルを見つけ、そのURLをメッセージで再利用できます。
https://wbiztool.com/api/v1/media/list/リクエストボディ: クエリ文字列、またはPOSTの場合はJSONボディ
一覧には、メディアのアップロードAPIでアップロードしたファイルと、メディアディレクトリページでアップロードしたファイルが含まれます。削除されたファイルは含まれません。
クイック例#
curl -G https://wbiztool.com/api/v1/media/list/ \
--data-urlencode client_id=12345 \
--data-urlencode api_key=YOUR_API_KEY \
--data-urlencode file_type=image \
--data-urlencode page=1 \
--data-urlencode limit=20import requests
response = requests.get(
"https://wbiztool.com/api/v1/media/list/",
params={
"client_id": 12345,
"api_key": "YOUR_API_KEY",
"file_type": "image",
"page": 1,
"limit": 20,
},
timeout=60,
)
result = response.json()
if result["status"] == 1:
data = result["data"]
print(f"Page {data['page']} of {data['total_pages']} ({data['total_count']} files)")
for media in data["media_files"]:
print(media["id"], media["original_file_name"], media["file_url"])
else:
print("Failed:", result["message"])// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const url = new URL("https://wbiztool.com/api/v1/media/list/");
url.search = new URLSearchParams({
client_id: "12345",
api_key: "YOUR_API_KEY",
file_type: "image",
page: "1",
limit: "20",
});
const response = await fetch(url);
const result = await response.json();
if (result.status === 1) {
const { data } = result;
console.log(`Page ${data.page} of ${data.total_pages} (${data.total_count} files)`);
for (const media of data.media_files) {
console.log(media.id, media.original_file_name, media.file_url);
}
} else {
console.error("Failed:", result.message);
}<?php
$query = http_build_query([
'client_id' => 12345,
'api_key' => 'YOUR_API_KEY',
'file_type' => 'image',
'page' => 1,
'limit' => 20,
]);
$ch = curl_init('https://wbiztool.com/api/v1/media/list/?' . $query);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 60,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
if (($result['status'] ?? 0) === 1) {
foreach ($result['data']['media_files'] as $media) {
echo $media['id'] . ' ' . $media['original_file_name'] . ' ' . $media['file_url'] . "\n";
}
} else {
echo 'Failed: ' . ($result['message'] ?? 'no response');
}12345とYOUR_API_KEYはご自身の値に置き換えてください。値の確認場所は認証をご覧ください。
リクエストパラメータ#
パラメータは、GETリクエストのクエリ文字列で送信するか、Content-Type: application/jsonを指定したPOSTリクエストのJSONボディで送信します。両方を混在させないでください。client_idがクエリ文字列にある場合、JSONボディは無視されます。フォーム形式のPOSTでもclient_id、api_key、file_type、searchは機能しますが、フォームフィールドのpageとlimitは無視されます。これらはクエリ文字列またはJSONで送信してください。
認証
client_idinteger必須設定 → APIキーに表示されるAPIクライアントIDです。
api_keystring必須同じページにあるAPIキーです。
フィルターとページネーション
pageinteger任意ページ番号で、
1(デフォルト)から始まります。1未満の値は1として扱われます。limitinteger任意1ページあたりのファイル数で、1〜100です。デフォルトは
20です。100を超える値は100として、1未満の値は20として扱われます。file_typestring任意画像のみの場合は
image、それ以外のすべての場合はfile。その他の値は無視されます。searchstring任意元のファイル名または保存名にこのテキストを含むファイルのみを返します。大文字と小文字は区別されません。
curl -X POST https://wbiztool.com/api/v1/media/list/ \
-H "Content-Type: application/json" \
-d '{
"client_id": 12345,
"api_key": "YOUR_API_KEY",
"search": "invoice",
"page": 1,
"limit": 50
}'レスポンス#
{
"status": 1,
"message": "Media files retrieved successfully",
"data": {
"total_count": 1,
"page": 1,
"limit": 20,
"total_pages": 1,
"has_next": false,
"has_previous": false,
"media_files": [
{
"id": 5123,
"file_name": "media_12345_17895806123456.jpg",
"original_file_name": "diwali-sale.jpg",
"file_url": "https://wbiztool-static.s3.ap-southeast-1.amazonaws.com/media/org_12345/media_12345_17895806123456.jpg",
"file_type": "image",
"file_size": 524288,
"file_size_display": "512.0 KB",
"mime_type": "image/jpeg",
"is_image": true,
"file_extension": "jpg",
"created_at": "2026-09-16T10:23:52.106447+00:00",
"uploaded_by": "[email protected]"
}
]
}
}
| フィールド | 型 | 説明 |
|---|---|---|
status | integer | 成功時は1、リクエストが失敗した場合は0。 |
message | string | Media files retrieved successfully、それ以外はエラー内容。 |
data.total_count | integer | 全ページを通じた、フィルターに一致するファイルの数。 |
data.page | integer | 返されたページ。 |
data.limit | integer | 1〜100の範囲に調整された後の、使用されたページサイズ。 |
data.total_pages | integer | ページ数。ファイルがない場合は0。 |
data.has_next | boolean | このページの後にページがある場合はtrue。 |
data.has_previous | boolean | pageが1より大きい場合はtrue。 |
data.media_files | array | このページのファイル(新しい順)。ページが末尾を超えている場合は空です。 |
メディアファイルのフィールド#
| フィールド | 型 | 説明 |
|---|---|---|
id | integer | メディアファイルのID。メディアファイルの取得で使用します。 |
file_name | string | ファイルの保存名。 |
original_file_name | string | アップロード時のファイル名。 |
file_url | string | 直接ダウンロードURL。送信時にimg_urlまたはfile_urlとして使用します。 |
file_type | string | imageまたはfile。 |
file_size | integer | サイズ(バイト)。 |
file_size_display | string | 小数点以下1桁の読みやすいサイズ(例:512.0 KB)。 |
mime_type | string | MIMEタイプ(例:image/jpeg)。 |
is_image | boolean | file_typeがimageの場合はtrue。 |
file_extension | string | original_file_nameの小文字の拡張子(ドットなし)。 |
created_at | string | アップロード日時。+00:00オフセット付きのUTCのISO 8601形式です。 |
uploaded_by | string or null | ファイルをアップロードしたチームメンバーのログインユーザー名(通常はメールアドレス)。 |
エラー#
エラーの場合もHTTP 200が返り、statusは0になります。
{ "status": 0, "message": "Invalid API key" }
| メッセージ | 対処方法 |
|---|---|
client_id is required | client_idを追加してください。JSONを送信する場合は、ボディが有効なJSONであることを確認してください(解析エラーはこのメッセージとして返されます)。 |
api_key is required | api_keyを追加してください。 |
client_id must be a valid integer | client_idを数値で送信してください。 |
Invalid API key | キーが存在し、削除または無効化されていないことを確認してください。 |
Invalid client_id for this API key | キーが別のclient_idに属しています。 |
Error retrieving media files: … | 通常は、クエリ文字列またはフォームフィールドのpageまたはlimitが整数ではありません。JSONボディの場合はエラーになりません。pageが整数でなければ、page、limit、file_type、searchはすべて無視され、フィルターなしで1ページ目の20件のファイルが返されます。limitだけが整数でない場合は、limit、file_type、searchが無視されます。 |
すべてのページを読み取る#
data.has_nextがtrueの間、次のページをリクエストし続けます。
import requests
files, page = [], 1
while True:
result = requests.get(
"https://wbiztool.com/api/v1/media/list/",
params={"client_id": 12345, "api_key": "YOUR_API_KEY", "page": page, "limit": 100},
timeout=60,
).json()
if result["status"] != 1:
raise RuntimeError(result["message"])
files += result["data"]["media_files"]
if not result["data"]["has_next"]:
break
page += 1
print(len(files), "files")// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const files = [];
let page = 1;
while (true) {
const url = new URL("https://wbiztool.com/api/v1/media/list/");
url.search = new URLSearchParams({ client_id: "12345", api_key: "YOUR_API_KEY", page: String(page), limit: "100" });
const result = await (await fetch(url)).json();
if (result.status !== 1) throw new Error(result.message);
files.push(...result.data.media_files);
if (!result.data.has_next) break;
page += 1;
}
console.log(files.length, "files");ヒント#
- 正しい送信パラメータを使う:
is_imageがtrueの場合はURLをmsg_type1でimg_urlとして、それ以外の場合はmsg_type2でfile_urlとして送信してください。メッセージ送信をご覧ください。 - APIキーをログに残さない:クエリ文字列はプロキシやサーバーでログに記録されることがよくあります。気になる場合は、代わりにJSONボディで
POSTを使用してください。
