偵測人臉

偵測一張圖片裡的所有人臉,回傳每張臉的邊界框座標與粗略年齡分級。需要合法的 X-Api-Key,依 model 計費,扣款規則見〈積分與計費〉。

model 可填 YUYU_M2 或 YUYU_M5,兩者的請求/回應格式完全相同,差別只在後端產能配置:YUYU_M2 與換臉任務共用同一批產能,YUYU_M5 是獨立配置的產能,不受換臉任務排隊影響。沒有特別需求時任選一個即可,下方範例以 YUYU_M2 示範,把 model 換成 YUYU_M5 即可改用獨立產能,其餘欄位不變。

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

完整範例

images 只接受恰好一張完整的 base64 data URI(png/jpeg/webp 三種 MIME 皆可),這裡為了範例簡短省略實際 base64 內容:

curl -X POST https://example.com/api/tasks/detect-face \
  -H "X-Api-Key: sk-live-xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YUYU_M2",
    "images": ["data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."],
    "callback_url": "https://example.com/webhooks/yuyu-detect-face"
  }'

成功回 201 Created(任務剛建立時是待派工狀態,result 尚無內容,credits 是這次實際扣款的積分,下方範例的數字僅為示意,實際以平台設定為準,見〈積分與計費〉）：

{
  "public_id": "01K1M2N3P4Q5R6S7T8V9W0XY14",
  "type": 3,
  "status": 0,
  "credits": 5,
  "params": {
    "model": "YUYU_M2",
    "images": ["data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."]
  },
  "result": null,
  "error_code": null,
  "error_message": null,
  "created_at": "2026-08-18T08:00:00.000000Z",
  "finished_at": null,
  "files_expire_at": null,
  "files_expired": false,
  "files": []
}

files_expire_at/files_expired/files 對這個任務類型沒有實際意義(結果不是檔案),永遠是 null/false/[],詳見〈任務查詢與取件〉。

任務完成後(status = 20),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 會是空陣列 [](這是正常完成,不是失敗)。

參數表

欄位	型別	必填	規則
model	string	是	YUYU_M2 或 YUYU_M5,二選一(差異見上方說明)
images	string[]	是	恰好 1 張,元素為完整 base64 data URI(data:image/{png|jpeg|webp};base64,...)
callback_url	string	否	必須是 https:// 開頭的網址,最長 2000 字;見〈回呼(Webhook)〉——這個任務類型的回呼內容比其他任務類型多帶一個欄位,見下方說明

一次只能偵測一張圖;要偵測多張圖,對每張圖各自呼叫一次這支端點即可(各自是獨立計費、獨立的 public_id)。

result.face_coordinates 欄位說明

欄位	說明
index	臉的索引,從 0 起算
bbox	臉部邊界框 [x1, y1, x2, y2],單位為像素,對應原始上傳圖片的座標系
age	年齡分級 ID(整數),對照表見下方

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 欄位——因為偵測結果只是一小段 JSON,直接帶在通知裡就能省去你再查詢一次的往返:

{
  "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)〉頁描述的一致,不受此例外影響。

回應

成功建立回 201 Created(冪等命中既有任務則回 200 OK),內容是〈任務查詢與取件〉描述的任務物件,type 為 3。

錯誤情境

狀態碼	情境	內容
422	參數驗證失敗(缺必填、images 不是恰好 1 張、data URI 格式不合法等)	Laravel 標準 errors 欄位驗證錯誤格式
422	model 值查無對應模型	{ "message": "Unknown model alias: {model}" }
402	積分(付費餘額或試用額度剩餘額度)不足以支付這次建單費用	{ "message": "Insufficient credits to complete this charge." }
429	你名下這個任務類型(偵測人臉)的待處理任務數已達上限	{ "message": "Too many pending tasks of this type; please retry later." },回應帶 Retry-After header

實際如何查詢進度、其他任務類型的計費規則,見〈任務查詢與取件〉與〈積分與計費〉。