Hongik Ingan (εΌηδΊΊι)
"Benefit All Humanity"
A well-designed API allows developers to integrate emotion recognition into their applications without binding them to any particular underlying implementation. A standardised interface prevents vendor lock-in, lowers development cost, and increases user trust. This chapter specifies the RESTful endpoints, authentication, request and response formats, per-modality call patterns, error handling, and rate-limiting that compose Phase 2, with cross-references to web-security standards (OWASP, IETF RFCs) and to relevant cloud-security certifications.
| Principle | Implementation |
|---|---|
| RESTful | Standard HTTP methods, resource-oriented URLs |
| JSON | All requests and responses use JSON |
| Versioning | API version in the URL path (/v1/) |
| Authentication | API key or OAuth 2.0 |
| Rate limiting | Limits clearly exposed in response headers |
The five principles incorporate IETF, W3C, and OWASP best practice. All requests must be transported over TLS 1.2 or above (TLS 1.3 recommended).[1] Systems deployed on cloud providers that hold local cloud-security certifications (for example, the relevant national cloud-security certification scheme, ISO/IEC 27017:2015 for cloud services, and ISO/IEC 27018:2019 for PII processing in public clouds) automatically meet a portion of the standard's security requirements.
RESTful design represents resources by URL and operations by HTTP method (GET, POST, PUT, DELETE). Because emotion-analysis calls are predominantly verbs rather than resource-state mutations, WIA Phase 2 uses POST for analysis calls and reserves GET and DELETE for status retrieval and cancellation. This pattern is common in OpenAPI 3.0 specifications and is naturally supported by FastAPI, Spring Boot, and Express.[2]
Versioning is performed by major-version path segment (/v1/, /v2/, β¦). Minor changes preserve backwards compatibility and are made without changing the URL; major changes are issued at a new path so that existing callers are unaffected. The minimum parallel-operation period for adjacent major versions is twelve months, ensuring users have sufficient time to migrate.
Production: https://api.wiastandards.com/emotion-ai/v1 Staging: https://api-staging.wiastandards.com/emotion-ai/v1
Five regional endpoints are operated (US, EU, KR, SG, BR) so that callers subject to local data-residency requirements can pick a region whose data-protection regime they have already mapped against. The response header X-WIA-Region echoes the region that processed each request, supporting auditable proofs of processing location. Inter-region latency is published in real time on the standard status page.
Header: X-WIA-API-Key: your_api_key_here
Example request:
curl -X POST https://api.wiastandards.com/emotion-ai/v1/analyze/face \
-H "X-WIA-API-Key: EXAMPLE_API_KEY_REPLACE_ME" \
-H "Content-Type: application/json" \
-d '{"image_url": "https://example.com/face.jpg"}'
API keys are transported only over HTTPS and only as a request header; carriage in query strings is forbidden because of the exposure that would result through server logs, browser history, and intermediate proxies. Keys are rotated quarterly by default; users are notified thirty days before rotation. Users typically maintain a small set of keys (for example one production key and one staging key); production keys carry stricter access controls (IP allow-listing, time-of-day restriction). Compromised keys can be revoked immediately, with replacement issued instantly. Many jurisdictions require notification of credential leakage to the relevant data-protection authority within twenty-four to seventy-two hours of detection.
Header: Authorization: Bearer <access_token> Token endpoint: POST /oauth/token Scopes: - emotion:read - Read emotion-analysis results - emotion:analyze - Submit content for analysis - emotion:stream - Access real-time streaming
OAuth 2.0 (IETF RFC 6749, RFC 6750) is recommended for multi-user environments and where delegated authentication is needed; OpenID Connect (OIDC) is supported in an annex for cases that require federated identity.[3] Of the OAuth 2.0 grant flows, WIA supports Authorization Code Grant (for web applications), Client Credentials Grant (for server-to-server communication), and Refresh Token Grant (for access-token renewal). Resource-Owner Password Credentials and Implicit Grant are not supported, in line with OAuth 2.1's deprecation guidance. The default access-token lifetime is one hour and the refresh-token lifetime is thirty days.
POST /v1/analyze/face
Request body:
{
"image_url": "https://example.com/face.jpg",
// or:
"image_base64": "data:image/jpeg;base64,/9j/4AAQ...",
"options": {
"return_action_units": true,
"return_dimensions": true,
"return_landmarks": false,
"min_face_size": 50,
"max_faces": 5
}
}
Response (200 OK):
{
"request_id": "req_abc123",
"processing_time_ms": 145,
"faces": [
{
"face_id": 0,
"bbox": { "x": 120, "y": 80, "width": 200, "height": 250 },
"emotions": {
"primary": { "label": "happiness", "confidence": 0.87 },
"all": [
{ "label": "happiness", "confidence": 0.87 },
{ "label": "neutral", "confidence": 0.08 },
{ "label": "surprise", "confidence": 0.05 }
]
},
"dimensions": { "valence": 0.72, "arousal": 0.45 },
"action_units": [
{ "au": "AU6", "intensity": 0.8 },
{ "au": "AU12", "intensity": 0.9 }
]
}
]
}
Either an image URL or a base64-encoded payload may be supplied. URL inputs are fetched through the WIA infrastructure and processed in the region that received the request. Base64 inputs are useful for client-side applications that wish to avoid hosting the source image. The maximum payload size is 10 MB.
Video analysis is a long-running operation: the response is asynchronous, returning a job identifier that the caller polls (or that triggers a webhook) when analysis completes. Maximum video duration is sixty minutes; supported codecs are H.264 (AVC) and VP9.
POST /v1/analyze/voice
Request body:
{
"audio_url": "https://example.com/sample.wav",
"options": {
"return_dimensions": true,
"return_features": true,
"language_hint": "en-US"
}
}
Response (200 OK):
{
"request_id": "req_def456",
"processing_time_ms": 382,
"duration_sec": 12.3,
"emotions": { "primary": { "label": "anger", "confidence": 0.79 } },
"dimensions": { "valence": -0.61, "arousal": 0.74 },
"voice_features": {
"pitch_mean_hz": 232.4,
"speech_rate_wpm": 178,
"voice_quality": "tense"
}
}
Supported codecs are WAV (PCM 16-bit), MP3, and WebM (Opus). The recommended sample rate is 44.1 kHz; 16 kHz is the minimum for telephony-quality input. Two-party-consent jurisdictions require call participants to be notified that voice analysis is occurring (see Β§2.3.1 and the conformance check at Β§2.8 item 11).
POST /v1/analyze/text
Request body:
{
"text": "I cannot believe how amazing this is!",
"options": { "language": "en", "return_aspects": true }
}
Response (200 OK):
{
"emotions": { "primary": { "label": "happiness", "confidence": 0.93 } },
"sentiment": { "polarity": "positive", "score": 0.95 },
"aspects": [
{ "entity": "service", "polarity": "positive", "score": 0.91 }
]
}
Aspect-based sentiment analysis (ABSA) decomposes a single text into entity-specific sentiment scores, supporting product-review and customer-feedback applications. Language identification is automatic when not specified. The maximum text length is ten thousand characters per request; longer inputs are split client-side and aggregated.
POST /v1/analyze/biosignal
Request body:
{
"signal_type": "ecg",
"samples": [/* ECG amplitude values */],
"sample_rate_hz": 250,
"duration_sec": 30
}
Response (200 OK):
{
"heart_rate_bpm": 78,
"hrv_rmssd_ms": 42.3,
"stress_index": 0.71,
"dimensions": { "arousal": 0.62 }
}
Biosignal endpoints accept arrays of raw samples or pre-extracted features. For health-related deployments a regulator-approved Software-as-a-Medical-Device (SaMD) classification is required; the relevant cross-walk is given in Β§7.4.
POST /v1/analyze/multimodal
Request body:
{
"modalities": {
"face": { "image_url": "https://example.com/face.jpg" },
"voice": { "audio_url": "https://example.com/sample.wav" },
"text": { "text": "I cannot believe how amazing this is!" }
},
"fusion": {
"strategy": "late",
"weights": { "face": 0.40, "voice": 0.35, "text": 0.25 }
}
}
The same fusion strategies introduced in Β§3.6 are exposed as request parameters. When the strategy parameter is omitted, late fusion is the default.
| HTTP status | Error code | Meaning |
|---|---|---|
| 400 | invalid_input | Request body fails schema validation |
| 401 | unauthorised | Missing or invalid API key / OAuth token |
| 403 | forbidden_use | Request matches a prohibited-use list entry |
| 413 | payload_too_large | Body exceeds the 10 MB limit |
| 429 | rate_limited | Caller exceeded the per-minute request limit |
| 503 | region_unavailable | Selected region is undergoing maintenance |
Error responses follow Problem Details for HTTP APIs (IETF RFC 7807) and include type, title, status, detail, and instance. The detail string is human-readable and avoids leaking implementation details that would aid an attacker.[4]
Rate limits are exposed in standard headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and on 429 responses Retry-After). Default limits are sixty requests per minute for the free tier and per-account configurable limits for paid tiers. Burst tolerance follows the token-bucket model; bursts above three times the steady-state rate are rejected with HTTP 429.
The Korean edition of this volume contains additional sections on Korean cloud-security certification (the relevant national cloud-security scheme), Korean PIMS / ISMS-P certification format requirements for API endpoints, named domestic cloud providers as candidate hosting environments, and OIDC integration with named domestic identity providers. These passages are most actionable for Korean readers and are retained in the Korean edition.
This English edition deliberately abstracts those passages. References to specific Korean schemes, providers, or platforms become "the relevant national cloud-security certification scheme", "leading domestic cloud providers", or "leading platform companies". The conformance requirements themselves are identical between the two editions.
Seven key takeaways.
X-WIA-Region response header supports data-residency audits.Chapter 6 turns to Phase 3 β the Streaming Protocol β which extends the request-response model of Phase 2 to continuous, low-latency channels suitable for driver monitoring, contact-centre call analytics, and interactive games. The simulator's π‘ Protocol panel (Panel 2) visualises the STREAMING / STOPPED state machine described in Phase 3. The standard's evolution roadmap is recorded in the public GitHub repository.[99]
WIA-Official/wia-standards-public/tree/main/emotion-ai. The standard's evolution roadmap, revision history, and SDK source code are maintained openly in this repository, where the WIA standards committee records its formal verification of all primary sources cited in this chapter. β