PHP文生图接口返回503是因熔断器主动拦截保护后端，需检查error_code、retry-after头、限制超时至8秒、缓存失败时间、降级fallback，并确认provider已退出半开态。
PHP 文生图接口不是“挂了”，而是被熔断器主动掐断了——它在保护后端模型服务不被拖垮。
为什么 PHP 调用文生图接口总返回 503 或自定义错误码
这不是网络超时或 token 错误，而是上游服务（比如 Z-Image-Turbo 或 SDXL 推理网关）触发了熔断。常见现象包括：
- 连续几次请求都卡在
curl_exec()超时（如 30s），之后突然全部返回503 Service Unavailable或{"error_code": "provider_down"} - 错误响应里带
retry-afterheader，但重试无效 - 日志里查不到模型侧报错，只看到“服务不可用”类降级日志
根本原因是：PHP 客户端没感知熔断状态，还在拼命发请求；而服务端已将该 provider 标记为“故障”，所有流量被拦截并走本地降级逻辑。
PHP 侧如何配合熔断器做优雅重试
不能靠 while (true) 硬重试，得按熔断器的节奏来。关键点：
立即学习“PHP免费学习笔记（深入）”；
- 检查响应状态码和 body 中是否含
"error_code"字段，如"model_unavailable"、"auth_unavailable"，这类是明确熔断信号 - 读取响应 header 中的
retry-after值（单位秒），若存在则必须 sleep 对应时间再发起下一次请求 - 避免并发请求打穿熔断窗口：用
apcu_store()缓存最近一次失败时间戳，10 秒内相同 provider 的请求直接跳过 - 降级 fallback：当检测到熔断时，可返回缓存图（
/static/fallback.jpg）或调用备用模型 API（如从 Z-Image 切到 ComfyUI 兼容接口）
PHP cURL 请求必须加的三个熔断友好配置
默认 curl_setopt() 设置会让熔断器误判健康状态：
- 务必设
CURLOPT_TIMEOUT_MS≤ 8000（8 秒），否则单次请求拖太久，熔断器统计的“超时率”虚高 - 禁用
CURLOPT_CONNECTTIMEOUT_MS单独设置，改用统一CURLOPT_TIMEOUT_MS控制全程，避免连接快但处理慢却被放行 - 加上
CURLOPT_HTTPHEADER包含"X-Request-ID: " . uniqid("req_")，方便熔断器按 trace_id 统计失败链路，而不是粗暴封整个 IP
示例片段：
curl_setopt($ch, CURLOPT_TIMEOUT_MS, 8000);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'X-Request-ID: ' . uniqid('req_')
]);
别忽略 provider 熔断恢复的静默期
很多 PHP 工程师以为熔断器“一好就通”，其实不是。Z-Image-Turbo 等生产级网关的熔断恢复有两阶段：
- 半开状态：只放行 5% 流量试探，其余仍走降级；这时 PHP 若没做成功率判断，会持续拿到降级结果
- 静默探测：后台自动用空 prompt 调用
/health接口验证，成功 3 次才全量恢复；这个过程 PHP 无法感知
所以，当发现错误率突降但仍未恢复时，别急着改代码——先确认 provider 是否已退出熔断半开态。最简单方式是 curl -I 请求 /health，看返回是否为 200 OK 且 body 含 "status":"healthy"。
