How Creating a Media Item Actually Works in WordPress
POST /wp-json/wp/v2/media takes the actual binary file in the request body (not JSON), with a Content-Disposition header specifying the filename -- this is a file upload, not a metadata-only create call.
Real API Details
For images, WordPress automatically generates multiple registered sizes (thumbnail, medium, large, and the original "full") on upload -- the response's media_details.sizes object lists each one with its own URL and dimensions.
Practical Considerations
Media items are technically their own post type (attachment) in WordPress's data model, so associating an uploaded item with a specific post requires setting its post field -- uploading doesn't automatically attach it to any post just because it was uploaded around the same time.
Use cases
Example automation scenarios include:
- Automatically upload product images from an external feed.
- Sync branded imagery to WordPress when new campaigns are created.
- Bulk import media for a new site launch.
- Attach uploaded media to relevant posts on publish.