コンテンツへスキップ
Wbiztool

メディアAPI

メディアファイル一覧API

ワークスペースのメディアライブラリにあるファイルを、ダウンロードURLとともに新しい順に取得します。種類で絞り込んだり名前で検索したりして、以前アップロードしたファイルを見つけ、そのURLをメッセージで再利用できます。

GEThttps://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=20

12345YOUR_API_KEYはご自身の値に置き換えてください。値の確認場所は認証をご覧ください。

リクエストパラメータ#

パラメータは、GETリクエストのクエリ文字列で送信するか、Content-Type: application/jsonを指定したPOSTリクエストのJSONボディで送信します。両方を混在させないでください。client_idがクエリ文字列にある場合、JSONボディは無視されます。フォーム形式のPOSTでもclient_idapi_keyfile_typesearchは機能しますが、フォームフィールドのpagelimitは無視されます。これらはクエリ文字列または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任意

元のファイル名または保存名にこのテキストを含むファイルのみを返します。大文字と小文字は区別されません。

JSONボディでPOSTするcURL
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]"
      }
    ]
  }
}
フィールド説明
statusinteger成功時は1、リクエストが失敗した場合は0
messagestringMedia files retrieved successfully、それ以外はエラー内容。
data.total_countinteger全ページを通じた、フィルターに一致するファイルの数。
data.pageinteger返されたページ。
data.limitinteger1〜100の範囲に調整された後の、使用されたページサイズ。
data.total_pagesintegerページ数。ファイルがない場合は0
data.has_nextbooleanこのページの後にページがある場合はtrue
data.has_previousbooleanpageが1より大きい場合はtrue
data.media_filesarrayこのページのファイル(新しい順)。ページが末尾を超えている場合は空です。

メディアファイルのフィールド#

フィールド説明
idintegerメディアファイルのID。メディアファイルの取得で使用します。
file_namestringファイルの保存名。
original_file_namestringアップロード時のファイル名。
file_urlstring直接ダウンロードURL。送信時にimg_urlまたはfile_urlとして使用します。
file_typestringimageまたはfile
file_sizeintegerサイズ(バイト)。
file_size_displaystring小数点以下1桁の読みやすいサイズ(例:512.0 KB)。
mime_typestringMIMEタイプ(例:image/jpeg)。
is_imagebooleanfile_typeimageの場合はtrue
file_extensionstringoriginal_file_nameの小文字の拡張子(ドットなし)。
created_atstringアップロード日時。+00:00オフセット付きのUTCのISO 8601形式です。
uploaded_bystring or nullファイルをアップロードしたチームメンバーのログインユーザー名(通常はメールアドレス)。

エラー#

エラーの場合もHTTP 200が返り、status0になります。

{ "status": 0, "message": "Invalid API key" }
メッセージ対処方法
client_id is requiredclient_idを追加してください。JSONを送信する場合は、ボディが有効なJSONであることを確認してください(解析エラーはこのメッセージとして返されます)。
api_key is requiredapi_keyを追加してください。
client_id must be a valid integerclient_idを数値で送信してください。
Invalid API keyキーが存在し、削除または無効化されていないことを確認してください。
Invalid client_id for this API keyキーが別のclient_idに属しています。
Error retrieving media files: …通常は、クエリ文字列またはフォームフィールドのpageまたはlimitが整数ではありません。JSONボディの場合はエラーになりません。pageが整数でなければ、pagelimitfile_typesearchはすべて無視され、フィルターなしで1ページ目の20件のファイルが返されます。limitだけが整数でない場合は、limitfile_typesearchが無視されます。

すべてのページを読み取る#

data.has_nexttrueの間、次のページをリクエストし続けます。

すべてのメディアファイルを取得する
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")

ヒント#

  • 正しい送信パラメータを使うis_imagetrueの場合はURLをmsg_type 1でimg_urlとして、それ以外の場合はmsg_type 2でfile_urlとして送信してください。メッセージ送信をご覧ください。
  • APIキーをログに残さない:クエリ文字列はプロキシやサーバーでログに記録されることがよくあります。気になる場合は、代わりにJSONボディでPOSTを使用してください。