UnicodeEncodeError latin-1は日本語ファイル名が原因

Pythonの requests でWordPressに画像をアップロードしようとしたら、「UnicodeEncodeError: 'latin-1’ codec can’t encode character」というエラーで止まった。画像の中身は普通のJPEGなのに、そもそも「latin-1」って何? そんな状態の方に向けた記事です。

この記事では、このエラーが何を意味しているのか、なぜ画像のアップロードで起きるのか、どう直せばいいのかを書きます。僕は移住前に都内でSEをしていて、今はこのブログの投稿をPythonで自動化しています。その作業中に、まさにこのエラーで止まりました。

読み終わるころには、エラーの原因に当たりをつけて、数行の修正で先に進めるようになるはずです。

こんなエラーが出ていませんか?

WordPressのREST APIで、画像を /wp-json/wp/v2/media に送ったときに、次のようなエラーが出るケースです。

UnicodeEncodeError: 'latin-1' codec can't encode characters in position 22-30: ordinal not in range(256)

日本語が1文字だけなら「can’t encode character '日’ in position 22」のように文字コード付きで、何文字か続いていると上のように「characters in position 22-30」と範囲で表示されます。数字は送ろうとした内容によって変わります。WordPressから返ってきたエラーではなく、Pythonがリクエストを送る前に止まっているのがポイントです。

結論:HTTPヘッダーに日本語を入れたのが原因

  • HTTPの「ヘッダー」(リクエストに付ける付帯情報)には、日本語をそのまま入れられません
  • Python標準の http.client(requests も最終的にこれを使って送ります)は、ヘッダーの値を latin-1 という文字コードに変換してから送ります。latin-1 は英数字や欧文の記号・アクセント付き文字など256種類しか扱えないので、日本語が入っているとこのエラーになります
  • 画像のアップロードでは、ファイル名を Content-Disposition というヘッダーに入れて送るため、ファイル名が日本語だと、ここで引っかかります

直し方はシンプルで、ファイル名を英数字だけにすることです。僕はこの方法で直りました。

僕の場合:ファイル名が記事のキーワードだった

僕は、Pythonの requests でWordPressに画像をアップロードするプログラムを動かしていました。そこで出たのが、冒頭の「UnicodeEncodeError: 'latin-1’ codec can’t encode character」です。

原因は、Content-Disposition ヘッダーに入れていたファイル名が、日本語(記事のキーワード)になっていたことでした。ファイル名を日本語にしていたのに、特に理由はありません。プログラムを作ったときに、たまたまそうなっていただけです。

正直、原因に気づくまで少し悩みました。エラーメッセージに出てくる「latin-1」が何のことか分からなかったからです。調べたり、Claude(AIアシスタント)に聞いたりして、ようやく「HTTPヘッダーには日本語をそのまま入れられない」という話にたどり着きました。

ファイル名を featured-時刻.jpg のような英数字だけの名前に変えたら、エラーは出なくなりました。

なぜ latin-1 なのか

少しだけ仕組みの話をします。

HTTPの仕様(RFC 9110)では、ヘッダーの値は基本的に US-ASCII(半角英数字と記号)の範囲にとどめるものとされています。昔は ISO-8859-1(latin-1 と同じ文字コード)の文字も許されていた、という経緯も書かれています。

Pythonの http.client のソースコードを見ると(2026年11月時点)、ヘッダーの値が文字列なら encode('latin-1') で変換してから送る作りになっています。latin-1 で表せるのは256種類の文字だけなので、「日」のような日本語は変換できません。エラーメッセージの「ordinal not in range(256)」は、「この文字の番号は256の範囲に入っていない」という意味です。

つまり、エラーに出てくる latin-1 は「Pythonがヘッダーを送るときに使う文字コード」のことで、画像の中身とは関係ありません。

直し方:ファイル名を英数字にする

ここからは、実際の直し方です。下のコードは説明用に書いたもので、当時のコードそのものではありません。

エラーになる書き方

画像のデータをそのまま本文として送り、ファイル名を Content-Disposition ヘッダーで伝える書き方です。

import requests

# WP_USER・WP_APP_PASSWORD は、ユーザー名とアプリケーションパスワードに置き換え
filename = "日本語のキーワード.jpg"  # ← ヘッダーに日本語が入る

with open("image.jpg", "rb") as f:
    r = requests.post(
        "https://example.com/wp-json/wp/v2/media",
        auth=(WP_USER, WP_APP_PASSWORD),
        headers={
            "Content-Disposition": f'attachment; filename="{filename}"',
            "Content-Type": "image/jpeg",
        },
        data=f.read(),
    )

直した書き方

ファイル名を英数字だけにします。僕は featured-時刻.jpg のような名前にしました。時刻を入れておくと、毎回ちがう名前になります。

from datetime import datetime

filename = f"featured-{datetime.now():%Y%m%d%H%M%S}.jpg"

あとは同じコードで送れます。ちなみに、WordPressのソースを見ると(2026年11月時点)、この書き方で Content-Disposition ヘッダーがないと「No Content-Disposition supplied.」というエラー(400)が返る作りです。ヘッダー自体は外さず、中身のファイル名だけを変えてください。

参考:日本語のファイル名を送る正式な書き方(僕は試していません)

「どうしても日本語のファイル名で送りたい」という場合のために、仕様上の方法も紹介しておきます。

Content-Disposition の仕様(RFC 6266)には、filename* という書き方があります。ファイル名をUTF-8にしたうえで「%E6%97%A5」のような形(パーセントエンコード)に変換して送るもので、変換のルールは RFC 5987(現在は RFC 8187 に更新)で決められています。RFC 6266 では、filename* を理解できない古い受け手のために、英数字の filename も一緒に付ける書き方も紹介されています。

from urllib.parse import quote

name = "日本語のキーワード.jpg"
cd = f"attachment; filename=\"image.jpg\"; filename*=UTF-8''{quote(name, safe='')}"

こうすればヘッダーの中身は英数字と記号だけになるので、latin-1 のエラーは出ないはずです。

ただし、僕はこの方法を試していません。しかも、WordPressのソースコードを読んだ限りでは(2026年11月時点)、REST APIがファイル名として読み取っているのは filename だけで、filename* を読む処理は見当たりませんでした。そのため、この方法で送っても、WordPressに日本語のファイル名で保存されるとは限りません。試す場合は、自分の環境で結果を確認してください。

キーワードを入れたいなら、代替テキストやタイトルに

もし「画像検索を意識して、ファイル名にキーワードを入れたい」と考えているなら、ファイル名にこだわらなくても大丈夫です。

Googleの画像検索向けのガイドでは、ファイル名は画像の内容について「ごくわずかな手がかり」にとどまるとされ、代替テキスト(alt属性)が「最も重要な属性」と書かれています(2026年11月時点)。ファイル名は英数字にして、キーワードは代替テキストやタイトルに入れる、という分け方で十分だと思います。

WordPressのREST APIでは、アップロードしたあとに、画像のIDを指定して alt_text(代替テキスト)や title(タイトル)を更新できます。こちらはJSONの本文として送るので、日本語でも問題ありません。

media_id = r.json()["id"]

requests.post(
    f"https://example.com/wp-json/wp/v2/media/{media_id}",
    auth=(WP_USER, WP_APP_PASSWORD),
    json={"alt_text": "日本語のキーワード", "title": "日本語のキーワード"},
)

なお、同じガイドには「キーワードを詰め込みすぎない」ことも書かれています。代替テキストは、画像の内容を短く説明する文にしておきましょう。

それでもアップロードできないとき

ファイル名を英数字にしてエラーが消えたあと、今度はWordPress側から別のエラーが返ってくることもあります。僕は同じ自動投稿の作業で、次のエラーにも引っかかりました。

latin-1 のエラーはPythonの中で起きるもの、上の3つはリクエストがサーバーに届いてから起きるもの、という違いがあります。どこで止まっているかを見ると、切り分けやすくなります。

まとめ

「UnicodeEncodeError: 'latin-1’」が出たときのポイントをまとめます。

  • 画像の問題ではなく、HTTPヘッダーに日本語が入っていることが原因
  • 画像アップロードなら、まず Content-Disposition のファイル名に日本語が入っていないかを見る
  • 直し方は、ファイル名を英数字だけにすること(僕はこれで直りました)
  • filename* を使う方法もあるが、WordPressで日本語のファイル名になるかは未確認
  • キーワードを入れたいなら、ファイル名ではなく代替テキストやタイトルに

「latin-1」という見慣れない言葉に戸惑うエラーですが、原因が分かれば直すのは数行です。同じところで手が止まっている方の参考になればうれしいです。