素材ライブラリ

素材ライブラリは、サイトごとに画像・PDF・テキスト・動画・音声のファイルを保管する場所です。アップロードした素材は「公開」にすると誰でも取得できるURLで配信され、コンテンツやコレクションの値から参照できます。非公開の素材は、ログイン中の所有者だけが取得できます。

アップロードする

サイト画面の「素材ライブラリ」を開き、ファイルを選んで「アップロード」を押します。

項目	内容
使えるファイル	画像（JPEG `.jpg` `.jpeg`、PNG `.png`、GIF `.gif`、WebP `.webp`）、PDF `.pdf`、テキスト `.txt`、動画（MP4 `.mp4`、WebM `.webm`）、音声（MP3 `.mp3`、WAV `.wav`）
サイズ	1ファイル 20 MB まで
公開設定	「公開URLで取得可能にする」にチェックすると公開素材になります。チェックしない場合は非公開です（初期状態）。
名前	アップロードしたファイル名がそのまま素材名になります。

SVG はアップロードできません。

名前と公開設定を変える

素材の一覧で名前（255文字まで）を書き換えたり、「公開」のチェックを切り替えたりして「保存」を押します。名前は、素材をダウンロードしたときのファイル名として使われます。素材のURLは変わりません。

公開URL

各素材の「取得」リンクが、その素材のURLです。

https://cms.magichtml.dev/assets/<素材ID>

公開設定	取得できる人
公開	誰でも（ログイン不要）
非公開	その素材を持つサイトの所有者（ログイン中）のみ。それ以外は 404 になります。

配信のされ方は次のとおりです。

画像・動画・音声はブラウザ内で表示・再生されます。PDF とテキストはダウンロードとして配信されます。
レスポンスには Cache-Control: no-store が付くため、公開設定の変更や削除はすぐに反映されます。
素材は X-Frame-Options: DENY 付きで配信されるため、<iframe> の中には表示できません。画像は <img>、動画は <video>、音声は <audio> で参照してください。

コンテンツの値から参照する

素材を静的サイトに表示するには、素材を「公開」にしたうえで、そのURLをコンテンツやコレクションの値に入れます。

素材ライブラリで素材を「公開」にします。
「取得」リンクのURLをコピーします。
リソースの「素材URL」型の項目に、そのURLを入力して保存し、公開します。

const cms = new MagicCMS('https://cms.magichtml.dev', 'SITE_ID');
const data = await cms.get('about');
const image = document.querySelector('#hero');
const src = data.records[0].values.hero_image;
// /assets/ で始まるパスの場合は Magic CMS Cloud のURLを前に付けます
image.src = src.startsWith('/') ? 'https://cms.magichtml.dev' + src : src;

「素材URL」型には、http://・https:// で始まるURL、または /assets/ で始まるパスを保存できます。
データの受け渡し（ZIP）で取り込んだ素材への参照は、/assets/<素材ID> の形のパスになります。静的サイトのページから参照するときは、上の例のように https://cms.magichtml.dev を前に付けてください。
「装飾文（HTML）」「文書（HTML）」の <a href> や「リンク」型の値から素材のURLを指すこともできます（PDF のダウンロードリンクなど）。
非公開の素材を参照しても、静的サイトの訪問者には表示されません。

削除する

素材の「削除」を押すと、ファイルと素材の情報が削除されます。その素材を参照しているURLは使えなくなる（404 になる）ため、先にコンテンツ側の参照を差し替えてから削除してください。サイトを削除した場合も、そのサイトの素材はすべて削除されます。

管理APIでの操作

管理API では、素材のアップロードと削除ができます（名前と公開設定の変更は管理画面で行います）。

curl -X POST 'https://cms.magichtml.dev/api/v1/sites/SITE_ID/assets' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -F 'file=@hero.jpg' \
  -F 'is_public=1'

レスポンスの data.id が素材IDです。