メディアを扱う


この機能は Ver. 3.3.0 で追加予定の、リリース前の機能です

このページは、アルファ版(Ver. 3.3.0-alpha.1)時点の内容です。正式版までに仕様や設定項目が変わる可能性があります。本番サイトでは使わず、検証環境でお試しください。

メディア(メディアライブラリの画像・SVG・ファイル)を REST API で扱います。エントリーの本文の画像やファイルは、メディアとして登録してから ID で参照します。

操作

メソッドとパス

スコープ

成功

一覧

GET /media

media:read

200

取得

GET /media/{id}

media:read

200(ETag 付き)

アップロード

POST /media(multipart/form-data)

media:write

201

URL から取り込み

POST /media/import

media:write

201

ファイルの差し替え

POST /media/{id}/replace(multipart/form-data)

media:write

201

項目の更新

PATCH /media/{id}・PUT /media/{id}

media:write

200

削除

DELETE /media/{id}

media:write

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/"
  }
}

アップロードで送れる項目

項目

説明・入力例

file

必須。アップロードするファイル

name

ファイル名(省略時は送ったファイルの名前)

status

ファイル(画像・SVG 以外)の公開範囲。entry・open・close・secret。省略時はコンフィグの media_default_status

tags

タグ(カンマ区切り)。例: サンプル,photo

caption / link / alt / text

キャプション / リンク / 代替テキスト / 説明

focal_point

焦点 "x,y"(各 0〜100)。例: 50,50

page

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(http か https、2048 文字まで)。認証情報を含む URL と内部のアドレスは不可。日本語などは百分率符号化します

name

ファイル名(拡張子つき)。省略時は URL のパスの最後の名前(拡張子が無い URL では必須)

status

アップロードと同じ

tags

文字列の配列

caption / link / alt / text / focal_point

文字列(null は空)

page

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"}'

項目

説明

name

ファイル名。拡張子は元のファイルのものになります

status

ファイル(type が file)だけ。ほかのメディアに送ると 422

tags

配列ごと置き換えます

caption / link / alt / text

null は空

focal_point

null は焦点なし

page

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 ユニットで参照してください。