Go 处理 Responses API 图片输入：MIME 预检、Base64 预算与失败回退

图片质检接口上线后，最先暴露问题的往往是客户端：用户上传了扩展名是 .jpg、实际却是 WebP 的文件，Base64 转换后请求体突然变大，或者慢网下请求一直占着连接。Go 调用 Responses API 处理图片时，建议把文件检查、大小预算和失败回退放在发送请求之前，模型只负责“看图并回答”，不负责替应用收拾输入数据。

一条可靠的处理链是：先读取文件头确认 MIME，再按 Base64 膨胀比例估算请求体，超过预算就压缩或转人工；发送时绑定 context 超时，失败结果保留原因和任务 id，不把原图内容写进普通日志。

先在 Go 客户端挡住不合格图片

扩展名只能说明用户怎么命名文件，不能说明文件内容。读取前 512 字节后再判断 MIME，配合大小和允许列表，可以把很多无效请求挡在网络调用之前：

var allowedImageTypes = map[string]bool{
    "image/jpeg": true,
    "image/png":  true,
    "image/webp": true,
}

func inspectImage(path string, maxBytes int64) (string, []byte, error) {
    info, err := os.Stat(path)
    if err != nil {
        return "", nil, err
    }
    if info.Size() == 0 || info.Size() > maxBytes {
        return "", nil, fmt.Errorf("图片大小 %d 超出预算 %d", info.Size(), maxBytes)
    }
    f, err := os.Open(path)
    if err != nil {
        return "", nil, err
    }
    defer f.Close()

    head := make([]byte, 512)
    n, err := io.ReadFull(f, head)
    if err != nil && err != io.ErrUnexpectedEOF {
        return "", nil, err
    }
    mime := http.DetectContentType(head[:n])
    if !allowedImageTypes[mime] {
        return "", nil, fmt.Errorf("不支持的图片类型: %s", mime)
    }
    body, err := os.ReadFile(path)
    return mime, body, err
}

如果接口只接收 PNG 和 JPEG，就把允许列表缩窄。这里的检查是输入卫生，不等同于安全扫描；生产环境还应限制图片像素总数，并在隔离环境做解码，防止超大尺寸图片拖垮内存。

Base64 预算要按请求体而不是原文件估算

把二进制图片放进 Data URL 后，体积大致是原文件的 4/3，还要加上 MIME 前缀、JSON 字段和提示词。不要把限制写成一个拍脑袋的“5 MB”，应把预算写进配置，并在请求前完成估算：

func encodedSize(rawSize int) int {
    return ((rawSize + 2) / 3) * 4
}

func imageDataURL(mime string, body []byte, budget int) (string, error) {
    size := encodedSize(len(body))
    prefix := len("data:") + len(mime) + len(";base64,")
    if prefix+size > budget {
        return "", fmt.Errorf("图片编码后约 %d 字节，超过请求预算 %d", prefix+size, budget)
    }
    return "data:" + mime + ";base64," + base64.StdEncoding.EncodeToString(body), nil
}

预算不是服务端固定值，而是应用为了稳定性给自己设的门槛。图片较大时，优先在上传阶段生成缩略图；如果原图是票据或标签，缩放后要重新检查文字是否仍然可读，不要为了过预算把关键信息压没了。

把图片放进 Responses API 请求，并控制连接生命周期

完成预检后，才把 Data URL 放到输入内容里。下面的示例只展示请求结构，实际项目应从配置读取模型和接口地址，并为每个任务生成可追踪的 id：

ctx, cancel := context.WithTimeout(context.Background(), 25*time.Second)
defer cancel()

payload := map[string]any{
    "model": "gpt-4.1-mini",
    "input": []any{map[string]any{
        "role": "user",
        "content": []any{
            map[string]any{"type": "input_text", "text": "判断这张图片是否清晰可读"},
            map[string]any{"type": "input_image", "image_url": dataURL},
        },
    }},
}
body, _ := json.Marshal(payload)
req, _ := http.NewRequestWithContext(ctx, http.MethodPost, endpoint, bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+apiKey)
req.Header.Set("Content-Type", "application/json")

超时要覆盖 DNS、连接、响应读取等阶段，不能只在调用后面包一个计时器。请求结束后立即释放响应体；日志记录 task_id、MIME、原始字节数、估算请求大小、HTTP 状态和耗时，Data URL 本身不要输出。

把超时和失败送进可恢复的回退路径

图片质检通常不是支付扣款这类必须同步完成的动作。模型请求失败时，可以把任务标成 pending_review，让人工继续处理；遇到 429 或临时 5xx 时，在任务级别做少量退避，遇到 MIME 不支持、预算超限和鉴权错误则直接停止。

type ReviewJob struct {
    ID          string
    Status      string
    FailureKind string
    Attempts    int
}

func nextStatus(err error) string {
    if errors.Is(err, context.DeadlineExceeded) {
        return "pending_review"
    }
    var apiErr *APIError
    if errors.As(err, &apiErr) && (apiErr.Status == 429 || apiErr.Status >= 500) {
        return "retry_wait"
    }
    return "rejected"
}

回退不是简单地“再发一次”。每次尝试都要带同一个任务 id，数据库用状态机限制 retry_wait -> processing -> done 的合法迁移。这样客户端在超时后再次提交，也不会产生两条人工任务。

用四类样本把输入边界跑一遍

上线前准备一组固定样本：正常 JPEG、扩展名与真实 MIME 不一致的文件、超过预算的高清图、接口模拟超时的任务。每条样本都检查状态迁移和日志字段，尤其确认失败记录里没有原图 Data URL。

type ImageMetric struct {
    MIME          string
    Bytes         int64
    EstimatedBody int64
    Status        string
    Duration      time.Duration
}

监控可以拆成 preflight_reject、request_timeout、api_retry 和 human_fallback 四类。它们分别代表用户输入问题、网络或服务时延、接口暂时不可用、以及业务上允许人工接管，排查时不会混成一个“失败率”。

常见问题：Go 图片输入接入时容易混淆的几件事

只检查扩展名能不能满足需求？

不能。扩展名可以伪造，至少应读取文件头判断 MIME，并配合大小和像素上限。

Base64 后为什么更容易超出请求预算？

Base64 会把每 3 个字节编码成 4 个字符，通常会增加约三分之一，还要加上 Data URL 前缀和 JSON 字段。

请求超时后要不要立刻重试？

先看任务是否已被服务端接受以及是否具备幂等键。对图片质检这类可回退任务，有限重试后进入人工队列更稳。

日志里应该保留图片内容方便排查吗？

普通日志不应保留 Data URL 或原图。记录任务 id、MIME、字节数、耗时、状态和错误类型，必要时把受控样本放到独立的安全存储。

让图片请求在模型之外也有一套边界

Responses API 只负责完成一次模型调用，输入文件是否合法、请求体是否超预算、失败后是否会重复处理，都应该由 Go 客户端和任务状态机负责。把这些门槛前移后，模型接口即使出现延迟或临时错误，业务也能沿着可观察、可回退的路径继续运行。