refactor(api): standardize responses and restore media config contracts

app/schemas/openai.py

@@ -1,7 +1,9 @@
-from typing import Any, Dict, List, Optional
+from typing import Dict, List, Optional
 
 from pydantic import BaseModel, ConfigDict, Field
 
+from app.schemas.common import JsonData
+
 
 class OpenAIModelInfo(BaseModel):
     id: str
@@ -16,14 +18,18 @@ class OpenAIModelListResponse(BaseModel):
 
 
 class OpenAIChatMessage(BaseModel):
+    """OpenAI Chat Completions 请求中的一条消息。"""
+
     role: str
-    content: Any
+    content: JsonData
     name: Optional[str] = None
 
     model_config = ConfigDict(extra="allow")
 
 
 class OpenAIChatCompletionsRequest(BaseModel):
+    """OpenAI Chat Completions 兼容请求。"""
+
     model: Optional[str] = None
     messages: List[OpenAIChatMessage]
     user: Optional[str] = None
@@ -33,8 +39,10 @@ class OpenAIChatCompletionsRequest(BaseModel):
 
 
 class OpenAIResponsesRequest(BaseModel):
+    """OpenAI Responses API 兼容请求。"""
+
     model: Optional[str] = None
-    input: Any
+    input: JsonData
     instructions: Optional[str] = None
     user: Optional[str] = None
     stream: bool = False
@@ -69,9 +77,30 @@ class OpenAIChatCompletionResponse(BaseModel):
 
 
 class OpenAIResponsesOutputText(BaseModel):
+    """Responses API 输出中的文本内容块。"""
+
     type: str = "output_text"
     text: str
-    annotations: List[Dict[str, Any]] = Field(default_factory=list)
+    annotations: List["OpenAIResponseAnnotation"] = Field(default_factory=list)
+
+
+class OpenAIResponseAnnotation(BaseModel):
+    """Responses API 文本内容关联的引用或文件注解。"""
+
+    type: str
+    index: Optional[int] = None
+    start_index: Optional[int] = None
+    end_index: Optional[int] = None
+    url: Optional[str] = None
+    title: Optional[str] = None
+    file_id: Optional[str] = None
+    filename: Optional[str] = None
+
+
+class OpenAIIncompleteDetails(BaseModel):
+    """Responses API 未完整结束时的原因。"""
+
+    reason: str
 
 
 class OpenAIResponsesOutputMessage(BaseModel):
@@ -83,14 +112,16 @@ class OpenAIResponsesOutputMessage(BaseModel):
 
 
 class OpenAIResponsesResponse(BaseModel):
+    """OpenAI Responses API 的非流式成功响应。"""
+
     id: str
     object: str = "response"
     created_at: int
     status: str = "completed"
     model: str
     output: List[OpenAIResponsesOutputMessage] = Field(default_factory=list)
-    error: Optional[Any] = None
-    incomplete_details: Optional[Any] = None
+    error: Optional["OpenAIErrorDetail"] = None
+    incomplete_details: Optional[OpenAIIncompleteDetails] = None
     usage: OpenAIUsage
 
 
@@ -105,20 +136,24 @@ class OpenAIErrorResponse(BaseModel):
     error: OpenAIErrorDetail
 
 
-OpenAIChatContentPart = Dict[str, Any]
+OpenAIChatContentPart = Dict[str, JsonData]
 
 
 class AnthropicMessage(BaseModel):
+    """Anthropic Messages 请求中的一条消息。"""
+
     role: str
-    content: Any
+    content: JsonData
 
     model_config = ConfigDict(extra="allow")
 
 
 class AnthropicMessagesRequest(BaseModel):
+    """Anthropic Messages 兼容请求。"""
+
     model: Optional[str] = None
     messages: List[AnthropicMessage]
-    system: Optional[Any] = None
+    system: Optional[JsonData] = None
     max_tokens: Optional[int] = 1024
     stream: bool = False