Upload 模块（上传）¶

upload 模块提供图片上传功能，返回的 media_id_string 可用于 posts create 和 dm send 命令的媒体附件。

目录¶

upload image — 上传图片
media category 说明
大小与格式限制
与其他命令配合使用

upload image — 上传图片¶

将本地图片文件上传到 Twitter 媒体服务器，返回媒体 ID。

语法¶

twitter-cli [全局 flags] upload image \
  --file <PATH> \
  [--category tweet-image|dm-image|banner-image]

参数¶

参数	类型	必填	说明
`--file <PATH>`	path	是	本地图片文件路径（支持 JPEG、PNG、GIF、WebP）
`--category <CATEGORY>`	string	否	媒体类别，默认 `tweet-image`（见下方说明）

category 可选值¶

值	对应场景
`tweet-image`	帖子图片（默认）
`dm-image`	私信图片附件
`banner-image`	用户 Banner 图

成功示例¶

twitter-cli --cookies-file cookies.txt upload image \
  --file /path/to/photo.jpg \
  --category tweet-image

输出：

{"success":true,"data":{"media_id":1811234567890123456,"media_id_string":"1811234567890123456","size":245678,"image":{"image_type":"image/jpeg","w":1920,"h":1080},"expires_after_secs":86400},"error":null,"meta":{"module":"upload","action":"image","elapsed_ms":1234,"timestamp":"2026-04-17T10:45:00Z","cli_version":"1.0.0","schema_version":"1.0"}}

上传 dm-image：

twitter-cli --cookies-file cookies.txt upload image \
  --file avatar.png \
  --category dm-image

失败示例¶

文件过大：

{"success":false,"data":null,"error":{"code":"MEDIA_UPLOAD_FAILED","message":"图片文件超过大小限制（最大 5MB）","retryable":false,"retry_after_secs":null,"docs_url":null,"recovery_actions":["压缩图片后重试","使用 ImageMagick: convert input.jpg -resize 1920x1080\\> -quality 85 output.jpg"],"issue_url":null,"details":{"file_size":8234567,"max_size":5242880}},"meta":{"module":"upload","action":"image","elapsed_ms":89,"timestamp":"2026-04-17T10:46:00Z","cli_version":"1.0.0","schema_version":"1.0"}}

格式不支持：

{"success":false,"data":null,"error":{"code":"MEDIA_UPLOAD_FAILED","message":"不支持的图片格式 .bmp，支持格式：JPEG、PNG、GIF、WebP","retryable":false,"retry_after_secs":null,"docs_url":null,"recovery_actions":["将图片转换为 JPEG 或 PNG 格式后重试"],"issue_url":null,"details":{"file_ext":".bmp"}}}

data 字段说明¶

字段	类型	说明
`media_id`	number	媒体 ID（数字类型，大整数可能有精度问题，建议使用 `media_id_string`）
`media_id_string`	string	媒体 ID（字符串类型，推荐使用此字段）
`size`	number	文件大小（字节）
`image.image_type`	string	MIME 类型（如 `"image/jpeg"`）
`image.w`	number	图片宽度（像素）
`image.h`	number	图片高度（像素）
`expires_after_secs`	number	媒体 ID 有效期（秒），超过后无法使用

重要: media_id_string 是字符串，始终使用此字段而非 media_id（数字类型在某些 JSON 解析器中可能丢失精度）。

media category 说明¶

不同类别的媒体在 Twitter 服务器上存储路径不同，使用错误类别会导致后续操作失败：

category	用于	不可用于
`tweet-image`	`posts create --media-ids`	`dm send --media-id`
`dm-image`	`dm send --media-id`	`posts create --media-ids`
`banner-image`	更新用户 Banner（Python API）	帖子、私信

大小与格式限制¶

Twitter 的媒体上传限制：

类别	格式	最大尺寸
`tweet-image`	JPEG、PNG、WebP	5 MB
`tweet-image`	GIF	15 MB
`dm-image`	JPEG、PNG、WebP、GIF	5 MB
`banner-image`	JPEG、PNG	5 MB

最大分辨率：4096 x 4096 像素（超过此尺寸会被自动缩小）

压缩图片建议¶

# 使用 ImageMagick 压缩（macOS: brew install imagemagick）
convert input.jpg -resize 1920x1080\> -quality 85 output.jpg

# 使用 ffmpeg 转换格式
ffmpeg -i input.bmp output.jpg

# 检查文件大小
ls -lh photo.jpg

与其他命令配合使用¶

上传图片 -> 发布帖子¶

# 上传并提取 media_id_string
media_id=$(twitter-cli --cookies-file cookies.txt upload image \
  --file photo.jpg \
  --category tweet-image | jq -r '.data.media_id_string')

# 检查上传是否成功
if [ -z "$media_id" ] || [ "$media_id" = "null" ]; then
  echo "上传失败"
  exit 1
fi

# 发布带图片的帖子
twitter-cli --cookies-file cookies.txt posts create \
  --text "今天的照片 📸" \
  --media-ids "$media_id"

上传图片 -> 发送私信¶

# 上传私信专用图片
media_id=$(twitter-cli --cookies-file cookies.txt upload image \
  --file screenshot.png \
  --category dm-image | jq -r '.data.media_id_string')

# 发送带图片的私信
twitter-cli --cookies-file cookies.txt dm send \
  --user-id 783214 \
  --text "请查看附件截图" \
  --media-id "$media_id"

多图上传（发帖最多 4 张）¶

# 依次上传多张图片
ids=()
for img in photo1.jpg photo2.jpg photo3.jpg; do
  id=$(twitter-cli --cookies-file cookies.txt upload image \
    --file "$img" --category tweet-image | jq -r '.data.media_id_string')
  ids+=("$id")
done

# 拼接 media-ids（逗号分隔）
media_ids=$(IFS=,; echo "${ids[*]}")

# 发布多图帖子
twitter-cli --cookies-file cookies.txt posts create \
  --text "今日多图记录" \
  --media-ids "$media_ids"

常见错误¶

错误码	原因	解决方法
`INVALID_ARGS`	`--file` 路径不存在	确认文件路径
`INVALID_ARGS`	`--category` 值不合法	使用 tweet-image / dm-image / banner-image
`MEDIA_UPLOAD_FAILED`	文件超过大小限制	压缩图片
`MEDIA_UPLOAD_FAILED`	格式不支持	转换为 JPEG/PNG/GIF/WebP
`AUTH_FAILED`	cookies 过期	重新导出 cookies
`NETWORK`	上传连接中断	检查网络，重试