feat(api): 统一官方兼容接口响应协议

兼容接口现在以入口协议作为最终响应协议，同协议保留官方 Wire 响应，跨协议统一转换成功、任务状态与错误结构。

同时修正异步提交状态边界，持久化兼容公开任务标识和官方提交响应，并新增迁移、流式响应及协议契约测试。

验证：go vet ./...；go test ./...；govulncheck ./...；pnpm lint；pnpm test；pnpm build；pnpm audit --audit-level high；pnpm openapi；全部 CI 脚本。

apps/api/docs/swagger.yaml

@@ -395,6 +395,28 @@ definitions:
         example: /static/uploaded/upload-abc123.png
         type: string
     type: object
+  httpapi.GeminiErrorEnvelope:
+    properties:
+      error:
+        $ref: '#/definitions/httpapi.GeminiErrorStatus'
+    type: object
+  httpapi.GeminiErrorStatus:
+    properties:
+      code:
+        example: 400
+        type: integer
+      details:
+        items:
+          additionalProperties: {}
+          type: object
+        type: array
+      message:
+        example: Invalid argument
+        type: string
+      status:
+        example: INVALID_ARGUMENT
+        type: string
+    type: object
   httpapi.HealthResponse:
     properties:
       env:
@@ -572,6 +594,20 @@ definitions:
         example: false
         type: boolean
     type: object
+  httpapi.KlingErrorEnvelope:
+    properties:
+      code:
+        example: 1001
+        type: integer
+      error:
+        example: invalid_parameter
+        type: string
+      message:
+        example: invalid parameter
+        type: string
+      request_id:
+        type: string
+    type: object
   httpapi.ModelCatalogFilterOption:
     properties:
       count:
@@ -764,6 +800,26 @@ definitions:
         example: env
         type: string
     type: object
+  httpapi.OpenAIErrorEnvelope:
+    properties:
+      error:
+        $ref: '#/definitions/httpapi.OpenAIErrorPayload'
+    type: object
+  httpapi.OpenAIErrorPayload:
+    properties:
+      code:
+        example: invalid_parameter
+        type: string
+      message:
+        example: Invalid parameter
+        type: string
+      param:
+        example: model
+        type: string
+      type:
+        example: invalid_request_error
+        type: string
+    type: object
   httpapi.PlatformListResponse:
     properties:
       items:
@@ -1281,6 +1337,49 @@ definitions:
         example: https://example.com/source.mp4
         type: string
     type: object
+  httpapi.VolcesContentsGenerationTaskResponse:
+    properties:
+      content:
+        additionalProperties: {}
+        type: object
+      created_at:
+        type: integer
+      error:
+        additionalProperties: {}
+        type: object
+      id:
+        example: cgt-202607221234
+        type: string
+      model:
+        type: string
+      status:
+        enum:
+        - queued
+        - running
+        - succeeded
+        - failed
+        - cancelled
+        type: string
+      updated_at:
+        type: integer
+      usage:
+        additionalProperties: {}
+        type: object
+    type: object
+  httpapi.VolcesErrorEnvelope:
+    properties:
+      error:
+        $ref: '#/definitions/httpapi.VolcesErrorPayload'
+    type: object
+  httpapi.VolcesErrorPayload:
+    properties:
+      code:
+        example: invalid_parameter
+        type: string
+      message:
+        example: model is required
+        type: string
+    type: object
   httpapi.WalletAdjustmentResponse:
     properties:
       account:
@@ -2306,6 +2405,20 @@ definitions:
         type: array
       cancellable:
         type: boolean
+      compatibilityProtocol:
+        type: string
+      compatibilityPublicId:
+        type: string
+      compatibilitySourceProtocol:
+        type: string
+      compatibilitySubmitBody:
+        additionalProperties: {}
+        type: object
+      compatibilitySubmitHeaders:
+        additionalProperties: {}
+        type: object
+      compatibilitySubmitHttpStatus:
+        type: integer
       conversationId:
         type: string
       createdAt:
@@ -6985,31 +7098,31 @@ paths:
         "400":
           description: Bad Request
           schema:
-            $ref: '#/definitions/httpapi.ErrorEnvelope'
+            $ref: '#/definitions/httpapi.OpenAIErrorEnvelope'
         "401":
           description: Unauthorized
           schema:
-            $ref: '#/definitions/httpapi.ErrorEnvelope'
+            $ref: '#/definitions/httpapi.OpenAIErrorEnvelope'
         "402":
           description: Payment Required
           schema:
-            $ref: '#/definitions/httpapi.ErrorEnvelope'
+            $ref: '#/definitions/httpapi.OpenAIErrorEnvelope'
         "403":
           description: Forbidden
           schema:
-            $ref: '#/definitions/httpapi.ErrorEnvelope'
+            $ref: '#/definitions/httpapi.OpenAIErrorEnvelope'
         "404":
           description: Not Found
           schema:
-            $ref: '#/definitions/httpapi.ErrorEnvelope'
+            $ref: '#/definitions/httpapi.OpenAIErrorEnvelope'
         "429":
           description: Too Many Requests
           schema:
-            $ref: '#/definitions/httpapi.ErrorEnvelope'
+            $ref: '#/definitions/httpapi.OpenAIErrorEnvelope'
         "502":
           description: Bad Gateway
           schema:
-            $ref: '#/definitions/httpapi.ErrorEnvelope'
+            $ref: '#/definitions/httpapi.OpenAIErrorEnvelope'
       security:
       - BearerAuth: []
       summary: 创建 Chat Completions
@@ -7025,6 +7138,14 @@ paths:
           schema:
             additionalProperties: true
             type: object
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/httpapi.VolcesErrorEnvelope'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/httpapi.VolcesErrorEnvelope'
       security:
       - BearerAuth: []
       summary: 列出火山内容生成任务
@@ -7041,8 +7162,23 @@ paths:
         "200":
           description: OK
           schema:
-            additionalProperties: true
-            type: object
+            $ref: '#/definitions/httpapi.VolcesContentsGenerationTaskResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/httpapi.VolcesErrorEnvelope'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/httpapi.VolcesErrorEnvelope'
+        "429":
+          description: Too Many Requests
+          schema:
+            $ref: '#/definitions/httpapi.VolcesErrorEnvelope'
+        "502":
+          description: Bad Gateway
+          schema:
+            $ref: '#/definitions/httpapi.VolcesErrorEnvelope'
       security:
       - BearerAuth: []
       summary: 创建火山内容生成任务
@@ -7063,8 +7199,11 @@ paths:
         "200":
           description: OK
           schema:
-            additionalProperties: true
-            type: object
+            $ref: '#/definitions/httpapi.VolcesContentsGenerationTaskResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/httpapi.VolcesErrorEnvelope'
       security:
       - BearerAuth: []
       summary: 取消火山内容生成任务
@@ -7083,8 +7222,11 @@ paths:
         "200":
           description: OK
           schema:
-            additionalProperties: true
-            type: object
+            $ref: '#/definitions/httpapi.VolcesContentsGenerationTaskResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/httpapi.VolcesErrorEnvelope'
       security:
       - BearerAuth: []
       summary: 查询火山内容生成任务
@@ -7094,17 +7236,8 @@ paths:
     post:
       consumes:
       - application/json
-      description: 统一公开入口按 model 选择平台模型并默认同步返回兼容响应；设置 X-Async=true 时异步创建任务并返回 202。
       parameters:
-      - description: true 时异步创建任务并返回 202
-        in: header
-        name: X-Async
-        type: boolean
-      - description: 可选请求幂等键；同一用户范围内唯一
-        in: header
-        name: Idempotency-Key
-        type: string
-      - description: AI 任务请求，字段随任务类型变化
+      - description: OpenAI Embeddings 请求
         in: body
         name: input
         required: true
@@ -7117,43 +7250,27 @@ paths:
           description: OK
           schema:
             $ref: '#/definitions/httpapi.CompatibleResponse'
-        "202":
-          description: Accepted
-          schema:
-            $ref: '#/definitions/httpapi.TaskAcceptedResponse'
         "400":
           description: Bad Request
           schema:
-            $ref: '#/definitions/httpapi.ErrorEnvelope'
+            $ref: '#/definitions/httpapi.OpenAIErrorEnvelope'
         "401":
           description: Unauthorized
           schema:
-            $ref: '#/definitions/httpapi.ErrorEnvelope'
-        "402":
-          description: Payment Required
-          schema:
-            $ref: '#/definitions/httpapi.ErrorEnvelope'
-        "403":
-          description: Forbidden
-          schema:
-            $ref: '#/definitions/httpapi.ErrorEnvelope'
-        "404":
-          description: Not Found
-          schema:
-            $ref: '#/definitions/httpapi.ErrorEnvelope'
+            $ref: '#/definitions/httpapi.OpenAIErrorEnvelope'
         "429":
           description: Too Many Requests
           schema:
-            $ref: '#/definitions/httpapi.ErrorEnvelope'
+            $ref: '#/definitions/httpapi.OpenAIErrorEnvelope'
         "502":
           description: Bad Gateway
           schema:
-            $ref: '#/definitions/httpapi.ErrorEnvelope'
+            $ref: '#/definitions/httpapi.OpenAIErrorEnvelope'
       security:
       - BearerAuth: []
-      summary: 创建或执行 AI 任务
+      summary: 创建 OpenAI Embeddings
       tags:
-      - tasks
+      - embeddings
   /api/v1/files/upload:
     post:
       consumes:
@@ -7283,17 +7400,8 @@ paths:
     post:
       consumes:
       - application/json
-      description: 统一公开入口按 model 选择平台模型并默认同步返回兼容响应；设置 X-Async=true 时异步创建任务并返回 202。
       parameters:
-      - description: true 时异步创建任务并返回 202
-        in: header
-        name: X-Async
-        type: boolean
-      - description: 可选请求幂等键；同一用户范围内唯一
-        in: header
-        name: Idempotency-Key
-        type: string
-      - description: AI 任务请求，字段随任务类型变化
+      - description: OpenAI Images 请求
         in: body
         name: input
         required: true
@@ -7306,58 +7414,33 @@ paths:
           description: OK
           schema:
             $ref: '#/definitions/httpapi.CompatibleResponse'
-        "202":
-          description: Accepted
-          schema:
-            $ref: '#/definitions/httpapi.TaskAcceptedResponse'
         "400":
           description: Bad Request
           schema:
-            $ref: '#/definitions/httpapi.ErrorEnvelope'
+            $ref: '#/definitions/httpapi.OpenAIErrorEnvelope'
         "401":
           description: Unauthorized
           schema:
-            $ref: '#/definitions/httpapi.ErrorEnvelope'
-        "402":
-          description: Payment Required
-          schema:
-            $ref: '#/definitions/httpapi.ErrorEnvelope'
-        "403":
-          description: Forbidden
-          schema:
-            $ref: '#/definitions/httpapi.ErrorEnvelope'
-        "404":
-          description: Not Found
-          schema:
-            $ref: '#/definitions/httpapi.ErrorEnvelope'
+            $ref: '#/definitions/httpapi.OpenAIErrorEnvelope'
         "429":
           description: Too Many Requests
           schema:
-            $ref: '#/definitions/httpapi.ErrorEnvelope'
+            $ref: '#/definitions/httpapi.OpenAIErrorEnvelope'
         "502":
           description: Bad Gateway
           schema:
-            $ref: '#/definitions/httpapi.ErrorEnvelope'
+            $ref: '#/definitions/httpapi.OpenAIErrorEnvelope'
       security:
       - BearerAuth: []
-      summary: 创建或执行 AI 任务
+      summary: 创建或编辑 OpenAI Images
       tags:
-      - tasks
+      - images
   /api/v1/images/generations:
     post:
       consumes:
       - application/json
-      description: 统一公开入口按 model 选择平台模型并默认同步返回兼容响应；设置 X-Async=true 时异步创建任务并返回 202。
       parameters:
-      - description: true 时异步创建任务并返回 202
-        in: header
-        name: X-Async
-        type: boolean
-      - description: 可选请求幂等键；同一用户范围内唯一
-        in: header
-        name: Idempotency-Key
-        type: string
-      - description: AI 任务请求，字段随任务类型变化
+      - description: OpenAI Images 请求
         in: body
         name: input
         required: true
@@ -7370,43 +7453,27 @@ paths:
           description: OK
           schema:
             $ref: '#/definitions/httpapi.CompatibleResponse'
-        "202":
-          description: Accepted
-          schema:
-            $ref: '#/definitions/httpapi.TaskAcceptedResponse'
         "400":
           description: Bad Request
           schema:
-            $ref: '#/definitions/httpapi.ErrorEnvelope'
+            $ref: '#/definitions/httpapi.OpenAIErrorEnvelope'
         "401":
           description: Unauthorized
           schema:
-            $ref: '#/definitions/httpapi.ErrorEnvelope'
-        "402":
-          description: Payment Required
-          schema:
-            $ref: '#/definitions/httpapi.ErrorEnvelope'
-        "403":
-          description: Forbidden
-          schema:
-            $ref: '#/definitions/httpapi.ErrorEnvelope'
-        "404":
-          description: Not Found
-          schema:
-            $ref: '#/definitions/httpapi.ErrorEnvelope'
+            $ref: '#/definitions/httpapi.OpenAIErrorEnvelope'
         "429":
           description: Too Many Requests
           schema:
-            $ref: '#/definitions/httpapi.ErrorEnvelope'
+            $ref: '#/definitions/httpapi.OpenAIErrorEnvelope'
         "502":
           description: Bad Gateway
           schema:
-            $ref: '#/definitions/httpapi.ErrorEnvelope'
+            $ref: '#/definitions/httpapi.OpenAIErrorEnvelope'
       security:
       - BearerAuth: []
-      summary: 创建或执行 AI 任务
+      summary: 创建或编辑 OpenAI Images
       tags:
-      - tasks
+      - images
   /api/v1/images/vectorize:
     post:
       consumes:
@@ -7515,7 +7582,7 @@ paths:
         "401":
           description: Unauthorized
           schema:
-            $ref: '#/definitions/httpapi.ErrorEnvelope'
+            $ref: '#/definitions/httpapi.KlingErrorEnvelope'
       security:
       - BearerAuth: []
       summary: 创建可灵 V1 Omni 视频任务
@@ -7581,7 +7648,7 @@ paths:
         "401":
           description: Unauthorized
           schema:
-            $ref: '#/definitions/httpapi.ErrorEnvelope'
+            $ref: '#/definitions/httpapi.KlingErrorEnvelope'
       security:
       - BearerAuth: []
       summary: 创建可灵 API 2.0 Omni 视频任务
@@ -7728,6 +7795,7 @@ paths:
           type: object
       produces:
       - application/json
+      - text/event-stream
       responses:
         "200":
           description: OK
@@ -7737,19 +7805,67 @@ paths:
         "400":
           description: Bad Request
           schema:
-            $ref: '#/definitions/httpapi.ErrorEnvelope'
+            $ref: '#/definitions/httpapi.GeminiErrorEnvelope'
         "401":
           description: Unauthorized
           schema:
-            $ref: '#/definitions/httpapi.ErrorEnvelope'
+            $ref: '#/definitions/httpapi.GeminiErrorEnvelope'
         "403":
           description: Forbidden
           schema:
-            $ref: '#/definitions/httpapi.ErrorEnvelope'
+            $ref: '#/definitions/httpapi.GeminiErrorEnvelope'
         "502":
           description: Bad Gateway
           schema:
-            $ref: '#/definitions/httpapi.ErrorEnvelope'
+            $ref: '#/definitions/httpapi.GeminiErrorEnvelope'
+      security:
+      - BearerAuth: []
+      summary: Gemini generateContent 兼容接口
+      tags:
+      - gemini-compatible
+  /api/v1/models/{model}:streamGenerateContent:
+    post:
+      consumes:
+      - application/json
+      description: 使用统一 /api/v1 前缀接收 Gemini generateContent 请求；旧 /v1 和 /v1beta 路径保留兼容。
+      parameters:
+      - description: 模型名称
+        in: path
+        name: model
+        required: true
+        type: string
+      - description: Gemini generateContent 请求
+        in: body
+        name: input
+        required: true
+        schema:
+          additionalProperties: true
+          type: object
+      produces:
+      - application/json
+      - text/event-stream
+      responses:
+        "200":
+          description: OK
+          schema:
+            additionalProperties: true
+            type: object
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/httpapi.GeminiErrorEnvelope'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/httpapi.GeminiErrorEnvelope'
+        "403":
+          description: Forbidden
+          schema:
+            $ref: '#/definitions/httpapi.GeminiErrorEnvelope'
+        "502":
+          description: Bad Gateway
+          schema:
+            $ref: '#/definitions/httpapi.GeminiErrorEnvelope'
       security:
       - BearerAuth: []
       summary: Gemini generateContent 兼容接口
@@ -8220,33 +8336,29 @@ paths:
       responses:
         "200":
           description: OK
-          headers:
-            X-Gateway-Task-Id:
-              description: 网关审计任务 ID
-              type: string
           schema:
             $ref: '#/definitions/httpapi.ResponsesCompatibleResponse'
         "400":
           description: invalid_previous_response_id / unsupported_response_tool /
             unsupported_response_parameter
           schema:
-            $ref: '#/definitions/httpapi.ErrorEnvelope'
+            $ref: '#/definitions/httpapi.OpenAIErrorEnvelope'
         "401":
           description: Unauthorized
           schema:
-            $ref: '#/definitions/httpapi.ErrorEnvelope'
+            $ref: '#/definitions/httpapi.OpenAIErrorEnvelope'
         "402":
           description: Payment Required
           schema:
-            $ref: '#/definitions/httpapi.ErrorEnvelope'
+            $ref: '#/definitions/httpapi.OpenAIErrorEnvelope'
         "403":
           description: Forbidden
           schema:
-            $ref: '#/definitions/httpapi.ErrorEnvelope'
+            $ref: '#/definitions/httpapi.OpenAIErrorEnvelope'
         "503":
           description: response_chain_unavailable
           schema:
-            $ref: '#/definitions/httpapi.ErrorEnvelope'
+            $ref: '#/definitions/httpapi.OpenAIErrorEnvelope'
       security:
       - BearerAuth: []
       summary: 创建 OpenAI Responses