11 KiB
11 KiB
對話練習 API
概述
對話練習API負責管理AI驅動的互動式對話學習體驗，包括場景式對話、實時AI分析回饋、回覆輔助系統和翻譯支援。
API 端點
對話系統 (Dialogue System)
開始對話練習
POST /api/v1/dialogues/start
Authorization: Bearer <access_token>
{
"scenario_id": "SC_Restaurant_01",
"difficulty_override": "A2", // optional
"target_vocabulary": ["reservation", "menu", "order"], // optional
"practice_mode": "guided", // guided, free_form, challenge
"language_focus": ["grammar", "vocabulary", "pronunciation"] // optional
}
Response 201 Created
{
"success": true,
"data": {
"dialogue_id": "DLG_20240905_001",
"scenario_id": "SC_Restaurant_01",
"session_token": "session_token_here",
"practice_mode": "guided",
"initial_context": {
"setting": "高級餐廳內部，晚上8點",
"your_role": "客人",
"ai_role": "餐廳服務員",
"objective": "成功預約並點餐",
"cultural_notes": "西式正式餐廳環境，需要適當的禮貌用語"
},
"ai_message": {
"message": "Good evening! Welcome to Milano Restaurant. Do you have a reservation?",
"audio_url": "https://cdn.example.com/audio/dlg001_001.mp3",
"phonetic": "ɡʊd ˈivnɪŋ! ˈwɛlkəm tu mɪˈlɑnoʊ ˈrɛstərɑnt. du ju hæv ə ˌrɛzərˈveɪʃən?",
"suggestions": [
{
"text": "Yes, I have a reservation under Smith.",
"difficulty": "A2",
"appropriateness": "formal"
},
{
"text": "No, but could we get a table for two?",
"difficulty": "A2",
"appropriateness": "polite"
},
{
"text": "I'd like to make a reservation for tonight.",
"difficulty": "B1",
"appropriateness": "formal"
}
],
"vocabulary_hints": [
{
"word": "reservation",
"definition": "預約",
"usage_note": "正式場合的預約用詞"
}
]
},
"dialogue_settings": {
"time_limit": 600, // seconds, null for unlimited
"assistance_available": true,
"hints_remaining": 3,
"auto_feedback": true
}
}
}
發送對話訊息
POST /api/v1/dialogues/{dialogue_id}/message
Authorization: Bearer <access_token>
{
"message": "Yes, I have a reservation under Chen for 8 PM.",
"message_type": "text", // text, audio
"audio_url": "https://cdn.example.com/user_audio/msg001.mp3", // if audio
"request_feedback": true, // optional, default true
"confidence_level": 4 // 1-5 scale, optional
}
Response 200 OK
{
"success": true,
"data": {
"ai_response": {
"message": "Perfect! Mr. Chen, your table for two is ready. Right this way please.",
"audio_url": "https://cdn.example.com/audio/dlg001_002.mp3",
"phonetic": "ˈpɜrfɪkt! ˈmɪstər ʧɛn, jʊr ˈteɪbəl fɔr tu ɪz ˈrɛdi. raɪt ðɪs weɪ pliz.",
"emotion": "friendly_professional",
"speaking_pace": "normal",
"analysis": {
"grammar_score": 90,
"semantic_score": 95,
"fluency_score": 85,
"pronunciation_score": 88,
"overall_score": 90,
"feedback": "Excellent use of formal language for restaurant context!",
"detailed_analysis": {
"grammar_issues": [],
"vocabulary_usage": [
{
"word": "reservation",
"correctness": "perfect",
"context_appropriateness": "excellent"
}
],
"pronunciation_notes": [
{
"word": "reservation",
"accuracy": 0.92,
"suggestion": "輕微的r音可以更清晰"
}
]
}
},
"suggestions": [
{
"text": "Thank you. Could we see the menu please?",
"reason": "自然的下一步動作",
"difficulty": "A2"
},
{
"text": "Great! What do you recommend today?",
"reason": "顯示興趣並尋求建議",
"difficulty": "B1"
},
{
"text": "Thank you. We'd like to start with drinks.",
"reason": "具體的點餐開始",
"difficulty": "A2"
}
]
},
"dialogue_progress": {
"turns_completed": 2,
"estimated_turns_remaining": 6,
"objectives_completed": ["greeting", "reservation_confirmation"],
"objectives_remaining": ["ordering", "payment"],
"completion_percentage": 25,
"current_phase": "seating_and_menu"
},
"session_stats": {
"total_time_elapsed": 45, // seconds
"average_response_time": 8.5,
"hints_used": 0,
"mistakes_count": 0
}
}
}
結束對話
POST /api/v1/dialogues/{dialogue_id}/complete
Authorization: Bearer <access_token>
{
"completion_type": "natural", // natural, forced, timeout
"user_satisfaction": 4 // 1-5 scale, optional
}
Response 200 OK
{
"success": true,
"data": {
"dialogue_summary": {
"dialogue_id": "DLG_20240905_001",
"completion_type": "natural",
"duration": 420, // seconds
"turns_completed": 8,
"final_score": 88,
"grade": "B+",
"objectives_achieved": 4,
"objectives_total": 4,
"vocabulary_practiced": 12,
"new_vocabulary_learned": 3,
"mistakes_count": 2,
"hints_used": 1
},
"rewards": {
"experience_points": 150,
"score_points": 75,
"diamonds_earned": 25,
"achievements_unlocked": ["First Perfect Dialogue", "Restaurant Master"],
"vocabulary_progress": {
"words_advanced": 3,
"words_mastered": 1,
"review_words_generated": 2
}
},
"performance_analysis": {
"strongest_areas": ["vocabulary_usage", "cultural_appropriateness"],
"improvement_areas": ["pronunciation", "sentence_variety"],
"next_recommended_scenarios": [
{
"scenario_id": "SC_Restaurant_02",
"title": "餐廳點餐進階",
"reason": "Continue building on restaurant vocabulary"
}
]
},
"certificate": {
"available": true,
"certificate_url": "https://cdn.example.com/certificates/DLG_20240905_001.pdf"
}
}
}
回覆輔助系統
獲取回覆輔助
POST /api/v1/dialogues/{dialogue_id}/assistance
Authorization: Bearer <access_token>
{
"assistance_type": "reply_guidance", // reply_guidance, translation, vocabulary_help
"context": {
"partner_message": "Good morning! How is your day going?",
"scenario_context": "friendly morning greeting at office",
"user_language_level": "A2",
"dialogue_history": [
{
"speaker": "partner",
"message": "Hello! Nice to meet you."
},
{
"speaker": "user",
"message": "Nice to meet you too."
}
]
}
}
Response 200 OK
{
"success": true,
"data": {
"assistance_id": "AST_20240905_001",
"assistance_type": "reply_guidance",
"analysis": {
"partner_intent": {
"intent": "friendly_greeting_inquiry",
"emotion": "positive_friendly",
"expectation": "positive_response_about_day",
"cultural_context": "Western casual workplace greeting",
"explanation": "對方是在進行友好的早晨問候，期待你分享今天的狀況或心情"
},
"response_guidance": {
"thinking_process": [
"對方表現友好，我應該同樣友善回應",
"這是詢問我今天的狀況，我可以簡單分享",
"可以考慮反問對方相同的問題表示關心"
],
"response_strategies": [
{
"strategy": "positive_sharing",
"description": "積極分享今天的狀況",
"tone": "upbeat"
},
{
"strategy": "brief_polite",
"description": "簡潔禮貌的回應",
"tone": "neutral_friendly"
},
{
"strategy": "reciprocal_inquiry",
"description": "回應後反問對方",
"tone": "engaging"
}
]
},
"reply_examples": [
{
"example": "Great, thank you! I'm feeling energetic today. How about you?",
"level": "A2",
"style": "friendly_reciprocal",
"explanation": "表達積極心情並反問對方，展現對話技巧"
},
{
"example": "Pretty good, thanks for asking!",
"level": "A2",
"style": "casual_brief",
"explanation": "簡潔友善的回應，適合快節奏對話"
},
{
"example": "It's going well so far! Just got to the office. What about your day?",
"level": "B1",
"style": "detailed_engaging",
"explanation": "提供更多細節並主動延續對話"
}
]
},
"cost_deducted": {
"item_type": "reply_hint",
"quantity": 1,
"remaining_quantity": 4
}
}
}
翻譯輔助
POST /api/v1/translation/assistance
Authorization: Bearer <access_token>
{
"source_text": "今天天氣真好，讓我心情很愉快",
"context": {
"dialogue_scenario": "casual_conversation",
"formality_level": "informal",
"target_language_level": "A2",
"cultural_adaptation": true
}
}
Response 200 OK
{
"success": true,
"data": {
"translation_result": {
"primary_translation": "The weather is really nice today, it makes me feel happy.",
"alternative_translations": [
{
"text": "It's such a beautiful day today, I'm in a great mood!",
"level": "B1",
"style": "enthusiastic"
},
{
"text": "Today's nice weather is making me cheerful.",
"level": "A2",
"style": "simple_clear"
}
],
"grammar_notes": [
{
"point": "weather_description",
"explanation": "英文描述天氣常用 'The weather is + adjective' 句型"
},
{
"point": "causative_structure",
"explanation": "'makes me feel + adjective' 表達某事讓你產生某種感受"
}
],
"vocabulary_highlights": [
{
"chinese": "心情愉快",
"english": "feel happy / in a good mood",
"note": "英文有多種表達好心情的方式"
}
],
"cultural_adaptation": {
"original_style": "direct_emotional_expression",
"adapted_style": "moderate_positive_expression",
"explanation": "調整為西方文化中更常見的表達方式"
}
}
}
}
錯誤處理
對話練習相關錯誤
DIALOGUE_NOT_FOUND: 對話不存在DIALOGUE_ALREADY_COMPLETED: 對話已完成DIALOGUE_EXPIRED: 對話會話已過期SCENARIO_NOT_ACCESSIBLE: 場景不可訪問INVALID_MESSAGE_FORMAT: 無效的訊息格式AUDIO_PROCESSING_FAILED: 音頻處理失敗AI_ANALYSIS_UNAVAILABLE: AI分析服務不可用
輔助系統相關錯誤
INSUFFICIENT_REPLY_HINTS: 回覆提示道具不足ASSISTANCE_NOT_AVAILABLE: 輔助功能不可用TRANSLATION_SERVICE_ERROR: 翻譯服務錯誤DAILY_HINT_LIMIT_EXCEEDED: 超過每日提示使用限制DIALOGUE_HINT_LIMIT_EXCEEDED: 超過單次對話提示使用限制INVALID_ASSISTANCE_TYPE: 無效的輔助類型CONTEXT_INSUFFICIENT: 上下文資訊不足LANGUAGE_PAIR_NOT_SUPPORTED: 不支援的語言對
建立日期: 2025-09-08
API版本: v1
負責模組: 對話練習系統