WordPress REST APIで画像をアップロードする方法

はじめに
画像アップロードの流れ
実行前に準備するもの
Node.jsで画像をアップロードする
スクリプトを実行する
エラーが出たときの確認ポイント
まとめ
参考情報

はじめに

WordPressへ記事を自動登録できても、画像だけ管理画面から手作業でアップロードしていると、入稿作業が途中で止まってしまいます。

結論として、WordPress REST APIのPOST /wp/v2/mediaを利用すれば、外部ツールから画像をメディアライブラリへ登録できます。レスポンスで得られるメディアIDと画像URLを使い、代替テキストや投稿との関連付け、アイキャッチまで設定可能です。

この記事では、Node.js 18以降の標準機能だけを使い、JPEG・PNG・WebP画像をアップロードする例を紹介します。対象は自分で管理するWordPressサイトとし、投稿の公開や削除は行いません。

画像アップロードの流れ

画像の登録は、次の3段階に分けると理解しやすくなります。

POST /wp/v2/mediaへ画像データを送る
返されたメディアIDを使い、alt_textなどを設定する
下書きのfeatured_mediaへメディアIDを指定する

メディア作成時のレスポンスには、画像を識別するidと、本文で利用できるsource_urlが含まれます。本文へ画像を入れる場合はsource_url、アイキャッチへ設定する場合はidを使います。

実行前に準備するもの

今回の例では、次の環境を前提にします。

WordPress 5.6以降
Node.js 18以降
HTTPSで接続できる自分のWordPressサイト
メディアをアップロードできるWordPressユーザー
そのユーザー用に発行したアプリケーションパスワード

通常のログインパスワードをスクリプトへ書かないでください。API専用のアプリケーションパスワードを発行し、環境変数で渡します。Basic認証の情報を保護するため、接続先はHTTPSに限定してください。

HTTPSの役割から確認したい場合は、HTTPとHTTPSの違いとHTTPSが必要な理由を先に読むと理解しやすくなります。

PowerShellでは、現在のターミナルに環境変数を設定できます。値は自分の環境へ置き換えてください。

$env:WP_SITE_URL = "https://example.com"
$env:WP_USERNAME = "api-user"
$env:WP_APP_PASSWORD = "発行したアプリケーションパスワード"

ターミナルを閉じると、この方法で設定した値は引き継がれません。認証情報をGit管理するファイルへ保存しないことも重要です。

Node.jsで画像をアップロードする

次のコードをupload-wordpress-media.mjsとして保存します。画像ファイルのバイナリを読み込み、MIMEタイプとファイル名をヘッダーへ指定して送信します。

import { readFile } from 'node:fs/promises';
import { basename, extname, resolve } from 'node:path';

const [imageArgument, altText, postIdArgument] = process.argv.slice(2);
const siteUrl = process.env.WP_SITE_URL?.replace(/\/$/, '');
const username = process.env.WP_USERNAME;
const appPassword = process.env.WP_APP_PASSWORD;

if (!imageArgument || !altText || !siteUrl || !username || !appPassword) {
  throw new Error('画像パス、代替テキスト、WordPressの環境変数を確認してください。');
}

const imagePath = resolve(imageArgument);
const fileName = basename(imagePath);
const mimeTypes = new Map([
  ['.jpg', 'image/jpeg'],
  ['.jpeg', 'image/jpeg'],
  ['.png', 'image/png'],
  ['.webp', 'image/webp'],
]);
const mimeType = mimeTypes.get(extname(fileName).toLowerCase());
if (!mimeType) throw new Error('対応形式はJPEG、PNG、WebPです。');

const authorization = `Basic ${Buffer.from(`${username}:${appPassword}`).toString('base64')}`;

async function requestJson(url, options) {
  const response = await fetch(url, options);
  const body = JSON.parse(await response.text());
  if (!response.ok) throw new Error(`WordPress API error ${response.status}: ${JSON.stringify(body)}`);
  return body;
}

const media = await requestJson(`${siteUrl}/wp-json/wp/v2/media`, {
  method: 'POST',
  headers: {
    Authorization: authorization,
    'Content-Type': mimeType,
    'Content-Disposition': `attachment; filename="${fileName}"`,
  },
  body: await readFile(imagePath),
});

const postId = postIdArgument ? Number(postIdArgument) : undefined;

await requestJson(`${siteUrl}/wp-json/wp/v2/media/${media.id}`, {
  method: 'POST',
  headers: { Authorization: authorization, 'Content-Type': 'application/json; charset=utf-8' },
  body: JSON.stringify({
    alt_text: altText,
    title: fileName.replace(/\.[^.]+$/, ''),
    ...(postId ? { post: postId } : {}),
  }),
});

console.log({ mediaId: media.id, sourceUrl: media.source_url });

実用時は、同じフォルダーに保存した完成版サンプルのように、ファイル名、HTTPS、投稿ID、投稿状態も検証してください。

スクリプトを実行する

画像だけ登録する場合は、画像パスと代替テキストを指定します。

node upload-wordpress-media.mjs ./featured.jpg "WordPressへ画像を送信する流れ"

完成版サンプルでは、3番目に下書きIDを渡すと、画像を投稿へ関連付けてアイキャッチにも設定します。

node upload-wordpress-media.mjs ./featured.jpg "WordPressへ画像を送信する流れ" 1234

1234は例です。自分の下書きIDへ置き換えてください。公開済み記事を誤って変更しないよう、完成版では取得した投稿の状態がdraftであることを確認してからfeatured_mediaを更新しています。

本文へ画像を入れる場合は、アップロード結果のsource_urlをMarkdownまたはHTMLへ設定します。

![WordPressへ画像を送信する流れ](https://example.com/wp-content/uploads/2026/10/featured.jpg)

URLは例示用です。実際にはAPIが返したsource_urlをそのまま使用します。

エラーが出たときの確認ポイント

状況	主な確認箇所
401	ユーザー名、アプリケーションパスワード、Authorizationヘッダー
403	ユーザーにメディアのアップロード権限があるか
画像形式のエラー	拡張子と`Content-Type`が一致しているか
アイキャッチを設定できない	テーマの対応、メディアID、投稿の編集権限