This is not possible via the API; you need to fetch the image yourself, and send the data to the API yourself.
Blockquote
– This quotes Ryan on the GitHub–issue mentioned in @Dan (deleted) answer.
How to side load images
Note that the media_sideload_image()
return value can be an instance of \WP_Error
as well. You then just need to attach it to a post, which is quite simple:
$media = media_sideload_image(
"http://i.imgur.com/bcJvAj0.jpg',
$post->ID,
'Some image description',
'src'
);
if ( ! empty( $media ) and ! is_wp_error( $media ) ) {
// reference new image to set as featured
$attachments = get_posts( [
'post_type' => 'attachment',
'posts_per_page' => 1,
'post_status' => 'any',
'post_parent' => $post->ID,
] );
if ( is_array( $attachments ) ) {
set_post_thumbnail( $post->ID, $attachments[0]->ID );
}
// Test print our image. The return value is the src of the sideloaded image.
printf( '<img src="https://wordpress.stackexchange.com/questions/229430/%s" />', $media );
}
The internals
A short back trace through core that explains why you should stick with the API:
Take a look at the source of media_sideload_image()
to see it uses download_url()
internally, which uses wp_safe_remote_get()
, a wrapper for \WP_HTTP::get()
. This means it offers the whole WP API while being quite safe, debuggable and easy to use. The return value of download_url()
is the result of wp_tempnam()
, which takes all possible /tmp
locations into account (there are plenty) and makes sure your location is writeable. The media_handle_sideload()
will generate all needed attachment data and meta data.