운영:    https://api.wiastandards.com/emotion-ai/v1
스테이징: https://api-staging.wiastandards.com/emotion-ai/v1

헤더: X-WIA-API-Key: your_api_key_here

예시 요청:
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"}'

헤더: Authorization: Bearer <access_token>

토큰 엔드포인트: POST /oauth/token
스코프:
  - emotion:read    - 감정 분석 결과 읽기
  - emotion:analyze - 분석 콘텐츠 제출
  - emotion:stream  - 실시간 스트리밍 접근

POST /v1/analyze/face

요청 본문:
{
    "image_url": "https://example.com/face.jpg",
    // 또는
    "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
    }
}

응답 (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 }
            ]
        }
    ]
}

POST /v1/analyze/face/video

요청 본문:
{
    "video_url": "https://example.com/video.mp4",
    // 또는
    "frames_base64": ["data:image/jpeg;base64,...", ...],

    "options": {
        "sample_rate": 5,
        "start_time_ms": 0,
        "end_time_ms": 10000,
        "track_faces": true
    }
}

응답 (200 OK):
{
    "request_id": "req_video123",
    "duration_ms": 10000,
    "frame_count": 60,
    "analyzed_frames": 12,
    "timeline": [
        {
            "timestamp_ms": 0,
            "faces": [{ ... }]
        },
        {
            "timestamp_ms": 833,
            "faces": [{ ... }]
        }
    ],
    "summary": {
        "dominant_emotion": "happiness",
        "average_valence": 0.65,
        "average_arousal": 0.42,
        "emotion_transitions": 3
    }
}

POST /v1/analyze/voice

요청 본문:
{
    "audio_url": "https://example.com/audio.wav",
    "options": {
        "language": "ko-KR",
        "return_transcript": true,
        "return_prosody": true,
        "segment_by": "utterance"
    }
}

응답 (200 OK):
{
    "request_id": "req_voice456",
    "duration_ms": 5500,
    "language_detected": "ko-KR",
    "transcript": "정말 기뻐요!",
    "emotions": {
        "primary": { "label": "happiness", "confidence": 0.85 }
    },
    "dimensions": {
        "valence": 0.78,
        "arousal": 0.65
    },
    "prosody": {
        "pitch_mean_hz": 220.5,
        "pitch_range_hz": 95.3,
        "intensity_db": 65.2,
        "speech_rate_wpm": 130,
        "pause_ratio": 0.18
    }
}

POST /v1/analyze/voice/stream
요청: WebSocket 업그레이드 (제6장 참조)

초기 메시지:
{
    "type": "config",
    "sample_rate": 16000,
    "encoding": "LINEAR16",
    "language": "ko-KR"
}

오디오 청크: 바이너리 PCM 데이터

응답 메시지:
{ "type": "partial", "timestamp_ms": 1500, "emotion": { "label": "neutral", "confidence": 0.7 } }
{ "type": "final", "segment": { "start_ms": 0, "end_ms": 3000, "text": "안녕하세요", "emotion": { "label": "happiness", "confidence": 0.82 } } }

POST /v1/analyze/text

요청 본문:
{
    "text": "이 제품 정말 좋아요! 최고의 구매!",
    "language": "ko",
    "options": {
        "return_aspects": true,
        "return_entities": true,
        "detect_sarcasm": true
    }
}

응답 (200 OK):
{
    "request_id": "req_text789",
    "text_length": 18,
    "language": "ko",
    "sentiment": {
        "polarity": 0.92,
        "subjectivity": 0.85,
        "label": "very_positive"
    },
    "emotions": {
        "primary": { "label": "happiness", "confidence": 0.91 }
    },
    "dimensions": {
        "valence": 0.88,
        "arousal": 0.65
    },
    "aspects": [
        { "aspect": "제품", "sentiment": 0.95 }
    ],
    "sarcasm": { "detected": false, "confidence": 0.02 }
}

POST /v1/analyze/text/batch

요청 본문:
{
    "texts": [
        { "id": "review_1", "text": "최고의 제품!" },
        { "id": "review_2", "text": "끔찍한 경험." },
        { "id": "review_3", "text": "그냥 보통이에요." }
    ],
    "language": "ko"
}

응답 (200 OK):
{
    "request_id": "req_batch001",
    "results": [
        { "id": "review_1", "sentiment": { "polarity": 0.85, "label": "positive" } },
        { "id": "review_2", "sentiment": { "polarity": -0.78, "label": "negative" } },
        { "id": "review_3", "sentiment": { "polarity": 0.1, "label": "neutral" } }
    ],
    "summary": {
        "average_sentiment": 0.06,
        "positive_count": 1,
        "negative_count": 1,
        "neutral_count": 1
    }
}

POST /v1/analyze/biosignal

요청 본문:
{
    "signals": {
        "ecg": { "sample_rate": 256, "data": [0.12, 0.15, ...], "unit": "mV" },
        "eda": { "sample_rate": 4, "data": [2.5, 2.6, ...], "unit": "uS" }
    },
    "duration_ms": 60000,
    "options": { "return_hrv": true, "return_stress": true, "return_engagement": true }
}

응답 (200 OK):
{
    "request_id": "req_bio001",
    "duration_ms": 60000,
    "heart_rate": { "mean_bpm": 72, "min_bpm": 65, "max_bpm": 82 },
    "hrv": { "rmssd_ms": 42.5, "sdnn_ms": 55.3 },
    "eda": { "scl_mean": 3.2, "scr_count": 5 },
    "derived_states": {
        "stress_level": 0.35,
        "relaxation": 0.55,
        "engagement": 0.72
    }
}

POST /v1/analyze/multimodal

요청 본문:
{
    "modalities": {
        "face": { "image_url": "https://example.com/face.jpg" },
        "voice": { "audio_url": "https://example.com/audio.wav" },
        "text": { "text": "오늘 기분 정말 좋아요!" }
    },
    "fusion": {
        "method": "weighted_average",
        "weights": { "face": 0.5, "voice": 0.3, "text": 0.2 }
    }
}

응답 (200 OK):
{
    "request_id": "req_multi001",
    "fused_result": {
        "emotions": { "primary": { "label": "happiness", "confidence": 0.88 } },
        "dimensions": { "valence": 0.75, "arousal": 0.52 }
    },
    "modality_results": {
        "face": { "emotions": { "primary": { "label": "happiness", "confidence": 0.85 } } },
        "voice": { "emotions": { "primary": { "label": "happiness", "confidence": 0.82 } } },
        "text": { "emotions": { "primary": { "label": "happiness", "confidence": 0.90 } } }
    },
    "fusion_details": {
        "method": "weighted_average",
        "weights_used": { "face": 0.5, "voice": 0.3, "text": 0.2 },
        "agreement_score": 0.92
    }
}

{
    "error": {
        "code": "INVALID_IMAGE",
        "message": "제공된 이미지를 처리할 수 없습니다",
        "details": {
            "reason": "이미지에서 얼굴을 탐지하지 못했습니다",
            "suggestion": "얼굴이 명확히 보이는 이미지를 사용해 주십시오"
        }
    },
    "request_id": "req_err001"
}