Tessera
ログイン無料で始める
ドキュメント一覧

メディアAPI

概要

画像やファイルを、APIキーを使ってプログラム的にアップロードできます。CI・スクリプト・ AIエージェントから、管理画面を開かずにメディアを投入する用途に使えます。ファイルはmultipart/form-dataでそのまま送るため、Base64エンコードは不要です。

MCPの upload_asset はBase64（最大5MB）でファイルを渡す方式で、AIエージェントの実行環境から小さなファイルを入れるのに 適しています。大きめのファイルや、curl・スクリプトからの投入にはこのメディアAPIが向いています。

アップロード

POST /api/assets に multipart/form-data で送信します。

フィールド内容
file（必須）アップロードするファイル本体
visibility（任意）public（既定）または private。public は永続の直リンク、private は 署名付きURL（短命）でのみ配信されます
curl -X POST https://tesseracms.com/api/assets \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@./cover.png" \
  -F "visibility=public"

成功時は HTTP 201 と、作成されたアセット（配信URLを含む）が返ります。

{
  "asset": {
    "id": "1d033150-a6d8-475b-b418-08d342aaa88a",
    "fileName": "cover.png",
    "mimeType": "image/png",
    "sizeBytes": 179402,
    "visibility": "public",
    "url": "https://media.tesseracms.com/<workspaceId>/1d033150-a6d8-475b-b418-08d342aaa88a.png",
    "createdAt": "2026-08-07T05:52:56.088Z"
  }
}

返ってきた url をそのまま記事本文やOGP画像などに使えます。

認証

アップロード（POST /api/assets）は、次のどちらの認証でも受け付けます。

  • APIキー: Authorization: Bearer <APIキー>。read_write スコープが必須です（read_only キーは 403）。
  • セッションCookie: 管理画面からのアップロードで使われます（ブラウザ経由）。

なお、メディアの一覧・削除・公開/非公開の切り替え・配信（GET/DELETE/PATCH /api/assets/*）は管理画面向けのセッション認証専用です。APIキーで一覧を取得したい場合は、MCPの list_assets を利用してください。

制約・仕様

  • サイズ上限: 1ファイルあたり最大 20MB（MCPのBase64経路は別軸で約5MB上限）。
  • 対応形式: image/*（image/svg+xml を除く）・application/pdf・video/mp4・video/webm・text/plain・text/csv。申告MIMEだけでなく実バイトも検査します。
  • 画像の最適化: 画像は保存時に自動で圧縮される場合があります（返却される sizeBytes は最適化後の値）。
  • レート制限・容量上限: ワークスペース単位のアップロード回数制限と、プラン別の メディア合計容量上限が適用されます。

エラーケース

認証・スコープ不足

HTTP 401 / 403

認証情報が無い・APIキーが不正な場合は 401。有効なキーだがスコープが read_write でない場合は 403（read_write スコープのAPIキーが必要です）。

サイズ超過・非対応形式

HTTP 400 / 413

20MB超は file_too_large、許可されない形式は unsupported_media_type、実バイトが申告と異なる/非対応の 場合は unsupported_file_content（いずれも 400）。メディア 合計容量の上限に達している場合は storage_limit_reached（413）。

レート制限

HTTP 429

アップロード回数の上限に達すると 429 を返します（Retry-After ヘッダに再試行可能までの秒数）。

関連ドキュメント