{
  "openapi": "3.0.3",
  "info": {
    "title": "鸡出没API · 常用端点参考",
    "version": "2026-10-11",
    "description": "常用接口子集，不替代完整 AI 参考和动态模型目录。文档未发起收费生成或逐客户端实测。模型支持能力、限制、费用与历史验收范围见 ai-reference.md / video-contract.json。",
    "x-documentation": "https://www.xcmapi.com/docs/QuickStart.html"
  },
  "servers": [
    {
      "url": "https://xcmapi.org",
      "description": "API Origin，不含 /v1；下面路径已含版本前缀。"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "用户自己的 API Key"
      },
      "geminiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "x-goog-api-key"
      }
    }
  },
  "paths": {
    "/v1/models": {
      "get": {
        "operationId": "listModels",
        "summary": "读取当前 Key 可见模型目录",
        "description": "不是价格 API，也不证明端点或模态已经通过测试。",
        "responses": {
          "200": {
            "description": "请求成功；字段依具体端点和模型而异。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "403": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "404": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "422": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "429": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "500": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/v1/chat/completions": {
      "post": {
        "operationId": "chatCompletions",
        "summary": "聊天与视觉理解",
        "description": "messages 中可用文字或图片内容块；流式为 SSE，解析 choices[].delta，不能套用 Responses 事件。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "model",
                  "messages"
                ],
                "properties": {
                  "model": {
                    "type": "string",
                    "description": "从当前 Key 的目录选择完整 ID；目录存在不保证模态、参数或端点能力。"
                  },
                  "messages": {
                    "type": "array",
                    "items": {
                      "oneOf": [
                        {
                          "type": "object",
                          "required": [
                            "role",
                            "content"
                          ],
                          "properties": {
                            "role": {
                              "type": "string",
                              "enum": [
                                "system",
                                "developer",
                                "user"
                              ]
                            },
                            "content": {
                              "oneOf": [
                                {
                                  "type": "string"
                                },
                                {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "additionalProperties": true
                                  }
                                }
                              ]
                            }
                          },
                          "additionalProperties": true
                        },
                        {
                          "type": "object",
                          "required": [
                            "role"
                          ],
                          "properties": {
                            "role": {
                              "type": "string",
                              "enum": [
                                "assistant"
                              ]
                            },
                            "content": {
                              "anyOf": [
                                {
                                  "type": "string",
                                  "nullable": true
                                },
                                {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "additionalProperties": true
                                  }
                                }
                              ]
                            },
                            "tool_calls": {
                              "type": "array",
                              "minItems": 1,
                              "items": {
                                "type": "object",
                                "additionalProperties": true
                              }
                            }
                          },
                          "additionalProperties": true,
                          "anyOf": [
                            {
                              "required": [
                                "content"
                              ]
                            },
                            {
                              "required": [
                                "tool_calls"
                              ]
                            }
                          ]
                        },
                        {
                          "type": "object",
                          "required": [
                            "role",
                            "content",
                            "tool_call_id"
                          ],
                          "properties": {
                            "role": {
                              "type": "string",
                              "enum": [
                                "tool"
                              ]
                            },
                            "content": {
                              "oneOf": [
                                {
                                  "type": "string"
                                },
                                {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "additionalProperties": true
                                  }
                                }
                              ]
                            },
                            "tool_call_id": {
                              "type": "string"
                            }
                          },
                          "additionalProperties": true
                        }
                      ]
                    }
                  },
                  "stream": {
                    "type": "boolean"
                  },
                  "max_tokens": {
                    "type": "integer"
                  },
                  "temperature": {
                    "type": "number"
                  }
                },
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "请求成功；字段依具体端点和模型而异。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                },
                "example": "data: {\"choices\":[{\"delta\":{\"content\":\"OK\"}}]}\n\ndata: [DONE]\n\n"
              }
            }
          },
          "400": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "403": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "404": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "422": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "429": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "500": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/v1/responses": {
      "post": {
        "operationId": "responses",
        "summary": "Responses API",
        "description": "input 和 output 结构；流式事件与聊天不同。模型需支持该端点。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "model",
                  "input"
                ],
                "properties": {
                  "model": {
                    "type": "string",
                    "description": "从当前 Key 的目录选择完整 ID；目录存在不保证模态、参数或端点能力。"
                  },
                  "input": {
                    "oneOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      }
                    ]
                  },
                  "stream": {
                    "type": "boolean"
                  }
                },
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "请求成功；字段依具体端点和模型而异。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "description": "按 Responses 事件类型处理。"
                }
              }
            }
          },
          "400": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "403": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "404": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "422": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "429": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "500": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/v1/messages": {
      "post": {
        "operationId": "anthropicMessages",
        "summary": "Anthropic Messages 原生协议",
        "description": "需当前 Key 与渠道支持；与 OpenAI 消息格式不同。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "model",
                  "messages",
                  "max_tokens"
                ],
                "properties": {
                  "model": {
                    "type": "string",
                    "description": "从当前 Key 的目录选择完整 ID；目录存在不保证模态、参数或端点能力。"
                  },
                  "messages": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "required": [
                        "role",
                        "content"
                      ],
                      "properties": {
                        "role": {
                          "type": "string",
                          "enum": [
                            "user",
                            "assistant"
                          ]
                        },
                        "content": {
                          "oneOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "additionalProperties": true
                              }
                            }
                          ]
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "max_tokens": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "stream": {
                    "type": "boolean"
                  },
                  "system": {
                    "oneOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      }
                    ]
                  }
                },
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "请求成功；字段依具体端点和模型而异。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "403": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "404": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "422": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "429": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "500": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "anthropic-version",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "default": "2023-06-01"
            }
          }
        ]
      }
    },
    "/v1beta/models/{model}:generateContent": {
      "post": {
        "operationId": "geminiGenerateContent",
        "summary": "Gemini 原生内容生成",
        "description": "使用 x-goog-api-key，不套用 OpenAI Chat 请求体。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "contents"
                ],
                "properties": {
                  "contents": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "additionalProperties": true
                    }
                  },
                  "generationConfig": {
                    "type": "object",
                    "additionalProperties": true
                  }
                },
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "请求成功；字段依具体端点和模型而异。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "403": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "404": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "422": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "429": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "500": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        },
        "security": [
          {
            "geminiKey": []
          }
        ],
        "parameters": [
          {
            "name": "model",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "description": "从当前 Key 的目录选择完整 ID；目录存在不保证模态、参数或端点能力。"
            }
          }
        ]
      }
    },
    "/v1/images/generations": {
      "post": {
        "operationId": "generateImage",
        "summary": "根据提示词生成图片",
        "description": "只支持指定图像模型。size/n 等值由型号决定。返回 data[].url 或 data[].b64_json。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "model",
                  "prompt"
                ],
                "properties": {
                  "model": {
                    "type": "string",
                    "description": "从当前 Key 的目录选择完整 ID；目录存在不保证模态、参数或端点能力。"
                  },
                  "prompt": {
                    "type": "string"
                  },
                  "size": {
                    "type": "string"
                  },
                  "n": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "response_format": {
                    "type": "string",
                    "enum": [
                      "url",
                      "b64_json"
                    ]
                  }
                },
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "请求成功；字段依具体端点和模型而异。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "403": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "404": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "422": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "429": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "500": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/v1/images/edits": {
      "post": {
        "operationId": "editImage",
        "summary": "上传图片并编辑",
        "description": "multipart 文件上传。字段与多图上限受模型约束；不要手动设置 boundary。",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "model",
                  "prompt",
                  "image[]"
                ],
                "properties": {
                  "model": {
                    "type": "string",
                    "description": "从当前 Key 的目录选择完整 ID；目录存在不保证模态、参数或端点能力。"
                  },
                  "prompt": {
                    "type": "string"
                  },
                  "image[]": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "binary"
                    }
                  },
                  "size": {
                    "type": "string"
                  },
                  "n": {
                    "type": "integer",
                    "minimum": 1
                  }
                },
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "请求成功；字段依具体端点和模型而异。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "403": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "404": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "422": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "429": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "500": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/v1/videos": {
      "post": {
        "operationId": "createVideo",
        "summary": "创建一个视频任务",
        "description": "仅创建一次。保存返回的任务 ID。POST 超时先核查，不自动重发；不声明 Idempotency-Key 可用。参数按 H3/具体混合型号区分。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "required": [
                      "model",
                      "prompt"
                    ],
                    "properties": {
                      "model": {
                        "type": "string",
                        "enum": [
                          "h3"
                        ]
                      },
                      "prompt": {
                        "type": "string"
                      },
                      "duration": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 15,
                        "description": "官方计费上限 15 秒；实际时长是否允许以该模型上游约束为准。"
                      },
                      "aspect_ratio": {
                        "type": "string",
                        "description": "H3 使用该字段而非 ratio；具体值以模型约束为准。"
                      },
                      "resolution": {
                        "type": "string",
                        "description": "计价档不等于经过出片验证；见现行 H3 章节。"
                      }
                    },
                    "additionalProperties": true
                  },
                  {
                    "type": "object",
                    "required": [
                      "model",
                      "prompt"
                    ],
                    "properties": {
                      "model": {
                        "type": "string",
                        "not": {
                          "enum": [
                            "h3"
                          ]
                        },
                        "description": "非 H3 的完整模型 ID；模型级约束见 video-contract.json。"
                      },
                      "prompt": {
                        "type": "string"
                      },
                      "duration": {
                        "type": "number",
                        "description": "必须匹配当前型号允许范围与计费限制。"
                      },
                      "ratio": {
                        "type": "string"
                      },
                      "resolution": {
                        "type": "string"
                      }
                    },
                    "additionalProperties": true
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "请求成功；字段依具体端点和模型而异。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "201": {
            "description": "任务已创建。ID 可能位于顶层或 data 中。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "202": {
            "description": "任务已受理，继续查询。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "403": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "404": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "422": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "429": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "500": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/v1/videos/generations": {
      "post": {
        "operationId": "createVideoAlias",
        "summary": "创建一个视频任务",
        "description": "仅创建一次。保存返回的任务 ID。POST 超时先核查，不自动重发；不声明 Idempotency-Key 可用。参数按 H3/具体混合型号区分。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "required": [
                      "model",
                      "prompt"
                    ],
                    "properties": {
                      "model": {
                        "type": "string",
                        "enum": [
                          "h3"
                        ]
                      },
                      "prompt": {
                        "type": "string"
                      },
                      "duration": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 15,
                        "description": "官方计费上限 15 秒；实际时长是否允许以该模型上游约束为准。"
                      },
                      "aspect_ratio": {
                        "type": "string",
                        "description": "H3 使用该字段而非 ratio；具体值以模型约束为准。"
                      },
                      "resolution": {
                        "type": "string",
                        "description": "计价档不等于经过出片验证；见现行 H3 章节。"
                      }
                    },
                    "additionalProperties": true
                  },
                  {
                    "type": "object",
                    "required": [
                      "model",
                      "prompt"
                    ],
                    "properties": {
                      "model": {
                        "type": "string",
                        "not": {
                          "enum": [
                            "h3"
                          ]
                        },
                        "description": "非 H3 的完整模型 ID；模型级约束见 video-contract.json。"
                      },
                      "prompt": {
                        "type": "string"
                      },
                      "duration": {
                        "type": "number",
                        "description": "必须匹配当前型号允许范围与计费限制。"
                      },
                      "ratio": {
                        "type": "string"
                      },
                      "resolution": {
                        "type": "string"
                      }
                    },
                    "additionalProperties": true
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "请求成功；字段依具体端点和模型而异。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "201": {
            "description": "任务已创建。ID 可能位于顶层或 data 中。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "202": {
            "description": "任务已受理，继续查询。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "403": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "404": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "422": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "429": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "500": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/v1/videos/{task_id}": {
      "get": {
        "operationId": "getVideoTask",
        "summary": "查询同一个视频任务",
        "description": "每 3–5 秒查询，设置总次数和时间上限。成功：done/completed/succeeded/success；失败：failed/error/expired/cancelled/canceled；未知状态停止自动轮询并保留 ID。",
        "parameters": [
          {
            "name": "task_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "创建时返回的 id/task_id/request_id。始终使用同一 Key 查询。"
          }
        ],
        "responses": {
          "200": {
            "description": "请求成功；字段依具体端点和模型而异。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "403": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "404": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "422": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "429": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "500": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/v1/videos/{task_id}/content": {
      "get": {
        "operationId": "downloadVideo",
        "summary": "下载已完成的视频",
        "description": "若返回外部地址，后续下载不要携带本站 Authorization；禁止 location-trusted。",
        "parameters": [
          {
            "name": "task_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "创建时返回的 id/task_id/request_id。始终使用同一 Key 查询。"
          }
        ],
        "responses": {
          "200": {
            "description": "视频内容或依渠道给出的下载结果；检查 Content-Type。",
            "content": {
              "video/mp4": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "302": {
            "description": "下载跳转；后续请求不得向外部域名转发 API Key。",
            "headers": {
              "Location": {
                "schema": {
                  "type": "string",
                  "format": "uri"
                }
              }
            }
          },
          "307": {
            "description": "临时跳转，遵守相同凭据隔离要求。"
          },
          "401": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "404": {
            "description": "错误响应；读取状态和 error/message。视频创建失败或超时不可自动重建。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    }
  }
}