人臉年齡偵測

上傳一張圖片,找出圖中所有人臉的位置,以及每張臉的大致年齡。每次偵測會扣積分,扣款規則請見〈積分與計費〉。

圖片直接以檔案上傳(multipart/form-data),不需要轉成 base64。

POST /api/v2/tasks/detect-face
X-Api-Key: sk-live-xxxx
Content-Type: multipart/form-data
Idempotency-Key: 選填,見〈圖生影片〉的說明

完整範例

curl -X POST https://yuyuvideo.com/api/v2/tasks/detect-face \
  -H "X-Api-Key: sk-live-xxxx" \
  -F "image=@photo.jpg" \
  -F "callback_url=https://example.com/webhooks/yuyu-detect-face"

建立成功會回傳 202 Accepted 和任務資料(type 為 3),表示系統已收到圖片、正在偵測。credits 是這次扣除的積分,範例中的數字僅供參考。如果用相同的 Idempotency-Key 重複送出,會回傳 200 OK 和原本那筆任務。

{
  "public_id": "01K1M2N3P4Q5R6S7T8V9W0XY14",
  "type": 3,
  "status": 10,
  "credits": 5,
  "params": {
    "model": "YUYU_M5",
    "images": ["uploads/01K1M2N3P4Q5R6S7T8V9W0XY15.jpg"]
  },
  "result": null,
  "error_code": null,
  "error_message": null,
  "created_at": "2026-10-19T08:00:00.000000Z",
  "finished_at": null,
  "files_expire_at": null,
  "files_expired": false,
  "files": []
}

status 通常是 10(處理中),偶爾是 0(排隊中),兩種情況都只要等 Webhook 通知或查詢任務即可。這類任務的結果不是檔案,所以 files 永遠是空陣列,files_expire_at、files_expired 也不會用到。

偵測通常幾秒內就會完成。完成後(status = 20),Webhook 通知和 GET /api/tasks/{public_id} 的 result 會是:

{
  "result": {
    "face_coordinates": [
      { "index": 0, "bbox": [41, 49, 131, 146], "age": 4 },
      { "index": 1, "bbox": [328, 274, 415, 388], "age": 2 }
    ]
  }
}

圖中沒有人臉時,face_coordinates 會是空陣列 [],這是正常完成,不是失敗。偵測失敗時,任務會變成 30(失敗),並全額退回這次扣的積分。

參數表

欄位	型別	必填	說明
image	file	是	圖片檔,支援 PNG、JPG、JPEG、WebP,最大 10 MB
model	string	否	不填時使用 YUYU_M5
callback_url	string	否	任務結束時要通知的網址,需以 https:// 開頭,最多 2000 字。這類任務的通知會多帶 result,見下方說明

一次只能偵測一張圖片。要偵測多張,請每張各呼叫一次,每次會分別扣積分、產生各自的 public_id。

表格沒有列出的參數帶了會回傳 422,不會被忽略。

result.face_coordinates 欄位說明

欄位	說明
index	第幾張臉,從 0 開始
bbox	臉的位置 [x1, y1, x2, y2],也就是左上角和右下角的座標。單位是像素,以原始圖片為準
age	年齡分級(整數),對照表見下方

age 對照表

age	年齡
0	0–2 歲
1	3–9 歲
2	10–19 歲
3	20–29 歲
4	30–39 歲
5	40–49 歲
6	50–59 歲
7	60–69 歲
8 以上	70 歲以上

Webhook 通知的差異

人臉年齡偵測的 Webhook 通知會比其他任務多帶一個 result 欄位,直接附上偵測結果,不需要再查詢一次:

{
  "public_id": "01K1M2N3P4Q5R6S7T8V9W0XY14",
  "status": 20,
  "error_code": null,
  "payload": null,
  "result": {
    "face_coordinates": [
      { "index": 0, "bbox": [41, 49, 131, 146], "age": 4 }
    ]
  }
}

任務失敗時(status = 30),result 一樣會出現,但值是 null。其他任務(例如圖生影片)的通知不會帶 result,格式請見〈回呼(Webhook)〉。

錯誤情境

狀態碼	原因	回應內容
422	參數有誤,例如沒有上傳 image、檔案格式不支援、超過 10 MB、callback_url 格式錯誤	errors 欄位會列出每個欄位的錯誤原因
422	model 填了不存在的模型	{ "message": "Unknown model alias: {model}" }
402	積分不足	{ "message": "Insufficient credits to complete this charge." }
429	請求太頻繁,或排隊中的偵測任務太多	回應會帶 Retry-After header,請等待後再送

查詢進度請見〈任務查詢與取件〉,扣款規則請見〈積分與計費〉。

舊版 API

已經串接舊版 POST /api/tasks/detect-face 的話(用 JSON 送出、images 放一張 base64 data URI、model 必填、成功回傳 201 Created),可以繼續使用,不需要修改。偵測結果、Webhook 通知和計費都跟新版相同。

新串接請使用本頁的 POST /api/v2/tasks/detect-face。