When working with WordPress via its REST API, one of the most common requirements is to programmatically upload media, like images, and add them to posts. Whether you’re building a custom WordPress dashboard or automating content management, this process can streamline your workflow. In this guide, I’ll walk through how to upload images to WordPress, set their metadata, and attach them as the featured image of a blog post—all using axios and TypeScript.
Thank me by sharing on Twitter 🙏
In this tutorial, I’ll cover the setup for uploading images, adding metadata such as alt text and descriptions, and setting the uploaded image as the featured image of a post. Using TypeScript provides the added benefit of type safety, making it easier to handle the WordPress API responses and ensure our code runs smoothly.
Setting Up the Upload Request
To start, we need to set up an API call to upload an image to WordPress. WordPress provides a media endpoint specifically for handling media uploads, making it easy to add images to your WordPress site programmatically. You’ll need to ensure that your API token has permission to access and upload to this endpoint.
Here’s how to get started with the axios request to upload an image file to WordPress:
Code Example for Uploading Images
First, let’s create a function called uploadImageToWordPress that takes a file path and filename as inputs and uploads the image to WordPress:
SZHAIYIJIN SD Card Reader for iPhone, Memory Card Reader with USB Camera Adapter Plug and Play Trail Game Camera SD Card Viewer Supports SD and TF Card Micro SD Card Adapter for iPad No App Required
$9.99 (as of December 21, 2024 08:38 GMT +00:00 - More infoProduct prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on [relevant Amazon Site(s), as applicable] at the time of purchase will apply to the purchase of this product.)
Co-Intelligence: Living and Working with AI
$17.79 (as of December 21, 2024 19:39 GMT +00:00 - More infoProduct prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on [relevant Amazon Site(s), as applicable] at the time of purchase will apply to the purchase of this product.)
COLORCORAL Cleaning Gel Universal Dust Cleaner for PC Keyboard Car Detailing Office Electronics Laptop Dusting Kit Computer Dust Remover, Stocking Stuffers for Men Women Kids Teens 160g
$6.98 (as of December 21, 2024 08:38 GMT +00:00 - More infoProduct prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on [relevant Amazon Site(s), as applicable] at the time of purchase will apply to the purchase of this product.)import axios, { AxiosResponse } from 'axios';
import * as fs from 'fs';
const BASE_URL = 'https://yourwebsite.com/wp-json/wp/v2';
const TOKEN = 'YOUR_ACCESS_TOKEN';
interface MediaUploadResponse {
id: number;
source_url: string;
alt_text: string;
description: { rendered: string };
[key: string]: any; // Accommodate any additional properties WordPress returns
}
async function uploadImageToWordPress(
filePath: string,
fileName: string,
altText: string,
description: string
): Promise<number | void> {
const url = `${BASE_URL}/media`;
try {
const imageData = fs.readFileSync(filePath);
const headers = {
'Authorization': `Basic ${TOKEN}`,
'Content-Disposition': `attachment; filename=${fileName}`,
'Content-Type': 'image/jpeg', // Change MIME type based on the file
};
// Set metadata fields
const params = {
alt_text: altText,
description: description,
};
// Make the POST request to upload the image with metadata
const response: AxiosResponse<MediaUploadResponse> = await axios.post(url, imageData, {
headers,
params,
});
if (response.status === 201) {
console.log('Image uploaded successfully with metadata:', response.data);
return response.data.id; // Return the media ID
} else {
console.error('Failed to upload image. Status:', response.status);
}
} catch (error) {
if (axios.isAxiosError(error)) {
console.error('Axios error:', error.message);
} else {
console.error('Unexpected error:', error);
}
}
}In this code:
- The
Authorizationheader contains the API token required to interact with WordPress. - We use
Content-Dispositionto specify the filename, whileContent-Typeis set to the image’s MIME type, likeimage/jpegfor a JPEG image. - We pass
alt_textanddescriptionmetadata in theparamsobject to set properties that enhance accessibility and SEO.
Using this function, you can upload images to WordPress and add metadata in a single request, providing a solid foundation for your API interactions.
Setting Metadata for Images
Metadata is essential for accessibility and search engine optimization. WordPress allows you to set properties like alt text and description directly through the REST API. Adding these fields ensures that the images not only serve a visual purpose but also contribute to the overall accessibility and searchability of your site.
In our uploadImageToWordPress function above, the metadata fields are included in the params object:
const params = {
alt_text: altText,
description: description,
};alt_text: This field is crucial for accessibility, providing descriptive text for visually impaired users.description: This property offers a summary of the image content, which can be useful for search engines and CMS organization.
With axios, we pass these fields directly into the request, where they are stored by WordPress upon upload. You can adjust these fields based on specific image requirements, ensuring your images are both accessible and discoverable.
Associating the Image with a Blog Post as the Featured Image
Once the image is uploaded, you may want to attach it to a specific blog post as the featured image. In WordPress, this is done by setting the featured_media field in the post to the media ID of the uploaded image.
Let’s create a function, setFeaturedImage, to handle this for us. This function will take in a postId and mediaId, then update the featured_media field for the specified post.
Code Example for Setting a Featured Image
Here’s how we would create and use this function:
interface WordPressPostResponse {
id: number;
date: string;
slug: string;
title: { rendered: string };
content: { rendered: string };
featured_media: number;
[key: string]: any;
}
async function setFeaturedImage(postId: number, mediaId: number): Promise<void> {
const url = `${BASE_URL}/posts/${postId}`;
const headers = {
'Authorization': `Basic ${TOKEN}`,
'Content-Type': 'application/json',
};
const data = {
featured_media: mediaId, // Sets the featured image for the post
};
try {
const response: AxiosResponse<WordPressPostResponse> = await axios.patch(url, data, { headers });
if (response.status === 200) {
console.log('Post updated successfully with featured image:', response.data);
} else {
console.error('Failed to update post. Status:', response.status);
}
} catch (error) {
if (axios.isAxiosError(error)) {
console.error('Axios error:', error.message);
} else {
console.error('Unexpected error:', error);
}
}
}To use these functions together, simply call uploadImageToWordPress, retrieve the returned mediaId, and then call setFeaturedImage with your desired postId.
Example Usage
async function main() {
const imageId = await uploadImageToWordPress(
'/path/to/your/image.jpg',
'image.jpg',
'An example alt text for the image',
'A description for the image.'
);
if (imageId) {
await setFeaturedImage(123, imageId); // Replace 123 with your post ID
}
}
main();Here, main orchestrates the workflow: it first uploads the image and adds the metadata, then updates a post with the image as the featured image.
Conclusion
Using WordPress’s REST API with TypeScript and axios to upload images and add metadata can improve your workflow’s efficiency and give you greater control over content management. We’ve covered the steps to upload images, set essential metadata like alt text and description, and assign the image as a post’s featured image.
This approach is ideal for managing a WordPress site programmatically, ensuring that images are not only uploaded but also optimized for accessibility and SEO right from the start. By breaking down the process into modular, reusable functions, you’ll find it easy to integrate media management into any WordPress project.
