メディアを扱う
この機能は Ver. 3.3.0 で追加予定の、リリース前の機能です
このページは、アルファ版(Ver. 3.3.0-alpha.1)時点の内容です。正式版までに仕様や設定項目が変わる可能性があります。本番サイトでは使わず、検証環境でお試しください。
メディア(メディアライブラリの画像・SVG・ファイル)を REST API で扱います。エントリーの本文の画像やファイルは、メディアとして登録してから ID で参照します。
操作 | メソッドとパス | スコープ | 成功 |
|---|---|---|---|
一覧 |
|
| 200 |
取得 |
|
| 200( |
アップロード |
|
| 201 |
URL から取り込み |
|
| 201 |
ファイルの差し替え |
|
| 201 |
項目の更新 |
|
| 200 |
削除 |
|
| 204 |
アップロードする
ファイルを file の項目で、multipart/form-data で送ります。管理画面のアップロードと同じ規則(拡張子・大きさの上限・画像のリサイズ・SVG のサニタイズ)で保存します。
curl -s -i -X POST "${ACMS_API}/media/" \
-H "Authorization: Bearer ${ACMS_API_TOKEN}" \
-F "file=@sample.png;type=image/png" \
-F "alt=サンプルの画像" \
-F "caption=REST API からアップロード" \
-F "tags=サンプル,photo"HTTP/2 201
content-type: application/json; charset=utf-8
location: https://example.com/rest-api/acms/v1/media/36/{
"id": 36,
"type": "image",
"extension": "PNG",
"file_name": "sample.png",
"file_size": 146,
"image_size": { "width": 64, "height": 40 },
"url": "https://example.com/media/001/202611/sample.png",
"thumbnail_url": "https://example.com/media/001/202611/tiny-sample.png",
"tags": ["サンプル", "photo"],
"status": null,
"upload_datetime": "2026-11-12T13:44:22+09:00",
"update_datetime": "2026-11-12T13:44:22+09:00",
"user_id": 1,
"blog_id": 1,
"fields": { "caption": "REST API からアップロード", "link": null, "alt": "サンプルの画像", "text": null, "focal_point": null, "page": null },
"links": {
"self": "https://example.com/rest-api/acms/v1/media/36/",
"blog": "https://example.com/rest-api/acms/v1/blogs/1/",
"user": "https://example.com/rest-api/acms/v1/users/1/"
}
}アップロードで送れる項目
項目 | 説明・入力例 |
|---|---|
| 必須。アップロードするファイル |
| ファイル名(省略時は送ったファイルの名前) |
| ファイル(画像・SVG 以外)の公開範囲。 |
| タグ(カンマ区切り)。例: |
| キャプション / リンク / 代替テキスト / 説明 |
| 焦点 |
| PDF のサムネイルにするページ |
JSON の本文の上限(rest_api_max_body_size、2 MiB)は、multipart のアップロードには掛かりません。multipart のリクエスト全体の上限は PHP の post_max_size、ファイルの大きさは upload_max_filesize と管理画面のアップロードの規則に従います。
URL から取り込む
サーバーが URL のファイルを取得して、アップロードと同じ規則で保存します。本文は JSON です。
curl -s -X POST "${ACMS_API}/media/import/" \
-H "Authorization: Bearer ${ACMS_API_TOKEN}" -H "Content-Type: application/json" \
-d '{"url":"https://images.example.net/photos/ogp.png","name":"ogp.png","alt":"取り込んだ画像","tags":["取り込み"]}'項目 | 説明 |
|---|---|
| 必須。取り込むファイルの URL( |
| ファイル名(拡張子つき)。省略時は URL のパスの最後の名前(拡張子が無い URL では必須) |
| アップロードと同じ |
| 文字列の配列 |
| 文字列( |
| 1 以上の整数 |
大きさは
upload_max_filesizeまで、取得の時間は 30 秒までです。取得できない場合は 422 で、
errors[].codeが理由を示します。内部のアドレスなどはrejected(「この URL からは取得できません。」)、取得先がエラーを返したときはhttp_status(「取得先がステータス 404 を返しました。」など)です。?dry_run=1では取得せずに、URL とファイル名の検査と、拡張子から推定した種類の表現を返します。取得できるかどうかは、dry-run では分かりません。
項目を更新する・ファイルを差し替える
キャプションやタグは PATCH で変えます。書き込みの項目は表現と形が違い、fields の中身を最上位で送ります。
curl -s -X PATCH "${ACMS_API}/media/36/" \
-H "Authorization: Bearer ${ACMS_API_TOKEN}" -H "Content-Type: application/json" \
-d '{"alt":"青い長方形のサンプル画像","tags":["サンプル","青"],"focal_point":"50,50"}'項目 | 説明 |
|---|---|
| ファイル名。拡張子は元のファイルのものになります |
| ファイル( |
| 配列ごと置き換えます |
|
|
|
|
| PDF のサムネイルのページ |
ファイルだけを新しいものに入れ替えるときは、POST /media/{id}/replace を使います。メディアの ID・タグ・キャプションなど・アップロードの日時を保ったまま入れ替えるため、本文などからの参照は新しいファイルを指します(管理画面のメディアの「変更」と同じ)。同じ種類(画像・SVG・ファイル)のファイルだけを受け付け、古いファイル(サイズ違い・オリジナル・サムネイルを含む)は差し替えの後に削除します。
ETAG=$(curl -s -D - -o /dev/null -H "Authorization: Bearer ${ACMS_API_TOKEN}" "${ACMS_API}/media/36/" \
| awk 'tolower($1)=="etag:"{print $2}' | tr -d '\r')
curl -s -X POST "${ACMS_API}/media/36/replace/" \
-H "Authorization: Bearer ${ACMS_API_TOKEN}" -H "If-Match: ${ETAG}" \
-F "file=@sample-v2.png;type=image/png"削除する
curl -s -i -X DELETE "${ACMS_API}/media/36/" -H "Authorization: Bearer ${ACMS_API_TOKEN}"
# HTTP/2 204メディアにはゴミ箱が無く、常に完全に削除します(?force は見ません)。管理画面の削除と同じ処理で、エントリーやカスタムフィールドから参照されていても削除します。削除の前に参照を確かめてください。
一覧の範囲と、エントリーからの参照
一覧は、選択できるメディア(URL のブログとその子孫。投稿者は自分のメディアだけ)を新しい順に返します(
?order=id-ascで古い順)。?include=blog,userで関連を含められます。キーワードやタグでの絞り込みはありません。エントリーの本文から参照するときは、
mediaユニットのattributes.media_idに、ID を文字列で入れます。カスタムフィールドの「メディア画像」「メディアファイル」は ID(整数)、「メディアギャラリー」は ID の配列で送ります(エントリーの本文とカスタムフィールドを送る)。
{
"title": "画像付きのお知らせ",
"status": "draft",
"units": [
{ "type": "media", "attributes": { "media_id": "36", "media_caption": "キャプション" } }
],
"fields": { "main_image": 36, "gallery": [36, 37] }
}よくある質問・つまずき
アップロードで 415 になります
POST /media は multipart/form-data で送ります。curl では -F を使い、Content-Type は自分で付けません(boundary が付かなくなるため)。
タグを付けると 422 reserved になります
api・rest-api などの予約語、4 桁の数字、拡張子の付いた形はタグに使えません。タグ名にカンマ・スラッシュ・改行も使えません。
応答の url が null です
?dry_run=1 のときは保存していないため、url・thumbnail_url は null です。
画像のユニットで送りたい
画像ユニット(image)は API から書き込めません。メディアとして登録し、media ユニットで参照してください。