openapi: 3.1.0
info:
  title: 短视频解析开放 API
  version: 1.0.0
  description: |
    抖音单条 / 图集 / Live 实况 / 主页批量，以及 26 平台通用解析。
    **按成功计费**：作品已删除、链接不支持、上游失败、限流拒绝一律不计费。

    ## 鉴权
    所有 `/v1/*` 接口需带 Key：`Authorization: Bearer vt_live_xxx` 或 `X-API-Key: vt_live_xxx`。

    ## 幂等
    同一 Key 携带相同 `request_id`，24 小时内只扣一次费。
  contact:
    name: 技术支持
    url: https://console.java68.cn
servers:
  - url: https://jxapi.java68.cn
    description: 生产
  - url: http://127.0.0.1:18001
    description: 本地开发

tags:
  - name: 解析
  - name: 账户
  - name: 公共

components:
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: vt_live_xxx

  schemas:
    Envelope:
      type: object
      required: [code, msg]
      properties:
        code:
          type: integer
          description: 0 成功；非 0 见错误码
        msg:
          type: string
        request_id:
          type: [string, 'null']
        cost:
          type: integer
          description: 本次计费次数，失败恒为 0
        data:
          type: object

    ParseResult:
      type: object
      properties:
        type:
          type: string
          enum: [video, photo]
        title: { type: string }
        author: { type: string }
        author_sec_uid: { type: string }
        cover: { type: string }
        music: { type: string }
        video_url:
          type: [string, 'null']
          description: 视频直链。下载必须带 Referer: https://www.douyin.com/
        images:
          type: array
          items: { type: string }
        live_videos:
          type: array
          items: { type: string }

paths:
  /v1/parse:
    post:
      tags: [解析]
      summary: 解析单条（视频 / 图集 / Live）
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [url]
              properties:
                url:
                  type: string
                  description: 分享链接、整段分享文案或 aweme_id
                  maxLength: 2048
                author_sec_uid:
                  type: string
                  description: 可选，上次结果里的作者 sec_uid，可提高被风控时的命中率
                request_id:
                  type: string
                  description: 建议传，幂等键（24h）
      responses:
        '200':
          description: 业务结果（成功或业务失败，看 code）
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Envelope'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/ParseResult'
        '401':
          description: Key 无效 / 未带 Key（code=1001）
        '402':
          description: 额度不足（code=1002）
        '429':
          description: 限流（code=1003），按 Retry-After 退避

  /v1/douyin/home:
    post:
      tags: [解析]
      summary: 抖音作者主页批量（同步，最长 45 秒）
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [sec_uid]
              properties:
                sec_uid: { type: string, description: 作者 sec_uid }
                cursor: { type: integer, minimum: 0, maximum: 5000, default: 0 }
                count: { type: integer, minimum: 1, maximum: 50, default: 20 }
      responses:
        '200':
          description: 结果；按成功返回条数计费，单页最低 10 条
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'

  /v1/usage:
    get:
      tags: [账户]
      summary: 本 Key 今日用量
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: 今日成功/已删除/失败/计费次数
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'

  /v1/plans:
    get:
      tags: [公共]
      summary: 在售套餐
      responses:
        '200':
          description: 套餐列表
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'

  /v1/health:
    get:
      tags: [公共]
      summary: 健康检查
      responses:
        '200':
          description: 服务状态
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'

x-error-codes:
  '0': 成功（计费）
  '1001': Key 无效/停用（不计费）
  '1002': 额度不足（不计费）
  '1003': 限流，按 Retry-After 退避（不计费）
  '1004': IP 不在白名单（不计费）
  '1006': 资源冲突（订单状态不允许该操作，不计费）
  '1007': 参数不合法（不计费）
  '1008': 没有权限（角色不足，不计费）
  '2001': 链接无法识别/平台不支持（不计费）
  '2002': 作品不存在或已删除（不计费，勿重试）
  '2003': 私密账号/需登录态（不计费）
  '3001': 上游暂时失败，可退避重试（不计费）
  '3002': 服务维护中（不计费）
  '5000': 内部错误（不计费，带 request_id 联系客服）
