如何通过WP REST API创建媒体时指定alt、caption等字段

AI 小北

2026-4-17

嘿，看你已经能通过代码调用WP REST API上传媒体文件了，但应该是遇到没法设置alt文本、标题、说明这些元数据的问题了对吧？我来帮你调整下代码，解决这个问题~

你之前的写法是直接把图片二进制数据作为POST内容提交，这种方式只能上传文件本身，没法附带任何元信息。要同时设置alt、caption这些字段，我们需要用multipart/form-data的表单格式来提交，把图片文件和元数据字段一起发给API端点。

下面是修改后的完整代码，我加了详细注释，你可以直接参考：

function createMedia($urlImage, $title, $altText = '', $caption = '') {
    global $usernameWP;
    global $passwordWP;
    
    $rest_api_url = "https://www.example.com/wp-json/wp/v2/media";

    // 先把远程图片下载到临时文件，因为WP API需要上传文件的形式，而不是直接传二进制数据
    $image_data = file_get_contents($urlImage);
    $tempFile = tempnam(sys_get_temp_dir(), 'wp_media_'); // 创建临时文件
    file_put_contents($tempFile, $image_data);
    $filename = basename($urlImage);

    // 构造表单数据：包含图片文件和要设置的元字段
    $postFields = [
        'file' => curl_file_create($tempFile, mime_content_type($tempFile), $filename),
        'alt_text' => $altText, // 直接设置图片的替代文本
        'caption' => [
            'raw' => $caption // caption的原始内容，WP会自动生成前端渲染用的版本
        ],
        'title' => [
            'raw' => $title // 媒体文件的标题
        ]
    ];

    $ch = curl_init();

    curl_setopt($ch, CURLOPT_URL, $rest_api_url);
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $postFields);

    // 这里不用手动设置Content-Type，CURL会自动处理multipart/form-data的请求头
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Basic ' . base64_encode($usernameWP . ':' . $passwordWP),
    ]);

    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true); // 处理可能的重定向

    $resultJsonString = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

    // 用完临时文件记得删掉，避免服务器垃圾堆积
    unlink($tempFile);

    // 处理请求错误
    if (curl_errno($ch)) {
        $error = curl_error($ch);
        curl_close($ch);
        return ['error' => $error];
    }

    curl_close($ch);

    // 根据HTTP状态码判断请求是否成功
    if ($httpCode >= 200 && $httpCode < 300) {
        return json_decode($resultJsonString, true); // 返回创建成功的媒体数据
    } else {
        return ['error' => '请求失败，状态码：' . $httpCode, 'response' => $resultJsonString];
    }
}

几个关键要点给你划重点：

临时文件的使用：WP REST API的媒体端点要求上传file字段（文件类型），所以我们得把远程图片先存到本地临时文件，再用curl_file_create包装成上传对象。
字段对应关系：WP API里的字段是固定的，比如alt_text直接对应图片的替代文本；caption和title都是包含raw（原始内容）和rendered（渲染后内容）的对象，我们只需要传raw，WP会自动处理渲染版本。
请求头的注意：不要手动设置Content-Type，当POST字段是数组时，CURL会自动生成正确的multipart/form-data请求头和边界，手动设置反而会导致请求失败。
权限问题：确保你的$usernameWP对应的WordPress用户拥有upload_files的权限，不然会返回403禁止访问的错误。

如果还需要设置其他字段（比如图片描述），可以在$postFields里添加'description' => ['raw' => '你的描述内容']，格式和caption一样就行~

备注：内容来源于stack exchange，提问作者Jean François Manatane