{
  "openapi": "3.1.0",
  "info": {
    "title": "H3 Video API",
    "version": "1.0.0",
    "description": "客户密钥由H3控制台管理员创建。每个密钥只能访问自身任务；网页管理员可查看全部。HTTP响应默认no-store。时间戳为Unix秒。每密钥120请求/分钟，最多10个新提交/分钟；工作区最多20个未完成任务。通过 /mcp 也可使用同一业务功能。"
  },
  "servers": [
    {
      "url": "https://h3.vectorepoch.com"
    }
  ],
  "security": [
    {
      "ApiKey": []
    }
  ],
  "paths": {
    "/api/v1/jobs": {
      "post": {
        "operationId": "createVideo",
        "summary": "创建自己的视频任务",
        "description": "需要 generate 密钥。对同一逻辑任务重试必须复用 Idempotency-Key 和参数。重复返回相同 job；参数冲突409。提交连接结果不确定时返回 uncertain，不会自动重复生成。",
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{16,80}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateVideo"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobResponse"
                }
              }
            }
          },
          "default": {
            "description": "请求失败；error 为可读说明，code 为稳定错误代码。429 附 Retry-After 秒数。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "listJobs",
        "summary": "分页列出本密钥自己的任务",
        "parameters": [
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{32}$"
            },
            "description": "上次响应的 next_cursor。"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobList"
                }
              }
            }
          },
          "default": {
            "description": "请求失败；error 为可读说明，code 为稳定错误代码。429 附 Retry-After 秒数。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/jobs/{job_id}": {
      "get": {
        "operationId": "getJob",
        "summary": "查询自己的任务状态与阶段进度",
        "parameters": [
          {
            "in": "path",
            "name": "job_id",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{32}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobResponse"
                }
              }
            }
          },
          "default": {
            "description": "请求失败；error 为可读说明，code 为稳定错误代码。429 附 Retry-After 秒数。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/jobs/{job_id}/video": {
      "get": {
        "operationId": "downloadVideo",
        "summary": "读取自己的视频（仍需同一Bearer密钥）",
        "parameters": [
          {
            "in": "path",
            "name": "job_id",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{32}$"
            }
          },
          {
            "in": "header",
            "name": "Range",
            "schema": {
              "type": "string"
            },
            "description": "单一字节范围，例如 bytes=0-1023 或 bytes=-1024。"
          },
          {
            "in": "query",
            "name": "download",
            "schema": {
              "type": "string",
              "enum": [
                "0",
                "1"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "MP4 成片",
            "content": {
              "video/mp4": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "206": {
            "description": "MP4 部分内容；返回 Content-Range 和 Accept-Ranges。",
            "content": {
              "video/mp4": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "default": {
            "description": "请求失败；error 为可读说明，code 为稳定错误代码。429 附 Retry-After 秒数。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/nodes": {
      "get": {
        "operationId": "listNodes",
        "summary": "节点在线状态、队列数量和负载",
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Nodes"
                }
              }
            }
          },
          "default": {
            "description": "请求失败；error 为可读说明，code 为稳定错误代码。429 附 Retry-After 秒数。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/capabilities": {
      "get": {
        "operationId": "getCapabilities",
        "summary": "生成选项和限制",
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Capabilities"
                }
              }
            }
          },
          "default": {
            "description": "请求失败；error 为可读说明，code 为稳定错误代码。429 附 Retry-After 秒数。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/openapi.json": {
      "get": {
        "operationId": "getOpenAPI",
        "summary": "公开接口描述",
        "security": [],
        "responses": {
          "200": {
            "description": "此 OpenAPI 文档",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "控制台创建的 h3_ 开头密钥；不得放入URL。read只能读取本密钥自己的任务；generate包含读取及生成权限。"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error",
          "code"
        ],
        "properties": {
          "error": {
            "type": "string"
          },
          "code": {
            "type": "string"
          }
        }
      },
      "CreateVideo": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "prompt"
        ],
        "properties": {
          "prompt": {
            "type": "string",
            "minLength": 1,
            "maxLength": 4000
          },
          "seconds": {
            "type": "number",
            "enum": [
              1.6,
              5,
              10
            ],
            "default": 5
          },
          "resolution": {
            "type": "string",
            "enum": [
              "480p",
              "768p"
            ],
            "default": "480p"
          },
          "node": {
            "type": "string",
            "enum": [
              "auto",
              "node102",
              "node124"
            ],
            "default": "auto"
          },
          "image_base64": {
            "type": "string",
            "minLength": 1,
            "maxLength": 16777216,
            "description": "可选 PNG/JPEG/WebP 原图的纯 Base64。原图最多12MiB，不接受URL、data:前缀或换行。"
          },
          "first_frame": {
            "type": "boolean",
            "default": false,
            "description": "为 true 必须同时提供 image_base64。"
          }
        }
      },
      "Job": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[a-f0-9]{32}$"
          },
          "node_id": {
            "type": "string"
          },
          "node_name": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "submitting",
              "queued",
              "running",
              "done",
              "error",
              "uncertain",
              "expired"
            ]
          },
          "created_at": {
            "type": "number"
          },
          "updated_at": {
            "type": "number"
          },
          "prompt": {
            "type": "string"
          },
          "width": {
            "type": "integer"
          },
          "height": {
            "type": "integer"
          },
          "seconds": {
            "type": "number"
          },
          "progress": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 0,
            "maximum": 100,
            "description": "当前阶段的百分比；null 表示该阶段无可用进度，不能当作整体百分比。"
          },
          "stage": {
            "type": [
              "string",
              "null"
            ]
          },
          "error": {
            "type": [
              "string",
              "null"
            ]
          },
          "elapsed": {
            "type": [
              "number",
              "null"
            ]
          },
          "video_url": {
            "type": [
              "string",
              "null"
            ],
            "description": "仅 done 返回 HTTPS 地址，下载必须使用创建任务的同一 Bearer 密钥。"
          }
        },
        "required": [
          "id",
          "node_id",
          "status",
          "created_at",
          "updated_at",
          "prompt",
          "width",
          "height",
          "seconds",
          "video_url"
        ]
      },
      "JobResponse": {
        "type": "object",
        "required": [
          "job"
        ],
        "properties": {
          "job": {
            "$ref": "#/components/schemas/Job"
          }
        }
      },
      "JobList": {
        "type": "object",
        "required": [
          "jobs",
          "next_cursor"
        ],
        "properties": {
          "jobs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Job"
            }
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "Nodes": {
        "type": "object",
        "required": [
          "nodes",
          "server_time"
        ],
        "properties": {
          "server_time": {
            "type": "number"
          },
          "nodes": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "online": {
                  "type": "boolean"
                },
                "queued": {
                  "type": "integer"
                },
                "running": {
                  "type": "integer"
                },
                "checked_at": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "metrics": {
                  "type": "object",
                  "description": "CPU百分比、内存GiB、GPU百分比、温度、功率和1分钟负载。"
                }
              }
            }
          }
        }
      },
      "Capabilities": {
        "type": "object",
        "properties": {
          "model": {
            "type": "string"
          },
          "durations": {
            "type": "array",
            "items": {
              "type": "number"
            }
          },
          "resolutions": {
            "type": "object"
          },
          "image_formats": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "image_max_bytes": {
            "type": "integer"
          },
          "prompt_max_length": {
            "type": "integer"
          },
          "video_requires_authentication": {
            "type": "boolean"
          },
          "per_key_requests_per_minute": {
            "type": "integer"
          },
          "per_key_new_submissions_per_minute": {
            "type": "integer"
          },
          "workspace_max_unfinished_jobs": {
            "type": "integer"
          },
          "authentication": {
            "type": "string"
          },
          "progress_unit": {
            "type": "string"
          },
          "idempotency_required": {
            "type": "boolean"
          }
        }
      }
    }
  }
}