超时与重试 - Poomi 文档

一次分析通常几秒到几十秒，最长约 2 分钟。云函数等有执行时长上限的环境，可能等不到结果就超时了。

带上请求编号

每次调用带一个你自己生成的编号（例如订单号 + 检测类型，控制台里叫「客户编号」），放在请求头 X-Client-Request-Id（也可以写成 Idempotency-Key）：

curl https://open.poomi.cn/api/v1/feces-analysis \
  -H "Authorization: Bearer pk_xxxxxxxx…" \
  -H "X-Client-Request-Id: pet-1024-feces-001" \
  -H "Content-Type: application/json" \
  -d '{ "image": "base64_encoded_image_data" }'

编号 1–64 位，只能用字母、数字和 - _ . :，同一个账号内不重复。
同一个编号再发一次：
- 已经成功 → 直接返回第一次的结果（同一个 request_id，响应头 Idempotent-Replayed: true），不再分析、不再扣费；
- 还在处理 → 返回 409 REQUEST_IN_PROGRESS，稍后再发或用下面的查结果接口；
- 第一次失败了（失败不收费）→ 按新请求重新处理。
同一个编号换了接口或图片 → 返回 422 CLIENT_ID_REUSED。每个新请求请用新编号。
编号在结果保存期（6 个月）内有效。不带编号的调用和以前完全一样。

查结果

curl https://open.poomi.cn/api/v1/results/pet-1024-feces-001 \
  -H "Authorization: Bearer pk_xxxxxxxx…"

GET /api/v1/results/{id}，id 填 request_id（req_ 开头）或你的请求编号。免费，只能查自己账号的调用。

状态	返回
处理中	`{ "success": true, "status": "processing", "request_id": "req_…" }`
成功	和原调用一样的完整结果，加 `"status": "succeeded"`
失败	原来的错误响应，加 `"status": "failed"`
查不到或已过保存期	404 `RESULT_NOT_FOUND`

找到的结果 HTTP 状态码都是 200，看 status 判断。

云函数怎么设

HTTP 超时设在执行时长上限以内（例如上限 55 秒就设 50 秒）。超时后用同一个编号重发，或下次再用查结果接口取。结果和费用都只算一次。

// Node.js 18+
const BASE = 'https://open.poomi.cn';
const KEY = process.env.POOMI_API_KEY;

async function analyze(requestNo, imageBase64) {
  try {
    const res = await fetch(`${BASE}/api/v1/feces-analysis`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${KEY}`,
        'Content-Type': 'application/json',
        'X-Client-Request-Id': requestNo,
      },
      body: JSON.stringify({ image: imageBase64 }),
      signal: AbortSignal.timeout(50_000),
    });
    return await res.json();
  } catch (err) {
    if (err.name !== 'TimeoutError') throw err;
    // 超时：先存下 requestNo，稍后（或下一次云函数）查结果
    return { success: true, status: 'processing', requestNo };
  }
}

async function getResult(requestNo) {
  const res = await fetch(`${BASE}/api/v1/results/${encodeURIComponent(requestNo)}`, {
    headers: { Authorization: `Bearer ${KEY}` },
  });
  return res.json(); // status: processing / succeeded / failed
}

控制台「调用记录」可以按客户编号搜索。