From 3e81f7c16b90a717e2083ed9cb60078e0ecfb443 Mon Sep 17 00:00:00 2001 From: M5Max128 Date: Fri, 22 May 2026 10:08:08 +0800 Subject: [PATCH] docs: rebuild HTML + WASM doc after identity PATCH update --- docs_v1.0/doc/07_identity.html | 191 +++++++++++++++++++- docs_v1.0/doc/08_media.html | 205 ++++++++++++++++++++++ docs_v1.0/doc_wasm/modules/07_identity.md | 118 ++++++++++++- docs_v1.0/doc_wasm/pkg/md_wasm_bg.wasm | Bin 287032 -> 287032 bytes 4 files changed, 511 insertions(+), 3 deletions(-) diff --git a/docs_v1.0/doc/07_identity.html b/docs_v1.0/doc/07_identity.html index 6ec050b..2bedf0f 100644 --- a/docs_v1.0/doc/07_identity.html +++ b/docs_v1.0/doc/07_identity.html @@ -132,6 +132,93 @@ a { color: #0066cc; } Scope: identity-level

Delete an identity permanently.

+

PATCH /api/v1/identity/:identity_uuid

+

Auth: Required +Scope: identity-level

+

Partially update an identity. Only provided fields are modified. The name field is a display label and may repeat across identities (removed UNIQUE constraint). Aliases for multilingual display are stored in metadata.aliases (see BCP 47 reference below).

+

Request (JSON, all fields optional)

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
namestringNew display name
metadataobjectMerged into existing metadata. Use "aliases" key for locale-tagged names
statusstring"confirmed", "pending", or "skipped"
identity_typestring"people", "brand", "object", "concept", etc.
+

Example

+
# Update name and add aliases
+curl -s -X PATCH "$API/api/v1/identity/$IDENTITY_UUID" \
+  -H "X-API-Key: $KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "John Smith",
+    "metadata": {
+      "aliases": [
+        {"locale": "en", "name": "John Smith"},
+        {"locale": "zh-TW", "name": "約翰·史密斯"},
+        {"locale": "ja", "name": "ジョン・スミス"}
+      ]
+    }
+  }'
+
+# Update status only
+curl -s -X PATCH "$API/api/v1/identity/$IDENTITY_UUID" \
+  -H "X-API-Key: $KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"status": "confirmed"}'
+
+ +

Response (200)

+
{
+  "success": true,
+  "identity_uuid": "a9a901056d6b46ff92da0c3c1a57dff4",
+  "updated_fields": ["name", "metadata"]
+}
+
+ +

Error Responses

+ + + + + + + + + + + + + + + + + +
HTTPWhen
400No fields to update or invalid UUID format
404Identity not found
+

GET /api/v1/identity/:identity_uuid/files

Auth: Required Scope: identity-level

@@ -349,7 +436,7 @@ a { color: #0066cc; }

Auth: Required Scope: identity-level

Upload an identity.json file to create or update an identity. Accepts the same format as the identity.json files stored on disk.

-

If an identity with the same name already exists, it will be updated with the new values.

+

If an identity with the same identity_uuid already exists, it will be updated with the new values.

Request

The request body is an IdentityFile object:

@@ -512,7 +599,107 @@ a { color: #0066cc; }
-

Updated: 2026-05-19 12:49:24

+

Alias System (BCP 47 Locale Tags)

+

Identity aliases support multilingual display names. Aliases are stored in metadata.aliases as an array of {locale, name} objects.

+

BCP 47 Locale Tags Reference

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
LocaleTagExample
EnglishenJohn Smith
Traditional Chinesezh-TW約翰·史密斯
Simplified Chinesezh-CN约翰·史密斯
Japanesejaジョン・スミス
Koreanko존 스미스
Cantoneseyue約翰·史密夫
FrenchfrJohn Smith (French spelling)
SpanishesJuan Smith
Arabicarجون سميث
RussianruДжон Смит
Thaithจอห์น สมิธ
+

BCP 47 is the IETF standard for language tags. Format: language (e.g. en, ja) or language-Region (e.g. zh-TW, zh-CN). Region suffix distinguishes regional variants.

+

Frontend Display Logic

+
function getDisplayName(identity, preferredLocale) {
+  // 1. Exact locale match
+  const match = identity.metadata?.aliases?.find(a => a.locale === preferredLocale);
+  if (match) return match.name;
+
+  // 2. Language-only match (zh-TW → zh)
+  const lang = preferredLocale.split('-')[0];
+  const langMatch = identity.metadata?.aliases?.find(a => a.locale.startsWith(lang));
+  if (langMatch) return langMatch.name;
+
+  // 3. Fallback to identity.name
+  return identity.name;
+}
+
+ +

Updating Aliases via PATCH

+
PATCH /api/v1/identity/:identity_uuid
+{
+  "metadata": {
+    "aliases": [
+      {"locale": "en", "name": "John Smith"},
+      {"locale": "zh-TW", "name": "約翰·史密斯"}
+    ]
+  }
+}
+
+ +

This replaces the entire aliases array. To add to existing aliases, include all existing entries in the request.

+
+

*Updated: 2026-05-22

\ No newline at end of file diff --git a/docs_v1.0/doc/08_media.html b/docs_v1.0/doc/08_media.html index c75a1fc..fe451e0 100644 --- a/docs_v1.0/doc/08_media.html +++ b/docs_v1.0/doc/08_media.html @@ -81,6 +81,211 @@ a { color: #0066cc; }

Auth: Required Scope: file-level

+

GET /api/v1/file/:file_uuid/trace/:trace_id/representative-face

+

Find the best single face to represent this trace. Uses a two-stage selection: SQL (area × confidence → top 10) then FFmpeg blurdetect (sharpness → pick the least blurry).

+

Auth: Required +Scope: file-level

+

Example

+
curl -s "$API/api/v1/file/$FILE_UUID/trace/1939/representative-face" \
+  -H "X-API-Key: $KEY"
+
+ +

Response (200)

+
{
+  "success": true,
+  "file_uuid": "aeed71342a899fe4b4c57b7d41bcb692",
+  "trace_id": 1939,
+  "face_count": 538,
+  "representative": {
+    "frame_number": 68193,
+    "timestamp_secs": 2727.72,
+    "bbox": { "x": 347, "y": 378, "width": 427, "height": 427 },
+    "confidence": 0.760,
+    "quality_score": 138516,
+    "blur_score": 9.46
+  }
+}
+
+ +

Response Fields

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
trace_idintegerFace trace ID
face_countintegerTotal face detections in this trace
representative.frame_numberintegerFrame number of the selected face (primary coordinate)
representative.timestamp_secsfloatTime in seconds (derived from frame_number / fps)
representative.bboxobjectBounding box {x, y, width, height}
representative.confidencefloatDetection confidence (0.0–1.0)
representative.quality_scorefloatPre-selection score (area × confidence)
representative.blur_scorefloatFFmpeg blurdetect result (lower = sharper)
+

Error Responses

+
+

GET /api/v1/file/:file_uuid/trace/:trace_id/thumbnail

+

Extract the best face image for a trace as JPEG (320×320). Internally selects the face using the same two-stage algorithm as representative-face, then crops via FFmpeg. The result is cacheable for 24 hours.

+

Auth: Required +Scope: file-level

+

Example

+
curl -s "$API/api/v1/file/$FILE_UUID/trace/1939/thumbnail" \
+  -H "X-API-Key: $KEY" -o trace_1939_face.jpg
+
+ +

Response

+ +
+

GET /api/v1/file/:file_uuid/identities/:identity_uuid_a/co-occur-with/:identity_uuid_b

+

Find the first frame where two identities appear together, with representative face thumbnails for both.

+

Auth: Required +Scope: file-level

+

Example

+
# Audrey Hepburn & Cary Grant 第一次同框
+curl -s "$API/api/v1/file/$FILE_UUID/identities/$AUDREY_UUID/co-occur-with/$CARY_UUID" \
+  -H "X-API-Key: $KEY" | jq '{identity_a: .identity_a.name, identity_b: .identity_b.name, first_frame: .first_cooccurrence.frame_number}'
+
+ +

Response (200)

+
{
+  "success": true,
+  "file_uuid": "aeed71342a899fe4b4c57b7d41bcb692",
+  "identity_a": {
+    "identity_uuid": "c3545906-c82d-4b66-aa1d-150bc02decce",
+    "name": "Audrey Hepburn",
+    "trace_id": 920
+  },
+  "identity_b": {
+    "identity_uuid": "2b0ddefe-e2a9-4533-9308-b375594604d5",
+    "name": "Cary Grant",
+    "trace_id": 919
+  },
+  "first_cooccurrence": {
+    "frame_number": 38165,
+    "timestamp_secs": 1526.60,
+    "total_cooccurrence_frames": 3136,
+    "representative_face_a": {
+      "frame_number": 38199,
+      "bbox": { "x": 122, "y": 339, "width": 176, "height": 176 },
+      "confidence": 0.832,
+      "thumbnail_url": "/api/v1/file/aeed71342.../trace/920/thumbnail"
+    },
+    "representative_face_b": {
+      "frame_number": 38291,
+      "bbox": { "x": 511, "y": 315, "width": 192, "height": 192 },
+      "confidence": 0.791,
+      "thumbnail_url": "/api/v1/file/aeed71342.../trace/919/thumbnail"
+    }
+  }
+}
+
+ +

Response Fields

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
identity_a.namestringFirst identity name
identity_b.namestringSecond identity name
first_cooccurrence.frame_numberintFirst frame where both appear
first_cooccurrence.timestamp_secsfloatTime in seconds
first_cooccurrence.total_cooccurrence_framesintTotal frames with both present
first_cooccurrence.representative_face_a/bobjectBest face thumbnail data for each identity
+

Error Responses

+ + + + + + + + + + + + + + + + + + + + + +
HTTPWhen
404File or identity not found
404The two identities never co-occur in this file
500Database or FFmpeg error

GET /api/v1/file/:file_uuid/video/bbox

Stream video with bounding box overlay for all detected objects/faces.

Auth: Required diff --git a/docs_v1.0/doc_wasm/modules/07_identity.md b/docs_v1.0/doc_wasm/modules/07_identity.md index d0ca1b1..66dc65a 100644 --- a/docs_v1.0/doc_wasm/modules/07_identity.md +++ b/docs_v1.0/doc_wasm/modules/07_identity.md @@ -74,6 +74,66 @@ Delete an identity permanently. --- +### `PATCH /api/v1/identity/:identity_uuid` + +**Auth**: Required +**Scope**: identity-level + +Partially update an identity. Only provided fields are modified. The `name` field is a display label and may repeat across identities (removed UNIQUE constraint). Aliases for multilingual display are stored in `metadata.aliases` (see BCP 47 reference below). + +#### Request (JSON, all fields optional) + +| Field | Type | Description | +|-------|------|-------------| +| `name` | string | New display name | +| `metadata` | object | Merged into existing metadata. Use `"aliases"` key for locale-tagged names | +| `status` | string | `"confirmed"`, `"pending"`, or `"skipped"` | +| `identity_type` | string | `"people"`, `"brand"`, `"object"`, `"concept"`, etc. | + +#### Example + +```bash +# Update name and add aliases +curl -s -X PATCH "$API/api/v1/identity/$IDENTITY_UUID" \ + -H "X-API-Key: $KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "John Smith", + "metadata": { + "aliases": [ + {"locale": "en", "name": "John Smith"}, + {"locale": "zh-TW", "name": "約翰·史密斯"}, + {"locale": "ja", "name": "ジョン・スミス"} + ] + } + }' + +# Update status only +curl -s -X PATCH "$API/api/v1/identity/$IDENTITY_UUID" \ + -H "X-API-Key: $KEY" \ + -H "Content-Type: application/json" \ + -d '{"status": "confirmed"}' +``` + +#### Response (200) + +```json +{ + "success": true, + "identity_uuid": "a9a901056d6b46ff92da0c3c1a57dff4", + "updated_fields": ["name", "metadata"] +} +``` + +#### Error Responses + +| HTTP | When | +|------|------| +| `400` | No fields to update or invalid UUID format | +| `404` | Identity not found | + +--- + ### `GET /api/v1/identity/:identity_uuid/files` **Auth**: Required @@ -330,7 +390,63 @@ curl -s "$API/api/v1/identity/$IDENTITY_UUID/profile-image" \ |----------------|-------| | `content-type` | `image/jpeg` or `image/png` | +--- +## Alias System (BCP 47 Locale Tags) + +Identity aliases support multilingual display names. Aliases are stored in `metadata.aliases` as an array of `{locale, name}` objects. + +### BCP 47 Locale Tags Reference + +| Locale | Tag | Example | +|--------|-----|---------| +| English | `en` | John Smith | +| Traditional Chinese | `zh-TW` | 約翰·史密斯 | +| Simplified Chinese | `zh-CN` | 约翰·史密斯 | +| Japanese | `ja` | ジョン・スミス | +| Korean | `ko` | 존 스미스 | +| Cantonese | `yue` | 約翰·史密夫 | +| French | `fr` | John Smith (French spelling) | +| Spanish | `es` | Juan Smith | +| Arabic | `ar` | جون سميث | +| Russian | `ru` | Джон Смит | +| Thai | `th` | จอห์น สมิธ | + +BCP 47 is the IETF standard for language tags. Format: `language` (e.g. `en`, `ja`) or `language-Region` (e.g. `zh-TW`, `zh-CN`). Region suffix distinguishes regional variants. + +### Frontend Display Logic + +```javascript +function getDisplayName(identity, preferredLocale) { + // 1. Exact locale match + const match = identity.metadata?.aliases?.find(a => a.locale === preferredLocale); + if (match) return match.name; + + // 2. Language-only match (zh-TW → zh) + const lang = preferredLocale.split('-')[0]; + const langMatch = identity.metadata?.aliases?.find(a => a.locale.startsWith(lang)); + if (langMatch) return langMatch.name; + + // 3. Fallback to identity.name + return identity.name; +} +``` + +### Updating Aliases via PATCH + +```json +PATCH /api/v1/identity/:identity_uuid +{ + "metadata": { + "aliases": [ + {"locale": "en", "name": "John Smith"}, + {"locale": "zh-TW", "name": "約翰·史密斯"} + ] + } +} +``` + +This **replaces** the entire `aliases` array. To add to existing aliases, include all existing entries in the request. --- -*Updated: 2026-05-19 12:49:24* +*Updated: 2026-05-22 diff --git a/docs_v1.0/doc_wasm/pkg/md_wasm_bg.wasm b/docs_v1.0/doc_wasm/pkg/md_wasm_bg.wasm index bad117da3e35d70d018adebd9a1a986c3cdb01ea..c1fdac78ee3352ccb6e7d5fd52d6decbdf9d4f2b 100644 GIT binary patch delta 24 gcmdmSNN~p?!G;#b7N!>FEiBy$j7HOY5?Iy%0DLqFG5`Po delta 24 gcmdmSNN~p?!G;#b7N!>FEiBy$jE2*D5?Iy%0DLY9F#rGn