如何用PHP调用API发送语音短信？遇The voice file must be a file错误

错误核心原因 #

你使用了http_build_query()来构建POST请求体，这个函数会将CURLFILE对象转换为普通字符串（类似CURLFILE Object (...)），而非API要求的multipart/form-data格式的文件上传结构，导致API无法识别到有效的语音文件。

解决方案 #

直接将包含CURLFILE的关联数组赋值给CURLOPT_POSTFIELDS，无需经过http_build_query()处理。当cURL检测到数组中存在CURLFILE对象时，会自动将请求编码为multipart/form-data格式——这是文件上传的标准格式，能被API正确识别。

修改后的代码 #

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://example/api/send',
    CURLOPT_HTTPHEADER => ['api-key: keyxxx='],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    // 直接传递数组，跳过http_build_query
    CURLOPT_POSTFIELDS => [
        'recipients' => [
            '233550000000'
        ],
        'voice_file' => new CURLFILE('voice_message.mp3'),
    ],
]);

$response = curl_exec($curl);

curl_close($curl);
echo $response;

额外检查项 #

• 确认voice_message.mp3路径正确：如果用相对路径，需保证文件和当前PHP脚本在同一目录；建议优先使用绝对路径（如/var/www/your-project/voice_message.mp3）。
• 检查文件权限：确保PHP进程拥有读取该文件的权限。
• 验证PHP版本：CURLFILE从PHP 5.5开始支持，若使用更早版本，可改用废弃的@前缀格式：'voice_file' => '@/path/to/voice_message.mp3'（不推荐，仅作兼容参考）。

内容的提问来源于stack exchange，提问作者Ken