{
  "openapi": "3.1.0",
  "info": {
    "version": "2026.10.31",
    "title": "云服洞察 API",
    "description": "独立的云服洞察公开 API，用于授权明文会话导入、录音导入、转写、说话人确认、质检和人工复核；控制台专用洞察接口不在此文档中。"
  },
  "paths": {
    "/v1/operations/insights.audio.read": {
      "get": {
        "operationId": "insights.audio.read",
        "summary": "读取录音导入任务",
        "description": "私有录音上传、异步转写、角色确认、质检及人工复核；请先阅读录音导入指南。\n\n响应示例仅说明结构，不代表已成功识别或质检。API Key必须绑定企业管理员并授权对应操作。\n\n单文件1–100MiB、最长7200秒、单/双声道；企业最多300个未清理任务、总声明容量2GiB；批量清单最多100项；ZIP必须平铺，解压最多100条且总量512MiB，超限、嵌套路径、重复文件名或路径穿越明确失败。\n\n清单子项支持create字段，覆盖顶层默认值；requestId省略时生成batchId-序号。清单创建可能部分成功，失败后保持原清单重放，不是全有或全无事务。\n\nZIP模式省略manifest或传空数组，并传archive:{filename,bytes}及source/startedAt；上传archiveJob的ZIP字节并complete，随后逐条跟踪jobs或archiveChildren。archive.manifest只是元数据，不代替真实ZIP字节。\n\nuncertain为提交未知；不要自动重提。识别使用语音分钟额度，文本模型质检另计。\n\n所有角色确认且含客户后才能分析；语义模型基于转写，噪音、音量与抢话需回听原音核对。\n\n原音回放为登录态私有接口，不提供公开音频URL。本组未新增异步完成Webhook，使用read/advance接续。\n\n原音默认保留365天，可在控制台设置1–3650天；到期返回410并清理原始字节，转写、质检和复核记录仍保留。本组没有修改保留策略的公开操作。",
        "tags": [
          "insights.audio"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-yunfu-permissions": [
          "reports",
          "service",
          "applications"
        ],
        "x-yunfu-billable": false,
        "parameters": [
          {
            "in": "query",
            "name": "jobId",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "可选；省略返回最近100个任务及可用ASR资源。指定时返回job及已有conversation。"
          }
        ],
        "responses": {
          "200": {
            "description": "按当前操作返回结果；任务状态须继续核对。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "job": {
                    "id": "YOUR_AUDIO_JOB_ID",
                    "status": "transcribed",
                    "roleConfirmed": false
                  },
                  "conversation": {
                    "revision": 1,
                    "messages": [],
                    "runs": []
                  }
                }
              }
            }
          },
          "400": {
            "description": "参数、时间、声道、角色或Base64格式不合法。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "密钥缺失、失效、轮换或调用期间撤销。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "没有可用语音分钟额度；先核对套餐余额。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "企业未开通洞察、非管理员或权限/操作授权不足。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "操作不存在，或任务不存在/不属于当前企业。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "方法与操作不一致；使用Allow响应头中的方法。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "版本、状态、幂等或容量冲突；保留输入并read核对，勿盲目换号重试。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "410": {
            "description": "原音到期或已清理；转写、分析与复核仍保留。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "请求正文、文件或ZIP解压量超过上限；调整上传与分块。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "POST必须使用application/json。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "ASR/文本模型/方案缺失，音频或转写无法校验，或分析超限。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "密钥限流或识别并发已满；按Retry-After退避。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "502": {
            "description": "供应商结果缺失或模型输出无效；先read核对状态与已计费用。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "依赖、存储完整性或服务暂不可用；保存任务编号与输入。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/operations/insights.audio.create": {
      "post": {
        "operationId": "insights.audio.create",
        "summary": "创建录音导入",
        "description": "私有录音上传、异步转写、角色确认、质检及人工复核；请先阅读录音导入指南。\n\n响应示例仅说明结构，不代表已成功识别或质检。API Key必须绑定企业管理员并授权对应操作。\n\n单文件1–100MiB、最长7200秒、单/双声道；企业最多300个未清理任务、总声明容量2GiB；批量清单最多100项；ZIP必须平铺，解压最多100条且总量512MiB，超限、嵌套路径、重复文件名或路径穿越明确失败。\n\n清单子项支持create字段，覆盖顶层默认值；requestId省略时生成batchId-序号。清单创建可能部分成功，失败后保持原清单重放，不是全有或全无事务。\n\nZIP模式省略manifest或传空数组，并传archive:{filename,bytes}及source/startedAt；上传archiveJob的ZIP字节并complete，随后逐条跟踪jobs或archiveChildren。archive.manifest只是元数据，不代替真实ZIP字节。\n\nuncertain为提交未知；不要自动重提。识别使用语音分钟额度，文本模型质检另计。\n\n所有角色确认且含客户后才能分析；语义模型基于转写，噪音、音量与抢话需回听原音核对。\n\n原音回放为登录态私有接口，不提供公开音频URL。本组未新增异步完成Webhook，使用read/advance接续。\n\n原音默认保留365天，可在控制台设置1–3650天；到期返回410并清理原始字节，转写、质检和复核记录仍保留。本组没有修改保留策略的公开操作。",
        "tags": [
          "insights.audio"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-yunfu-permissions": [
          "reports",
          "service",
          "applications"
        ],
        "x-yunfu-billable": false,
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_.:-]{8,100}$"
            },
            "description": "POST必须携带8–100位Idempotency-Key（字母数字、下划线、短横线、点、冒号）；同一次写入重传保持key及正文不变，不同操作/分块使用不同key，轮询advance每次使用新key。网关24小时有界响应重放；未知或过期不会重复执行。"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "requestId",
                  "filename",
                  "bytes",
                  "source",
                  "startedAt",
                  "channels"
                ],
                "properties": {
                  "requestId": {
                    "type": "string",
                    "pattern": "^[A-Za-z0-9_-]{8,100}$"
                  },
                  "filename": {
                    "type": "string",
                    "maxLength": 240
                  },
                  "bytes": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 104857600
                  },
                  "source": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 80
                  },
                  "title": {
                    "type": "string",
                    "maxLength": 200
                  },
                  "startedAt": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "channels": {
                    "type": "integer",
                    "enum": [
                      1,
                      2
                    ]
                  },
                  "asrResourceId": {
                    "type": "string"
                  },
                  "asrModel": {
                    "type": "string",
                    "enum": [
                      "fun-asr",
                      "qwen-audio-3.1-asr-flash-filetrans"
                    ]
                  },
                  "channelMapping": {
                    "type": "object",
                    "required": [
                      "left",
                      "right"
                    ],
                    "properties": {
                      "left": {
                        "type": "string",
                        "enum": [
                          "agent",
                          "customer",
                          "unknown"
                        ]
                      },
                      "right": {
                        "type": "string",
                        "enum": [
                          "agent",
                          "customer",
                          "unknown"
                        ]
                      }
                    }
                  },
                  "batchId": {
                    "type": "string",
                    "pattern": "^[A-Za-z0-9_-]{8,100}$"
                  },
                  "archive": {
                    "type": "object",
                    "required": [
                      "filename",
                      "bytes"
                    ],
                    "properties": {
                      "filename": {
                        "type": "string",
                        "maxLength": 240,
                        "pattern": "\\.[zZ][iI][pP]$"
                      },
                      "bytes": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 104857600
                      }
                    }
                  }
                }
              },
              "example": {
                "requestId": "YOUR_STABLE_REQUEST_ID",
                "filename": "call.wav",
                "bytes": 32044,
                "source": "CRM录音",
                "startedAt": "2026-10-17T09:00:00+08:00",
                "channels": 1,
                "asrResourceId": "YOUR_ASR_RESOURCE_ID",
                "asrModel": "fun-asr"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "按当前操作返回结果；任务状态须继续核对。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "job": {
                    "id": "YOUR_AUDIO_JOB_ID",
                    "status": "uploading"
                  }
                }
              }
            }
          },
          "400": {
            "description": "参数、时间、声道、角色或Base64格式不合法。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "密钥缺失、失效、轮换或调用期间撤销。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "没有可用语音分钟额度；先核对套餐余额。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "企业未开通洞察、非管理员或权限/操作授权不足。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "操作不存在，或任务不存在/不属于当前企业。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "方法与操作不一致；使用Allow响应头中的方法。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "版本、状态、幂等或容量冲突；保留输入并read核对，勿盲目换号重试。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "410": {
            "description": "原音到期或已清理；转写、分析与复核仍保留。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "请求正文、文件或ZIP解压量超过上限；调整上传与分块。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "POST必须使用application/json。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "ASR/文本模型/方案缺失，音频或转写无法校验，或分析超限。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "密钥限流或识别并发已满；按Retry-After退避。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "502": {
            "description": "供应商结果缺失或模型输出无效；先read核对状态与已计费用。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "依赖、存储完整性或服务暂不可用；保存任务编号与输入。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/operations/insights.audio.batch": {
      "post": {
        "operationId": "insights.audio.batch",
        "summary": "创建批量录音导入",
        "description": "私有录音上传、异步转写、角色确认、质检及人工复核；请先阅读录音导入指南。\n\n响应示例仅说明结构，不代表已成功识别或质检。API Key必须绑定企业管理员并授权对应操作。\n\n单文件1–100MiB、最长7200秒、单/双声道；企业最多300个未清理任务、总声明容量2GiB；批量清单最多100项；ZIP必须平铺，解压最多100条且总量512MiB，超限、嵌套路径、重复文件名或路径穿越明确失败。\n\n清单子项支持create字段，覆盖顶层默认值；requestId省略时生成batchId-序号。清单创建可能部分成功，失败后保持原清单重放，不是全有或全无事务。\n\nZIP模式省略manifest或传空数组，并传archive:{filename,bytes}及source/startedAt；上传archiveJob的ZIP字节并complete，随后逐条跟踪jobs或archiveChildren。archive.manifest只是元数据，不代替真实ZIP字节。\n\nuncertain为提交未知；不要自动重提。识别使用语音分钟额度，文本模型质检另计。\n\n所有角色确认且含客户后才能分析；语义模型基于转写，噪音、音量与抢话需回听原音核对。\n\n原音回放为登录态私有接口，不提供公开音频URL。本组未新增异步完成Webhook，使用read/advance接续。\n\n原音默认保留365天，可在控制台设置1–3650天；到期返回410并清理原始字节，转写、质检和复核记录仍保留。本组没有修改保留策略的公开操作。",
        "tags": [
          "insights.audio"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-yunfu-permissions": [
          "reports",
          "service",
          "applications"
        ],
        "x-yunfu-billable": false,
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_.:-]{8,100}$"
            },
            "description": "POST必须携带8–100位Idempotency-Key（字母数字、下划线、短横线、点、冒号）；同一次写入重传保持key及正文不变，不同操作/分块使用不同key，轮询advance每次使用新key。网关24小时有界响应重放；未知或过期不会重复执行。"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "batchId"
                ],
                "properties": {
                  "requestId": {
                    "type": "string",
                    "pattern": "^[A-Za-z0-9_-]{8,100}$"
                  },
                  "filename": {
                    "type": "string",
                    "maxLength": 240
                  },
                  "bytes": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 104857600
                  },
                  "source": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 80
                  },
                  "title": {
                    "type": "string",
                    "maxLength": 200
                  },
                  "startedAt": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "channels": {
                    "type": "integer",
                    "enum": [
                      1,
                      2
                    ]
                  },
                  "asrResourceId": {
                    "type": "string"
                  },
                  "asrModel": {
                    "type": "string",
                    "enum": [
                      "fun-asr",
                      "qwen-audio-3.1-asr-flash-filetrans"
                    ]
                  },
                  "channelMapping": {
                    "type": "object",
                    "required": [
                      "left",
                      "right"
                    ],
                    "properties": {
                      "left": {
                        "type": "string",
                        "enum": [
                          "agent",
                          "customer",
                          "unknown"
                        ]
                      },
                      "right": {
                        "type": "string",
                        "enum": [
                          "agent",
                          "customer",
                          "unknown"
                        ]
                      }
                    }
                  },
                  "batchId": {
                    "type": "string",
                    "pattern": "^[A-Za-z0-9_-]{8,100}$"
                  },
                  "archive": {
                    "type": "object",
                    "required": [
                      "filename",
                      "bytes"
                    ],
                    "properties": {
                      "filename": {
                        "type": "string",
                        "maxLength": 240,
                        "pattern": "\\.[zZ][iI][pP]$"
                      },
                      "bytes": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 104857600
                      }
                    }
                  },
                  "manifest": {
                    "type": "array",
                    "maxItems": 100,
                    "items": {
                      "type": "object",
                      "required": [
                        "filename",
                        "bytes"
                      ],
                      "properties": {
                        "requestId": {
                          "type": "string",
                          "pattern": "^[A-Za-z0-9_-]{8,100}$"
                        },
                        "filename": {
                          "type": "string",
                          "maxLength": 240
                        },
                        "bytes": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 104857600
                        },
                        "source": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 80
                        },
                        "title": {
                          "type": "string",
                          "maxLength": 200
                        },
                        "startedAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "channels": {
                          "type": "integer",
                          "enum": [
                            1,
                            2
                          ]
                        },
                        "asrResourceId": {
                          "type": "string"
                        },
                        "asrModel": {
                          "type": "string",
                          "enum": [
                            "fun-asr",
                            "qwen-audio-3.1-asr-flash-filetrans"
                          ]
                        },
                        "channelMapping": {
                          "type": "object",
                          "required": [
                            "left",
                            "right"
                          ],
                          "properties": {
                            "left": {
                              "type": "string",
                              "enum": [
                                "agent",
                                "customer",
                                "unknown"
                              ]
                            },
                            "right": {
                              "type": "string",
                              "enum": [
                                "agent",
                                "customer",
                                "unknown"
                              ]
                            }
                          }
                        }
                      }
                    }
                  }
                },
                "oneOf": [
                  {
                    "required": [
                      "manifest"
                    ],
                    "properties": {
                      "manifest": {
                        "minItems": 1
                      }
                    },
                    "allOf": [
                      {
                        "anyOf": [
                          {
                            "required": [
                              "source"
                            ]
                          },
                          {
                            "properties": {
                              "manifest": {
                                "items": {
                                  "required": [
                                    "source"
                                  ]
                                }
                              }
                            }
                          }
                        ]
                      },
                      {
                        "anyOf": [
                          {
                            "required": [
                              "startedAt"
                            ]
                          },
                          {
                            "properties": {
                              "manifest": {
                                "items": {
                                  "required": [
                                    "startedAt"
                                  ]
                                }
                              }
                            }
                          }
                        ]
                      },
                      {
                        "anyOf": [
                          {
                            "required": [
                              "channels"
                            ]
                          },
                          {
                            "properties": {
                              "manifest": {
                                "items": {
                                  "required": [
                                    "channels"
                                  ]
                                }
                              }
                            }
                          }
                        ]
                      }
                    ]
                  },
                  {
                    "required": [
                      "archive",
                      "source",
                      "startedAt"
                    ],
                    "properties": {
                      "manifest": {
                        "maxItems": 0
                      }
                    }
                  }
                ]
              },
              "example": {
                "batchId": "YOUR_STABLE_BATCH_ID",
                "manifest": [
                  {
                    "requestId": "YOUR_ITEM_REQUEST_ID",
                    "filename": "call.wav",
                    "bytes": 32044,
                    "source": "CRM录音",
                    "startedAt": "2026-10-17T09:00:00+08:00",
                    "channels": 1,
                    "asrResourceId": "YOUR_ASR_RESOURCE_ID",
                    "asrModel": "fun-asr"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "按当前操作返回结果；任务状态须继续核对。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "batchId": "YOUR_BATCH_ID",
                  "jobs": [
                    {
                      "id": "YOUR_AUDIO_JOB_ID",
                      "status": "uploading"
                    }
                  ],
                  "duplicates": []
                }
              }
            }
          },
          "400": {
            "description": "参数、时间、声道、角色或Base64格式不合法。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "密钥缺失、失效、轮换或调用期间撤销。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "没有可用语音分钟额度；先核对套餐余额。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "企业未开通洞察、非管理员或权限/操作授权不足。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "操作不存在，或任务不存在/不属于当前企业。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "方法与操作不一致；使用Allow响应头中的方法。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "版本、状态、幂等或容量冲突；保留输入并read核对，勿盲目换号重试。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "410": {
            "description": "原音到期或已清理；转写、分析与复核仍保留。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "请求正文、文件或ZIP解压量超过上限；调整上传与分块。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "POST必须使用application/json。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "ASR/文本模型/方案缺失，音频或转写无法校验，或分析超限。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "密钥限流或识别并发已满；按Retry-After退避。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "502": {
            "description": "供应商结果缺失或模型输出无效；先read核对状态与已计费用。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "依赖、存储完整性或服务暂不可用；保存任务编号与输入。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/operations/insights.audio.chunk": {
      "post": {
        "operationId": "insights.audio.chunk",
        "summary": "上传录音分块",
        "description": "私有录音上传、异步转写、角色确认、质检及人工复核；请先阅读录音导入指南。\n\n响应示例仅说明结构，不代表已成功识别或质检。API Key必须绑定企业管理员并授权对应操作。\n\n单文件1–100MiB、最长7200秒、单/双声道；企业最多300个未清理任务、总声明容量2GiB；批量清单最多100项；ZIP必须平铺，解压最多100条且总量512MiB，超限、嵌套路径、重复文件名或路径穿越明确失败。\n\n清单子项支持create字段，覆盖顶层默认值；requestId省略时生成batchId-序号。清单创建可能部分成功，失败后保持原清单重放，不是全有或全无事务。\n\nZIP模式省略manifest或传空数组，并传archive:{filename,bytes}及source/startedAt；上传archiveJob的ZIP字节并complete，随后逐条跟踪jobs或archiveChildren。archive.manifest只是元数据，不代替真实ZIP字节。\n\nuncertain为提交未知；不要自动重提。识别使用语音分钟额度，文本模型质检另计。\n\n所有角色确认且含客户后才能分析；语义模型基于转写，噪音、音量与抢话需回听原音核对。\n\n原音回放为登录态私有接口，不提供公开音频URL。本组未新增异步完成Webhook，使用read/advance接续。\n\n原音默认保留365天，可在控制台设置1–3650天；到期返回410并清理原始字节，转写、质检和复核记录仍保留。本组没有修改保留策略的公开操作。",
        "tags": [
          "insights.audio"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-yunfu-permissions": [
          "reports",
          "service",
          "applications"
        ],
        "x-yunfu-billable": false,
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_.:-]{8,100}$"
            },
            "description": "POST必须携带8–100位Idempotency-Key（字母数字、下划线、短横线、点、冒号）；同一次写入重传保持key及正文不变，不同操作/分块使用不同key，轮询advance每次使用新key。网关24小时有界响应重放；未知或过期不会重复执行。"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "jobId",
                  "index",
                  "data"
                ],
                "properties": {
                  "jobId": {
                    "type": "string"
                  },
                  "index": {
                    "type": "integer",
                    "minimum": 0
                  },
                  "data": {
                    "type": "string",
                    "contentEncoding": "base64",
                    "description": "Canonical Base64; exactly 1048576 raw bytes except the final chunk."
                  }
                }
              },
              "example": {
                "jobId": "YOUR_AUDIO_JOB_ID",
                "index": 0,
                "data": "BASE64_OF_THIS_CHUNK"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "按当前操作返回结果；任务状态须继续核对。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "received": 0
                }
              }
            }
          },
          "400": {
            "description": "参数、时间、声道、角色或Base64格式不合法。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "密钥缺失、失效、轮换或调用期间撤销。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "没有可用语音分钟额度；先核对套餐余额。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "企业未开通洞察、非管理员或权限/操作授权不足。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "操作不存在，或任务不存在/不属于当前企业。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "方法与操作不一致；使用Allow响应头中的方法。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "版本、状态、幂等或容量冲突；保留输入并read核对，勿盲目换号重试。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "410": {
            "description": "原音到期或已清理；转写、分析与复核仍保留。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "请求正文、文件或ZIP解压量超过上限；调整上传与分块。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "POST必须使用application/json。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "ASR/文本模型/方案缺失，音频或转写无法校验，或分析超限。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "密钥限流或识别并发已满；按Retry-After退避。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "502": {
            "description": "供应商结果缺失或模型输出无效；先read核对状态与已计费用。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "依赖、存储完整性或服务暂不可用；保存任务编号与输入。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/operations/insights.audio.complete": {
      "post": {
        "operationId": "insights.audio.complete",
        "summary": "完成录音上传",
        "description": "私有录音上传、异步转写、角色确认、质检及人工复核；请先阅读录音导入指南。\n\n响应示例仅说明结构，不代表已成功识别或质检。API Key必须绑定企业管理员并授权对应操作。\n\n单文件1–100MiB、最长7200秒、单/双声道；企业最多300个未清理任务、总声明容量2GiB；批量清单最多100项；ZIP必须平铺，解压最多100条且总量512MiB，超限、嵌套路径、重复文件名或路径穿越明确失败。\n\n清单子项支持create字段，覆盖顶层默认值；requestId省略时生成batchId-序号。清单创建可能部分成功，失败后保持原清单重放，不是全有或全无事务。\n\nZIP模式省略manifest或传空数组，并传archive:{filename,bytes}及source/startedAt；上传archiveJob的ZIP字节并complete，随后逐条跟踪jobs或archiveChildren。archive.manifest只是元数据，不代替真实ZIP字节。\n\nuncertain为提交未知；不要自动重提。识别使用语音分钟额度，文本模型质检另计。\n\n所有角色确认且含客户后才能分析；语义模型基于转写，噪音、音量与抢话需回听原音核对。\n\n原音回放为登录态私有接口，不提供公开音频URL。本组未新增异步完成Webhook，使用read/advance接续。\n\n原音默认保留365天，可在控制台设置1–3650天；到期返回410并清理原始字节，转写、质检和复核记录仍保留。本组没有修改保留策略的公开操作。",
        "tags": [
          "insights.audio"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-yunfu-permissions": [
          "reports",
          "service",
          "applications"
        ],
        "x-yunfu-billable": true,
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_.:-]{8,100}$"
            },
            "description": "POST必须携带8–100位Idempotency-Key（字母数字、下划线、短横线、点、冒号）；同一次写入重传保持key及正文不变，不同操作/分块使用不同key，轮询advance每次使用新key。网关24小时有界响应重放；未知或过期不会重复执行。"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "jobId"
                ],
                "properties": {
                  "jobId": {
                    "type": "string"
                  }
                }
              },
              "example": {
                "jobId": "YOUR_AUDIO_JOB_ID"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "按当前操作返回结果；任务状态须继续核对。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "job": {
                    "id": "YOUR_AUDIO_JOB_ID",
                    "status": "queued"
                  }
                }
              }
            }
          },
          "400": {
            "description": "参数、时间、声道、角色或Base64格式不合法。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "密钥缺失、失效、轮换或调用期间撤销。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "没有可用语音分钟额度；先核对套餐余额。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "企业未开通洞察、非管理员或权限/操作授权不足。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "操作不存在，或任务不存在/不属于当前企业。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "方法与操作不一致；使用Allow响应头中的方法。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "版本、状态、幂等或容量冲突；保留输入并read核对，勿盲目换号重试。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "410": {
            "description": "原音到期或已清理；转写、分析与复核仍保留。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "请求正文、文件或ZIP解压量超过上限；调整上传与分块。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "POST必须使用application/json。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "ASR/文本模型/方案缺失，音频或转写无法校验，或分析超限。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "密钥限流或识别并发已满；按Retry-After退避。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "502": {
            "description": "供应商结果缺失或模型输出无效；先read核对状态与已计费用。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "依赖、存储完整性或服务暂不可用；保存任务编号与输入。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/operations/insights.audio.advance": {
      "post": {
        "operationId": "insights.audio.advance",
        "summary": "推进录音识别",
        "description": "私有录音上传、异步转写、角色确认、质检及人工复核；请先阅读录音导入指南。\n\n响应示例仅说明结构，不代表已成功识别或质检。API Key必须绑定企业管理员并授权对应操作。\n\n单文件1–100MiB、最长7200秒、单/双声道；企业最多300个未清理任务、总声明容量2GiB；批量清单最多100项；ZIP必须平铺，解压最多100条且总量512MiB，超限、嵌套路径、重复文件名或路径穿越明确失败。\n\n清单子项支持create字段，覆盖顶层默认值；requestId省略时生成batchId-序号。清单创建可能部分成功，失败后保持原清单重放，不是全有或全无事务。\n\nZIP模式省略manifest或传空数组，并传archive:{filename,bytes}及source/startedAt；上传archiveJob的ZIP字节并complete，随后逐条跟踪jobs或archiveChildren。archive.manifest只是元数据，不代替真实ZIP字节。\n\nuncertain为提交未知；不要自动重提。识别使用语音分钟额度，文本模型质检另计。\n\n所有角色确认且含客户后才能分析；语义模型基于转写，噪音、音量与抢话需回听原音核对。\n\n原音回放为登录态私有接口，不提供公开音频URL。本组未新增异步完成Webhook，使用read/advance接续。\n\n原音默认保留365天，可在控制台设置1–3650天；到期返回410并清理原始字节，转写、质检和复核记录仍保留。本组没有修改保留策略的公开操作。",
        "tags": [
          "insights.audio"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-yunfu-permissions": [
          "reports",
          "service",
          "applications"
        ],
        "x-yunfu-billable": true,
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_.:-]{8,100}$"
            },
            "description": "POST必须携带8–100位Idempotency-Key（字母数字、下划线、短横线、点、冒号）；同一次写入重传保持key及正文不变，不同操作/分块使用不同key，轮询advance每次使用新key。网关24小时有界响应重放；未知或过期不会重复执行。"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "jobId"
                ],
                "properties": {
                  "jobId": {
                    "type": "string"
                  }
                }
              },
              "example": {
                "jobId": "YOUR_AUDIO_JOB_ID"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "按当前操作返回结果；任务状态须继续核对。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "job": {
                    "id": "YOUR_AUDIO_JOB_ID",
                    "status": "queued"
                  }
                }
              }
            }
          },
          "400": {
            "description": "参数、时间、声道、角色或Base64格式不合法。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "密钥缺失、失效、轮换或调用期间撤销。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "没有可用语音分钟额度；先核对套餐余额。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "企业未开通洞察、非管理员或权限/操作授权不足。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "操作不存在，或任务不存在/不属于当前企业。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "方法与操作不一致；使用Allow响应头中的方法。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "版本、状态、幂等或容量冲突；保留输入并read核对，勿盲目换号重试。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "410": {
            "description": "原音到期或已清理；转写、分析与复核仍保留。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "请求正文、文件或ZIP解压量超过上限；调整上传与分块。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "POST必须使用application/json。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "ASR/文本模型/方案缺失，音频或转写无法校验，或分析超限。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "密钥限流或识别并发已满；按Retry-After退避。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "502": {
            "description": "供应商结果缺失或模型输出无效；先read核对状态与已计费用。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "依赖、存储完整性或服务暂不可用；保存任务编号与输入。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/operations/insights.audio.roles": {
      "post": {
        "operationId": "insights.audio.roles",
        "summary": "确认录音说话人",
        "description": "私有录音上传、异步转写、角色确认、质检及人工复核；请先阅读录音导入指南。\n\n响应示例仅说明结构，不代表已成功识别或质检。API Key必须绑定企业管理员并授权对应操作。\n\n单文件1–100MiB、最长7200秒、单/双声道；企业最多300个未清理任务、总声明容量2GiB；批量清单最多100项；ZIP必须平铺，解压最多100条且总量512MiB，超限、嵌套路径、重复文件名或路径穿越明确失败。\n\n清单子项支持create字段，覆盖顶层默认值；requestId省略时生成batchId-序号。清单创建可能部分成功，失败后保持原清单重放，不是全有或全无事务。\n\nZIP模式省略manifest或传空数组，并传archive:{filename,bytes}及source/startedAt；上传archiveJob的ZIP字节并complete，随后逐条跟踪jobs或archiveChildren。archive.manifest只是元数据，不代替真实ZIP字节。\n\nuncertain为提交未知；不要自动重提。识别使用语音分钟额度，文本模型质检另计。\n\n所有角色确认且含客户后才能分析；语义模型基于转写，噪音、音量与抢话需回听原音核对。\n\n原音回放为登录态私有接口，不提供公开音频URL。本组未新增异步完成Webhook，使用read/advance接续。\n\n原音默认保留365天，可在控制台设置1–3650天；到期返回410并清理原始字节，转写、质检和复核记录仍保留。本组没有修改保留策略的公开操作。",
        "tags": [
          "insights.audio"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-yunfu-permissions": [
          "reports",
          "service",
          "applications"
        ],
        "x-yunfu-billable": false,
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_.:-]{8,100}$"
            },
            "description": "POST必须携带8–100位Idempotency-Key（字母数字、下划线、短横线、点、冒号）；同一次写入重传保持key及正文不变，不同操作/分块使用不同key，轮询advance每次使用新key。网关24小时有界响应重放；未知或过期不会重复执行。"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "jobId",
                  "revision",
                  "roles"
                ],
                "properties": {
                  "jobId": {
                    "type": "string"
                  },
                  "revision": {
                    "type": "integer",
                    "minimum": 0
                  },
                  "roles": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "string",
                      "enum": [
                        "agent",
                        "customer",
                        "ai",
                        "unknown"
                      ]
                    }
                  }
                }
              },
              "example": {
                "jobId": "YOUR_AUDIO_JOB_ID",
                "revision": 1,
                "roles": {
                  "channel-0-speaker-0": "customer",
                  "channel-1-speaker-0": "agent"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "按当前操作返回结果；任务状态须继续核对。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "job": {
                    "id": "YOUR_AUDIO_JOB_ID",
                    "status": "queued"
                  }
                }
              }
            }
          },
          "400": {
            "description": "参数、时间、声道、角色或Base64格式不合法。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "密钥缺失、失效、轮换或调用期间撤销。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "没有可用语音分钟额度；先核对套餐余额。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "企业未开通洞察、非管理员或权限/操作授权不足。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "操作不存在，或任务不存在/不属于当前企业。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "方法与操作不一致；使用Allow响应头中的方法。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "版本、状态、幂等或容量冲突；保留输入并read核对，勿盲目换号重试。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "410": {
            "description": "原音到期或已清理；转写、分析与复核仍保留。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "请求正文、文件或ZIP解压量超过上限；调整上传与分块。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "POST必须使用application/json。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "ASR/文本模型/方案缺失，音频或转写无法校验，或分析超限。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "密钥限流或识别并发已满；按Retry-After退避。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "502": {
            "description": "供应商结果缺失或模型输出无效；先read核对状态与已计费用。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "依赖、存储完整性或服务暂不可用；保存任务编号与输入。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/operations/insights.audio.retry": {
      "post": {
        "operationId": "insights.audio.retry",
        "summary": "确认重试录音识别",
        "description": "私有录音上传、异步转写、角色确认、质检及人工复核；请先阅读录音导入指南。\n\n响应示例仅说明结构，不代表已成功识别或质检。API Key必须绑定企业管理员并授权对应操作。\n\n单文件1–100MiB、最长7200秒、单/双声道；企业最多300个未清理任务、总声明容量2GiB；批量清单最多100项；ZIP必须平铺，解压最多100条且总量512MiB，超限、嵌套路径、重复文件名或路径穿越明确失败。\n\n清单子项支持create字段，覆盖顶层默认值；requestId省略时生成batchId-序号。清单创建可能部分成功，失败后保持原清单重放，不是全有或全无事务。\n\nZIP模式省略manifest或传空数组，并传archive:{filename,bytes}及source/startedAt；上传archiveJob的ZIP字节并complete，随后逐条跟踪jobs或archiveChildren。archive.manifest只是元数据，不代替真实ZIP字节。\n\nuncertain为提交未知；不要自动重提。识别使用语音分钟额度，文本模型质检另计。\n\n所有角色确认且含客户后才能分析；语义模型基于转写，噪音、音量与抢话需回听原音核对。\n\n原音回放为登录态私有接口，不提供公开音频URL。本组未新增异步完成Webhook，使用read/advance接续。\n\n原音默认保留365天，可在控制台设置1–3650天；到期返回410并清理原始字节，转写、质检和复核记录仍保留。本组没有修改保留策略的公开操作。",
        "tags": [
          "insights.audio"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-yunfu-permissions": [
          "reports",
          "service",
          "applications"
        ],
        "x-yunfu-billable": true,
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_.:-]{8,100}$"
            },
            "description": "POST必须携带8–100位Idempotency-Key（字母数字、下划线、短横线、点、冒号）；同一次写入重传保持key及正文不变，不同操作/分块使用不同key，轮询advance每次使用新key。网关24小时有界响应重放；未知或过期不会重复执行。"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "jobId",
                  "confirmProviderRetry"
                ],
                "properties": {
                  "jobId": {
                    "type": "string"
                  },
                  "confirmProviderRetry": {
                    "const": true
                  },
                  "asrResourceId": {
                    "type": "string"
                  },
                  "asrModel": {
                    "type": "string",
                    "enum": [
                      "fun-asr",
                      "qwen-audio-3.1-asr-flash-filetrans"
                    ]
                  }
                }
              },
              "example": {
                "jobId": "YOUR_AUDIO_JOB_ID",
                "confirmProviderRetry": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "按当前操作返回结果；任务状态须继续核对。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "job": {
                    "id": "YOUR_AUDIO_JOB_ID",
                    "status": "queued"
                  }
                }
              }
            }
          },
          "400": {
            "description": "参数、时间、声道、角色或Base64格式不合法。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "密钥缺失、失效、轮换或调用期间撤销。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "没有可用语音分钟额度；先核对套餐余额。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "企业未开通洞察、非管理员或权限/操作授权不足。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "操作不存在，或任务不存在/不属于当前企业。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "方法与操作不一致；使用Allow响应头中的方法。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "版本、状态、幂等或容量冲突；保留输入并read核对，勿盲目换号重试。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "410": {
            "description": "原音到期或已清理；转写、分析与复核仍保留。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "请求正文、文件或ZIP解压量超过上限；调整上传与分块。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "POST必须使用application/json。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "ASR/文本模型/方案缺失，音频或转写无法校验，或分析超限。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "密钥限流或识别并发已满；按Retry-After退避。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "502": {
            "description": "供应商结果缺失或模型输出无效；先read核对状态与已计费用。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "依赖、存储完整性或服务暂不可用；保存任务编号与输入。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/operations/insights.audio.analyze": {
      "post": {
        "operationId": "insights.audio.analyze",
        "summary": "执行录音质检",
        "description": "私有录音上传、异步转写、角色确认、质检及人工复核；请先阅读录音导入指南。\n\n响应示例仅说明结构，不代表已成功识别或质检。API Key必须绑定企业管理员并授权对应操作。\n\n单文件1–100MiB、最长7200秒、单/双声道；企业最多300个未清理任务、总声明容量2GiB；批量清单最多100项；ZIP必须平铺，解压最多100条且总量512MiB，超限、嵌套路径、重复文件名或路径穿越明确失败。\n\n清单子项支持create字段，覆盖顶层默认值；requestId省略时生成batchId-序号。清单创建可能部分成功，失败后保持原清单重放，不是全有或全无事务。\n\nZIP模式省略manifest或传空数组，并传archive:{filename,bytes}及source/startedAt；上传archiveJob的ZIP字节并complete，随后逐条跟踪jobs或archiveChildren。archive.manifest只是元数据，不代替真实ZIP字节。\n\nuncertain为提交未知；不要自动重提。识别使用语音分钟额度，文本模型质检另计。\n\n所有角色确认且含客户后才能分析；语义模型基于转写，噪音、音量与抢话需回听原音核对。\n\n原音回放为登录态私有接口，不提供公开音频URL。本组未新增异步完成Webhook，使用read/advance接续。\n\n原音默认保留365天，可在控制台设置1–3650天；到期返回410并清理原始字节，转写、质检和复核记录仍保留。本组没有修改保留策略的公开操作。",
        "tags": [
          "insights.audio"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-yunfu-permissions": [
          "reports",
          "service",
          "applications"
        ],
        "x-yunfu-billable": true,
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_.:-]{8,100}$"
            },
            "description": "POST必须携带8–100位Idempotency-Key（字母数字、下划线、短横线、点、冒号）；同一次写入重传保持key及正文不变，不同操作/分块使用不同key，轮询advance每次使用新key。网关24小时有界响应重放；未知或过期不会重复执行。"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "jobId",
                  "revision",
                  "requestId",
                  "engine",
                  "planMode"
                ],
                "properties": {
                  "jobId": {
                    "type": "string"
                  },
                  "revision": {
                    "type": "integer",
                    "minimum": 0
                  },
                  "requestId": {
                    "type": "string",
                    "pattern": "^[A-Za-z0-9_-]{8,100}$"
                  },
                  "engine": {
                    "type": "string",
                    "enum": [
                      "local",
                      "model"
                    ]
                  },
                  "planMode": {
                    "type": "string",
                    "enum": [
                      "bound",
                      "latest"
                    ]
                  },
                  "planId": {
                    "type": "string"
                  }
                }
              },
              "example": {
                "jobId": "YOUR_AUDIO_JOB_ID",
                "revision": 2,
                "requestId": "YOUR_ANALYSIS_REQUEST_ID",
                "engine": "model",
                "planMode": "latest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "按当前操作返回结果；任务状态须继续核对。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "conversationId": "YOUR_CONVERSATION_ID",
                  "status": "completed",
                  "accepted": false
                }
              }
            }
          },
          "400": {
            "description": "参数、时间、声道、角色或Base64格式不合法。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "密钥缺失、失效、轮换或调用期间撤销。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "没有可用语音分钟额度；先核对套餐余额。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "企业未开通洞察、非管理员或权限/操作授权不足。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "操作不存在，或任务不存在/不属于当前企业。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "方法与操作不一致；使用Allow响应头中的方法。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "版本、状态、幂等或容量冲突；保留输入并read核对，勿盲目换号重试。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "410": {
            "description": "原音到期或已清理；转写、分析与复核仍保留。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "请求正文、文件或ZIP解压量超过上限；调整上传与分块。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "POST必须使用application/json。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "ASR/文本模型/方案缺失，音频或转写无法校验，或分析超限。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "密钥限流或识别并发已满；按Retry-After退避。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "502": {
            "description": "供应商结果缺失或模型输出无效；先read核对状态与已计费用。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "依赖、存储完整性或服务暂不可用；保存任务编号与输入。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/operations/insights.audio.review": {
      "post": {
        "operationId": "insights.audio.review",
        "summary": "人工复核录音质检",
        "description": "私有录音上传、异步转写、角色确认、质检及人工复核；请先阅读录音导入指南。\n\n响应示例仅说明结构，不代表已成功识别或质检。API Key必须绑定企业管理员并授权对应操作。\n\n单文件1–100MiB、最长7200秒、单/双声道；企业最多300个未清理任务、总声明容量2GiB；批量清单最多100项；ZIP必须平铺，解压最多100条且总量512MiB，超限、嵌套路径、重复文件名或路径穿越明确失败。\n\n清单子项支持create字段，覆盖顶层默认值；requestId省略时生成batchId-序号。清单创建可能部分成功，失败后保持原清单重放，不是全有或全无事务。\n\nZIP模式省略manifest或传空数组，并传archive:{filename,bytes}及source/startedAt；上传archiveJob的ZIP字节并complete，随后逐条跟踪jobs或archiveChildren。archive.manifest只是元数据，不代替真实ZIP字节。\n\nuncertain为提交未知；不要自动重提。识别使用语音分钟额度，文本模型质检另计。\n\n所有角色确认且含客户后才能分析；语义模型基于转写，噪音、音量与抢话需回听原音核对。\n\n原音回放为登录态私有接口，不提供公开音频URL。本组未新增异步完成Webhook，使用read/advance接续。\n\n原音默认保留365天，可在控制台设置1–3650天；到期返回410并清理原始字节，转写、质检和复核记录仍保留。本组没有修改保留策略的公开操作。",
        "tags": [
          "insights.audio"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-yunfu-permissions": [
          "reports",
          "service",
          "applications"
        ],
        "x-yunfu-billable": false,
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_.:-]{8,100}$"
            },
            "description": "POST必须携带8–100位Idempotency-Key（字母数字、下划线、短横线、点、冒号）；同一次写入重传保持key及正文不变，不同操作/分块使用不同key，轮询advance每次使用新key。网关24小时有界响应重放；未知或过期不会重复执行。"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "jobId",
                  "revision",
                  "score",
                  "reason"
                ],
                "properties": {
                  "jobId": {
                    "type": "string"
                  },
                  "revision": {
                    "type": "integer",
                    "minimum": 0
                  },
                  "score": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 100
                  },
                  "reason": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 3000
                  }
                }
              },
              "example": {
                "jobId": "YOUR_AUDIO_JOB_ID",
                "revision": 3,
                "score": 80,
                "reason": "已逐段核对原始录音与质检证据，现确认人工评分。"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "按当前操作返回结果；任务状态须继续核对。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "id": "YOUR_CONVERSATION_ID",
                  "revision": 4,
                  "review": {
                    "score": 80,
                    "reason": "人工复核依据",
                    "at": "2026-10-17T09:30:00+08:00"
                  }
                }
              }
            }
          },
          "400": {
            "description": "参数、时间、声道、角色或Base64格式不合法。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "密钥缺失、失效、轮换或调用期间撤销。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "没有可用语音分钟额度；先核对套餐余额。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "企业未开通洞察、非管理员或权限/操作授权不足。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "操作不存在，或任务不存在/不属于当前企业。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "方法与操作不一致；使用Allow响应头中的方法。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "版本、状态、幂等或容量冲突；保留输入并read核对，勿盲目换号重试。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "410": {
            "description": "原音到期或已清理；转写、分析与复核仍保留。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "请求正文、文件或ZIP解压量超过上限；调整上传与分块。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "POST必须使用application/json。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "ASR/文本模型/方案缺失，音频或转写无法校验，或分析超限。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "密钥限流或识别并发已满；按Retry-After退避。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "502": {
            "description": "供应商结果缺失或模型输出无效；先read核对状态与已计费用。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "依赖、存储完整性或服务暂不可用；保存任务编号与输入。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/operations/insights.conversations.import": {
      "post": {
        "operationId": "insights.conversations.import",
        "summary": "导入结构化会话",
        "description": "整批原子导入1–50条已有明文会话，以稳定externalId识别重复与更新；不自动分析。\n\n仅导入调用方已合法持有并获授权处理的明文会话；企业微信会话专区的明文提取须使用其专用授权链路。本接口不提取企业微信明文。\n\n企业须已开通洞察；API Key绑定企业管理员，账号同时具有reports、service、applications权限，密钥逐项授权本操作。企业及归属由服务端确定。\n\n导入不调用ASR或文本模型，不自动启动分析，不产生供应商调用费用；analysisStarted始终为false。需要分析时在洞察控制台明确发起。\n\n严格按字段契约提交：请求、会话和消息对象中的未知字段都会被拒绝；查询只接受externalId，不接受其他参数。",
        "tags": [
          "insights.conversations"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-yunfu-permissions": [
          "reports",
          "service",
          "applications"
        ],
        "x-yunfu-billable": false,
        "x-yunfu-max-body-bytes": 150000,
        "x-yunfu-atomic": true,
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_.:-]{8,100}$"
            },
            "description": "POST必须携带8–100位Idempotency-Key。同键同请求只重放结果，同键不同内容返回409。externalId另行保证业务级去重；修改内容使用新请求键及最新revision。"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "records"
                ],
                "properties": {
                  "records": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 50,
                    "items": {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "externalId",
                        "source",
                        "startedAt",
                        "messages"
                      ],
                      "properties": {
                        "externalId": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 100
                        },
                        "source": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 80
                        },
                        "title": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200
                        },
                        "startedAt": {
                          "type": "string",
                          "format": "date-time",
                          "pattern": "(?:[zZ]|[+-]\\d{2}:\\d{2})$"
                        },
                        "duration": {
                          "type": "number",
                          "minimum": 0,
                          "description": "Seconds; must cover every supplied message start/end offset."
                        },
                        "demo": {
                          "type": "boolean"
                        },
                        "revision": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "messages": {
                          "type": "array",
                          "minItems": 1,
                          "maxItems": 1000,
                          "items": {
                            "type": "object",
                            "additionalProperties": false,
                            "required": [
                              "role",
                              "text"
                            ],
                            "properties": {
                              "id": {
                                "type": "string",
                                "minLength": 1,
                                "maxLength": 200
                              },
                              "role": {
                                "type": "string",
                                "enum": [
                                  "customer",
                                  "agent",
                                  "ai",
                                  "unknown"
                                ]
                              },
                              "speaker": {
                                "type": "string",
                                "minLength": 1,
                                "maxLength": 200
                              },
                              "text": {
                                "type": "string",
                                "minLength": 1,
                                "maxLength": 10000
                              },
                              "sentAt": {
                                "type": "string",
                                "format": "date-time",
                                "pattern": "(?:[zZ]|[+-]\\d{2}:\\d{2})$"
                              },
                              "seconds": {
                                "type": "number",
                                "minimum": 0
                              },
                              "endSeconds": {
                                "type": "number",
                                "minimum": 0,
                                "description": "Must be greater than or equal to seconds (or zero when seconds is omitted)."
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              },
              "example": {
                "records": [
                  {
                    "externalId": "wecom-demo-001",
                    "source": "企业微信授权会话",
                    "title": "退款咨询（演示）",
                    "startedAt": "2026-10-20T09:00:00+08:00",
                    "demo": true,
                    "messages": [
                      {
                        "id": "m1",
                        "role": "customer",
                        "speaker": "客户",
                        "text": "退款什么时候到账？",
                        "sentAt": "2026-10-20T09:00:00+08:00"
                      },
                      {
                        "id": "m2",
                        "role": "agent",
                        "speaker": "客服",
                        "text": "我会核对退款进度并向您反馈。",
                        "sentAt": "2026-10-20T09:01:00+08:00"
                      }
                    ]
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "导入回执或元数据；不会启动分析。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "results",
                    "created",
                    "updated",
                    "unchanged",
                    "analysisStarted"
                  ],
                  "properties": {
                    "results": {
                      "type": "array",
                      "minItems": 1,
                      "maxItems": 50,
                      "items": {
                        "type": "object",
                        "additionalProperties": false,
                        "required": [
                          "externalId",
                          "conversationId",
                          "revision",
                          "status",
                          "messageCount"
                        ],
                        "properties": {
                          "externalId": {
                            "type": "string",
                            "minLength": 1,
                            "maxLength": 100
                          },
                          "conversationId": {
                            "type": "string"
                          },
                          "revision": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "created",
                              "updated",
                              "unchanged"
                            ]
                          },
                          "messageCount": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 1000
                          }
                        }
                      }
                    },
                    "created": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 50
                    },
                    "updated": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 50
                    },
                    "unchanged": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 50
                    },
                    "analysisStarted": {
                      "type": "boolean",
                      "const": false
                    }
                  }
                },
                "example": {
                  "results": [
                    {
                      "externalId": "wecom-demo-001",
                      "conversationId": "YOUR_CONVERSATION_ID",
                      "revision": 1,
                      "status": "created",
                      "messageCount": 2
                    }
                  ],
                  "created": 1,
                  "updated": 0,
                  "unchanged": 0,
                  "analysisStarted": false
                }
              }
            }
          },
          "400": {
            "description": "参数、时间、声道、角色或Base64格式不合法。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "密钥缺失、失效、轮换或调用期间撤销。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "没有可用语音分钟额度；先核对套餐余额。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "企业未开通洞察、非管理员或权限/操作授权不足。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "操作不存在，或任务不存在/不属于当前企业。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "方法与操作不一致；使用Allow响应头中的方法。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "版本、状态、幂等或容量冲突；保留输入并read核对，勿盲目换号重试。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "410": {
            "description": "原音到期或已清理；转写、分析与复核仍保留。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "请求正文、文件或ZIP解压量超过上限；调整上传与分块。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "POST必须使用application/json。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "ASR/文本模型/方案缺失，音频或转写无法校验，或分析超限。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "密钥限流或识别并发已满；按Retry-After退避。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "502": {
            "description": "供应商结果缺失或模型输出无效；先read核对状态与已计费用。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "依赖、存储完整性或服务暂不可用；保存任务编号与输入。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/operations/insights.conversations.read": {
      "get": {
        "operationId": "insights.conversations.read",
        "summary": "读取 API 会话版本",
        "description": "按externalId查询当前企业已导入会话的元数据和最新revision，供更新或未知结果核对；不返回明文消息。\n\n仅导入调用方已合法持有并获授权处理的明文会话；企业微信会话专区的明文提取须使用其专用授权链路。本接口不提取企业微信明文。\n\n企业须已开通洞察；API Key绑定企业管理员，账号同时具有reports、service、applications权限，密钥逐项授权本操作。企业及归属由服务端确定。\n\n导入不调用ASR或文本模型，不自动启动分析，不产生供应商调用费用；analysisStarted始终为false。需要分析时在洞察控制台明确发起。\n\n严格按字段契约提交：请求、会话和消息对象中的未知字段都会被拒绝；查询只接受externalId，不接受其他参数。",
        "tags": [
          "insights.conversations"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-yunfu-permissions": [
          "reports",
          "service",
          "applications"
        ],
        "x-yunfu-billable": false,
        "x-yunfu-allow-extra-query": false,
        "parameters": [
          {
            "in": "query",
            "name": "externalId",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100
            },
            "description": "必填，1–100字符，使用原导入的稳定externalId；不存在或不属于当前企业返回404。"
          }
        ],
        "responses": {
          "200": {
            "description": "导入回执或元数据；不会启动分析。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "record"
                  ],
                  "properties": {
                    "record": {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "externalId",
                        "conversationId",
                        "revision",
                        "source",
                        "title",
                        "startedAt",
                        "messageCount",
                        "resultStatus"
                      ],
                      "properties": {
                        "externalId": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 100
                        },
                        "conversationId": {
                          "type": "string"
                        },
                        "revision": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "source": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 80
                        },
                        "title": {
                          "type": "string"
                        },
                        "startedAt": {
                          "type": "string",
                          "format": "date-time",
                          "pattern": "(?:[zZ]|[+-]\\d{2}:\\d{2})$"
                        },
                        "messageCount": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 1000
                        },
                        "resultStatus": {
                          "type": "string",
                          "enum": [
                            "stale",
                            "current"
                          ]
                        }
                      }
                    }
                  }
                },
                "example": {
                  "record": {
                    "externalId": "wecom-demo-001",
                    "conversationId": "YOUR_CONVERSATION_ID",
                    "revision": 1,
                    "source": "企业微信授权会话",
                    "title": "退款咨询（演示）",
                    "startedAt": "2026-10-20T09:00:00+08:00",
                    "messageCount": 2,
                    "resultStatus": "stale"
                  }
                }
              }
            }
          },
          "400": {
            "description": "参数、时间、声道、角色或Base64格式不合法。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "密钥缺失、失效、轮换或调用期间撤销。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "没有可用语音分钟额度；先核对套餐余额。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "企业未开通洞察、非管理员或权限/操作授权不足。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "操作不存在，或任务不存在/不属于当前企业。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "方法与操作不一致；使用Allow响应头中的方法。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "版本、状态、幂等或容量冲突；保留输入并read核对，勿盲目换号重试。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "410": {
            "description": "原音到期或已清理；转写、分析与复核仍保留。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "请求正文、文件或ZIP解压量超过上限；调整上传与分块。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "POST必须使用application/json。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "ASR/文本模型/方案缺失，音频或转写无法校验，或分析超限。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "密钥限流或识别并发已满；按Retry-After退避。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "502": {
            "description": "供应商结果缺失或模型输出无效；先read核对状态与已计费用。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "依赖、存储完整性或服务暂不可用；保存任务编号与输入。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "企业须开通洞察；企业管理员须具有 reports、service、applications 权限，并为密钥逐项授权所需 insights.audio 或 insights.conversations 操作。密钥与企业/管理员绑定，不接受请求自报租户或账户。 标准会话导入无需ASR或模型。录音转写须先在控制台配置并授权北京百炼 ASR；独立洞察资源优先，多个候选时明确选择 asrResourceId。engine=model 还须配置文本模型与已发布分析方案。本组不开放这些配置写入。 YUNFU_BASE_URL 是部署根地址（不含 /api），服务端保存 YUNFU_API_KEY。发送 Authorization: Bearer；POST 使用 application/json 与8–100位 Idempotency-Key。网关自动固定action，调用方可以省略。"
      }
    }
  },
  "x-yunfu-guide": [
    {
      "id": "prepare",
      "title": "调用前准备",
      "steps": [
        "企业须开通洞察；企业管理员须具有 reports、service、applications 权限，并为密钥逐项授权所需 insights.audio 或 insights.conversations 操作。密钥与企业/管理员绑定，不接受请求自报租户或账户。",
        "标准会话导入无需ASR或模型。录音转写须先在控制台配置并授权北京百炼 ASR；独立洞察资源优先，多个候选时明确选择 asrResourceId。engine=model 还须配置文本模型与已发布分析方案。本组不开放这些配置写入。",
        "YUNFU_BASE_URL 是部署根地址（不含 /api），服务端保存 YUNFU_API_KEY。发送 Authorization: Bearer；POST 使用 application/json 与8–100位 Idempotency-Key。网关自动固定action，调用方可以省略。"
      ]
    },
    {
      "id": "standard-import",
      "title": "标准会话：导入、去重与更新",
      "steps": [
        "POST insights.conversations.import导入已获授权且调用方已持有的明文，正文为{records:[...]}；1–50条会话，每条1–1000条消息，整份JSON最多150000字节。每条必填externalId、source、startedAt和messages；时间必须带时区，role为customer/agent/ai/unknown。",
        "externalId须稳定且为1–100字符，source为1–80字符，title可选且提供时为1–200字符；duration及messages的seconds/endSeconds单位为秒，sentAt提供时须带时区。导入为整批原子写入，任意无效项或冲突不会部分落库。",
        "新externalId返回created；规范化内容相同返回unchanged。修改既有会话前GET insights.conversations.read?externalId=原编号，使用record.revision和新Idempotency-Key提交；缺少或过期revision返回409。read仅返回元数据和最新版本，不返回消息明文。",
        "保存返回results中的conversationId/revision和created/updated/unchanged数量。analysisStarted固定false；本接口不调用ASR、模型或自动分析，不产生供应商调用费用。企业微信会话专区的明文提取属于专用授权链路，本标准接口不执行该提取。"
      ]
    },
    {
      "id": "single",
      "title": "单文件：创建、分块、提交",
      "steps": [
        "1. GET insights.audio.read（不传jobId），核对 config.resources、config.asrModels、limits 和 retention。列表最多100条，按更新时间倒序；没有通用分页。",
        "2. POST create：requestId、filename、bytes、source、startedAt、channels 必填。startedAt 必须带时区；title 可选。保存返回 job.id 及原始元数据。requestId 与网关幂等key是两层独立标识；同requestId不得更改元数据或“显式/省略模型”的意图。",
        "3. 按原始字节切成1048576字节（1MiB）分块，序号从0起。除最后一块外长度必须恰好1MiB；末块长度为 min(1MiB, bytes-index*1MiB)。将每块编码为规范Base64，不带data:前缀；逐块POST chunk。received是该块序号。",
        "4. 每个chunk使用独立稳定key；同块重传保持key与内容不变。全部块齐全后POST complete。服务端核对连续序号、总字节、完整性、时长与实际声道；普通音频返回queued只表示待识别。"
      ]
    },
    {
      "id": "batch",
      "title": "清单与ZIP批量导入",
      "steps": [
        "清单模式：POST batch，传batchId与1–100项manifest。子项支持create字段，覆盖顶层默认值；子项requestId省略时使用batchId-序号（从1起，整体仍须≤100字符）。返回jobs后，对每条任务分别chunk/complete；传archive元数据不会自动上传或解压。",
        "ZIP模式：省略manifest或传[]，提供archive:{filename:\"calls.zip\",bytes:实际ZIP字节数}及顶层source/startedAt；channels默认1，需要左右映射时设为2。返回archiveJob后上传ZIP本身的分块，再对父任务complete；支持直接create一个.zip任务。",
        "ZIP必须平铺，最多100条支持格式的录音；压缩包≤100MiB，单条解压≤100MiB，解压合计≤512MiB；拒绝目录路径、重复文件名、嵌套ZIP和非音频条目。实际内容会解码验证；archive.manifest只是来源元数据，不控制实际子项。",
        "清单与ZIP子项不是整批原子事务；可能已保存部分任务后遇到错误。保持原batchId/元数据安全重放；若网关key已缓存错误须先read核对，再用新网关key重放同一业务清单。ZIP重新complete会接续已建子任务。父任务completed仅表示解包完成；逐条读取jobs或archiveChildren确认转写和分析。"
      ]
    },
    {
      "id": "roles-analysis",
      "title": "角色、方案、分析与人工复核",
      "steps": [
        "转写后read返回job.segments及conversation。roles的键必须使用实际segments[].speaker，覆盖全部且不能猜测或多传；值为customer/agent/ai/unknown。所有角色已知且至少一位customer后才可分析。",
        "双声道create/batch可传channelMapping:{left:\"agent\",right:\"customer\"}，仅channels=2合法；left对应provider声道0，right对应1。两侧可用agent/customer/unknown。它只标注provider声道，不做音轨分离，也不保证每个说话人都被识别。核对read中的roleConfirmed，必要时人工roles确认。",
        "仅在角色或确认状态发生变化时，roles 才递增会话 revision、归档人工复核并将旧结果标为 stale。重复确认相同角色保留现有分析和人工评分。每次roles/analyze/review前读取最新conversation.revision；409时保留输入并重新核对。accountId为只读归属，由服务端设置为密钥绑定的管理员，不能在导入时指定。",
        "POST analyze：jobId/revision/requestId/engine/planMode必填，planId可选。engine=model用文本模型，local仅做字面规则；bound优先复用已绑定快照，latest使用当前发布方案。单会话最多1000段、60000字。当前同步成功返回{conversationId,status:\"completed\",accepted:false}，重复完成可返回duplicate:true；没有公开202排队契约。",
        "分析后read查看conversation.runs、证据、analysisJob/analysisAttempts与最新revision。POST review提交0–100分与非空reason；它直接返回完整会话（含id/revision/review），不包在job中。模型原结论与历史保留；噪音、音量、抢话仍需回听原音核对。"
      ]
    },
    {
      "id": "recovery",
      "title": "轮询、断点与未知结果",
      "steps": [
        "保存job.id、batchId、原始元数据、文件与本地已确认分块索引。服务重启后read恢复任务；没有公开已上传分块列表，客户端可对uploading任务安全重传同内容分块。勿从最近100条列表中未看到任务就认定任务不存在。",
        "queued/recognizing可用advance有界推进，建议约5秒间隔并遵守Retry-After。每次真正推进使用新的网关key；重复旧key只重放旧响应。submitting表明提交进行中；后台会有限接续，但客户端仍应read/advance核对最终状态。",
        "uncertain或提交租约过期表示供应商结果未知。先核对供应商控制台与费用，禁止自动重提。明确确认后retry传confirmProviderRetry:true，可选更换授权资源/模型；failed/uncertain或未获得供应商task的queued才允许，任务处理中返回409。未知预留会保留，超过10笔须管理员核对。",
        "分析超时/失败后先read核对runs中的requestId及analysisJob/analysisAttempts。本组未开放analysis status/recover操作；已有模型回执但未落库时在控制台恢复，不能虚构公开恢复路径，也不能自动换requestId再次付费。网关409未知响应可含requestId/state。",
        "网关POST幂等key支持字母数字、下划线、短横线、点、冒号，共8–100位；同一次写入保持操作/查询/正文完全一致。响应最多有界缓存24小时；unknown、处理中、超限响应或过期不可重放时返回409，服务端不会再次执行。"
      ]
    },
    {
      "id": "billing-retention",
      "title": "用量、保留与能力边界",
      "steps": [
        "ASR提交前按服务端校验时长向上取整到整分钟预留语音额度；供应商成功后结算，即使下载、转写校验或后续质检失败也不能视为免费。明确拒绝/识别失败可释放对应预留；uncertain不自动退款。模型质检另计文本模型用量，local不调用文本模型。",
        "read中的usage.asrSeconds是实际原音秒数，不是向上取整后的结算数；quotaReceiptId用于核对。complete/advance/retry都可能推进付费识别，analyze:model可能产生模型费；文档与示例本身不会发起调用。",
        "原音默认365天，企业可在控制台设置1–3650天；read返回retention，job含retentionDays/expiresAt/purgedAt。到期即禁止重新上传、回听、识别与retry，清理调度删除原始字节；转写、分析、复核及历史继续保留。本组没有保留设置或删除操作。",
        "本组提供insights.audio的10个操作与insights.conversations的2个操作。控制台/api/insights、私有回放、上传URL、任意文档导入及配置管理不是本组公开别名。无异步识别/分析完成Webhook；通用api.request.completed只表示HTTP请求完成，不代表后台任务完成。"
      ]
    }
  ],
  "x-yunfu-field-contracts": [
    {
      "id": "insights-audio-read",
      "group": "洞察与质检",
      "name": "读取录音导入任务",
      "method": "GET",
      "currentPath": "/api/insights-audio",
      "publicPath": "/v1/operations/insights.audio.read",
      "actualPaths": [
        "/api/insights-audio"
      ],
      "status": "available",
      "description": "私有录音上传、异步转写、角色确认、质检及人工复核；请先阅读录音导入指南。",
      "scopes": [
        "tenant_admin",
        "reports",
        "service",
        "applications",
        "企业洞察授权",
        "insights.audio.read"
      ],
      "request": "?jobId=YOUR_AUDIO_JOB_ID",
      "response": "{\n  \"job\": {\n    \"id\": \"YOUR_AUDIO_JOB_ID\",\n    \"status\": \"transcribed\",\n    \"roleConfirmed\": false\n  },\n  \"conversation\": {\n    \"revision\": 1,\n    \"messages\": [],\n    \"runs\": []\n  }\n}",
      "requestFields": [
        {
          "name": "jobId (query)",
          "type": "string",
          "description": "可选；省略返回最近100个任务及可用ASR资源。指定时返回job及已有conversation。"
        }
      ],
      "responseFields": [
        {
          "name": "jobs / config / limits / retention",
          "type": "object fields",
          "description": "省略jobId时返回最近更新的100个任务（不含segments）、config.resources/asrModels、文件上限和当前retentionDays/revision/updatedAt；没有分页或分块进度查询。"
        },
        {
          "name": "conversation.accountId",
          "type": "string",
          "description": "只读归属：由服务端设置为密钥绑定的管理员账户；create/batch不接受accountId指定归属。"
        },
        {
          "name": "conversation.revision",
          "type": "integer",
          "description": "roles/analyze/review使用的会话版本；不是工作区或任务版本。每次写后重新read。"
        },
        {
          "name": "received / conversationId / review",
          "type": "action-dependent",
          "description": "chunk返回received分块序号而非累计数；analyze首次成功返回{conversationId,status:\"completed\",accepted:false}，重复已完成requestId返回duplicate:true且可省略accepted；review直接返回完整会话及递增revision/review。结果详情请再调用read。"
        },
        {
          "name": "job",
          "type": "object",
          "description": "按分支返回任务状态、真实文件元数据、原音时长（秒）、说话人片段、usage及retentionDays/expiresAt；batch返回jobs，ZIP创建返回archiveJob，ZIP complete另含jobs；chunk/analyze/review不返回job。不暴露供应商密钥或私有任务凭证。"
        },
        {
          "name": "conversation",
          "type": "object",
          "description": "read指定jobId且转写已入库时返回会话：revision、messages、runs、review等；电话号码遵循隐私权限。"
        }
      ],
      "curl": "curl \"$YUNFU_BASE_URL/v1/operations/insights.audio.read?jobId=YOUR_AUDIO_JOB_ID\" -H \"Authorization: Bearer $YUNFU_API_KEY\"",
      "callbackEvents": [],
      "idempotency": "POST必须携带8–100位Idempotency-Key（字母数字、下划线、短横线、点、冒号）；同一次写入重传保持key及正文不变，不同操作/分块使用不同key，轮询advance每次使用新key。网关24小时有界响应重放；未知或过期不会重复执行。",
      "notes": [
        "响应示例仅说明结构，不代表已成功识别或质检。API Key必须绑定企业管理员并授权对应操作。",
        "单文件1–100MiB、最长7200秒、单/双声道；企业最多300个未清理任务、总声明容量2GiB；批量清单最多100项；ZIP必须平铺，解压最多100条且总量512MiB，超限、嵌套路径、重复文件名或路径穿越明确失败。",
        "清单子项支持create字段，覆盖顶层默认值；requestId省略时生成batchId-序号。清单创建可能部分成功，失败后保持原清单重放，不是全有或全无事务。",
        "ZIP模式省略manifest或传空数组，并传archive:{filename,bytes}及source/startedAt；上传archiveJob的ZIP字节并complete，随后逐条跟踪jobs或archiveChildren。archive.manifest只是元数据，不代替真实ZIP字节。",
        "uncertain为提交未知；不要自动重提。识别使用语音分钟额度，文本模型质检另计。",
        "所有角色确认且含客户后才能分析；语义模型基于转写，噪音、音量与抢话需回听原音核对。",
        "原音回放为登录态私有接口，不提供公开音频URL。本组未新增异步完成Webhook，使用read/advance接续。",
        "原音默认保留365天，可在控制台设置1–3650天；到期返回410并清理原始字节，转写、质检和复核记录仍保留。本组没有修改保留策略的公开操作。"
      ]
    },
    {
      "id": "insights-audio-create",
      "group": "洞察与质检",
      "name": "创建录音导入",
      "method": "POST",
      "currentPath": "/api/insights-audio",
      "publicPath": "/v1/operations/insights.audio.create",
      "actualPaths": [
        "/api/insights-audio"
      ],
      "status": "available",
      "description": "私有录音上传、异步转写、角色确认、质检及人工复核；请先阅读录音导入指南。",
      "scopes": [
        "tenant_admin",
        "reports",
        "service",
        "applications",
        "企业洞察授权",
        "insights.audio.create"
      ],
      "request": "{\"requestId\":\"YOUR_STABLE_REQUEST_ID\",\"filename\":\"call.wav\",\"bytes\":32044,\"source\":\"CRM录音\",\"startedAt\":\"2026-10-17T09:00:00+08:00\",\"channels\":1,\"asrResourceId\":\"YOUR_ASR_RESOURCE_ID\",\"asrModel\":\"fun-asr\"}",
      "response": "{\n  \"job\": {\n    \"id\": \"YOUR_AUDIO_JOB_ID\",\n    \"status\": \"uploading\"\n  }\n}",
      "requestFields": [
        {
          "name": "requestId",
          "type": "string",
          "required": true,
          "description": "8–100位字母、数字、下划线或短横线。相同编号对应相同文件元数据。"
        },
        {
          "name": "filename",
          "type": "string",
          "required": true,
          "description": "带支持扩展名的原始文件名；不是服务端路径。"
        },
        {
          "name": "bytes",
          "type": "number",
          "required": true,
          "description": "原始文件总字节数，1–104857600；不含Base64膨胀。"
        },
        {
          "name": "source",
          "type": "string",
          "required": true,
          "description": "来源说明，不能用它更改企业范围。"
        },
        {
          "name": "startedAt",
          "type": "string",
          "required": true,
          "description": "录音真实开始时间，带时区ISO字符串；重跑保持一致。"
        },
        {
          "name": "channels",
          "type": "number",
          "required": true,
          "description": "1或2；必须与服务端解码所得声道数一致。"
        },
        {
          "name": "asrResourceId",
          "type": "string",
          "required": false,
          "description": "已授权的独立洞察 ASR 或复用语音 ASR 资源 ID；仅一个独立资源时优先使用，多个独立资源必须明确选择。"
        },
        {
          "name": "asrModel",
          "type": "string",
          "required": false,
          "description": "fun-asr或qwen-audio-3.1-asr-flash-filetrans；省略时使用独立资源的默认模型。"
        },
        {
          "name": "title",
          "type": "string",
          "required": false,
          "description": "可选录音标题，最多200字符；省略或空字符串时使用filename。"
        },
        {
          "name": "channelMapping",
          "type": "object",
          "required": false,
          "description": "双声道角色标注：left/right取agent、customer或unknown；只标注provider声道，不执行音轨分离。"
        },
        {
          "name": "batchId",
          "type": "string",
          "required": false,
          "description": "批量任务编号；同一清单可安全重放，子项按requestId分别幂等。"
        },
        {
          "name": "archive",
          "type": "object",
          "required": false,
          "description": "可选ZIP元数据；最多100条录音、解压总量512MiB，拒绝路径穿越和非音频扩展名。"
        }
      ],
      "responseFields": [
        {
          "name": "received / conversationId / review",
          "type": "action-dependent",
          "description": "chunk返回received分块序号而非累计数；analyze首次成功返回{conversationId,status:\"completed\",accepted:false}，重复已完成requestId返回duplicate:true且可省略accepted；review直接返回完整会话及递增revision/review。结果详情请再调用read。"
        },
        {
          "name": "job",
          "type": "object",
          "description": "按分支返回任务状态、真实文件元数据、原音时长（秒）、说话人片段、usage及retentionDays/expiresAt；batch返回jobs，ZIP创建返回archiveJob，ZIP complete另含jobs；chunk/analyze/review不返回job。不暴露供应商密钥或私有任务凭证。"
        },
        {
          "name": "conversation",
          "type": "object",
          "description": "read指定jobId且转写已入库时返回会话：revision、messages、runs、review等；电话号码遵循隐私权限。"
        }
      ],
      "curl": "curl -X POST \"$YUNFU_BASE_URL/v1/operations/insights.audio.create\" -H \"Authorization: Bearer $YUNFU_API_KEY\" -H \"Idempotency-Key: YOUR_UNIQUE_REQUEST_KEY\" -H 'Content-Type: application/json' --data '{\"requestId\":\"YOUR_STABLE_REQUEST_ID\",\"filename\":\"call.wav\",\"bytes\":32044,\"source\":\"CRM录音\",\"startedAt\":\"2026-10-17T09:00:00+08:00\",\"channels\":1,\"asrResourceId\":\"YOUR_ASR_RESOURCE_ID\",\"asrModel\":\"fun-asr\"}'",
      "callbackEvents": [],
      "idempotency": "POST必须携带8–100位Idempotency-Key（字母数字、下划线、短横线、点、冒号）；同一次写入重传保持key及正文不变，不同操作/分块使用不同key，轮询advance每次使用新key。网关24小时有界响应重放；未知或过期不会重复执行。",
      "notes": [
        "响应示例仅说明结构，不代表已成功识别或质检。API Key必须绑定企业管理员并授权对应操作。",
        "单文件1–100MiB、最长7200秒、单/双声道；企业最多300个未清理任务、总声明容量2GiB；批量清单最多100项；ZIP必须平铺，解压最多100条且总量512MiB，超限、嵌套路径、重复文件名或路径穿越明确失败。",
        "清单子项支持create字段，覆盖顶层默认值；requestId省略时生成batchId-序号。清单创建可能部分成功，失败后保持原清单重放，不是全有或全无事务。",
        "ZIP模式省略manifest或传空数组，并传archive:{filename,bytes}及source/startedAt；上传archiveJob的ZIP字节并complete，随后逐条跟踪jobs或archiveChildren。archive.manifest只是元数据，不代替真实ZIP字节。",
        "uncertain为提交未知；不要自动重提。识别使用语音分钟额度，文本模型质检另计。",
        "所有角色确认且含客户后才能分析；语义模型基于转写，噪音、音量与抢话需回听原音核对。",
        "原音回放为登录态私有接口，不提供公开音频URL。本组未新增异步完成Webhook，使用read/advance接续。",
        "原音默认保留365天，可在控制台设置1–3650天；到期返回410并清理原始字节，转写、质检和复核记录仍保留。本组没有修改保留策略的公开操作。"
      ]
    },
    {
      "id": "insights-audio-batch",
      "group": "洞察与质检",
      "name": "创建批量录音导入",
      "method": "POST",
      "currentPath": "/api/insights-audio",
      "publicPath": "/v1/operations/insights.audio.batch",
      "actualPaths": [
        "/api/insights-audio"
      ],
      "status": "available",
      "description": "私有录音上传、异步转写、角色确认、质检及人工复核；请先阅读录音导入指南。",
      "scopes": [
        "tenant_admin",
        "reports",
        "service",
        "applications",
        "企业洞察授权",
        "insights.audio.batch"
      ],
      "request": "{\"batchId\":\"YOUR_STABLE_BATCH_ID\",\"manifest\":[{\"requestId\":\"YOUR_ITEM_REQUEST_ID\",\"filename\":\"call.wav\",\"bytes\":32044,\"source\":\"CRM录音\",\"startedAt\":\"2026-10-17T09:00:00+08:00\",\"channels\":1,\"asrResourceId\":\"YOUR_ASR_RESOURCE_ID\",\"asrModel\":\"fun-asr\"}]}",
      "response": "{\n  \"batchId\": \"YOUR_BATCH_ID\",\n  \"jobs\": [\n    {\n      \"id\": \"YOUR_AUDIO_JOB_ID\",\n      \"status\": \"uploading\"\n    }\n  ],\n  \"duplicates\": []\n}",
      "requestFields": [
        {
          "name": "batchId",
          "type": "string",
          "required": true,
          "description": "批量任务编号；同一清单可安全重放，子项按requestId分别幂等。"
        },
        {
          "name": "manifest",
          "type": "array",
          "required": false,
          "description": "可选的1–100项音频元数据清单；省略或传空数组时返回待分块的ZIP父任务。"
        },
        {
          "name": "archive",
          "type": "object",
          "required": false,
          "description": "可选ZIP元数据；最多100条录音、解压总量512MiB，拒绝路径穿越和非音频扩展名。"
        },
        {
          "name": "source",
          "type": "string",
          "required": false,
          "description": "来源说明，不能用它更改企业范围。 清单模式由子项或顶层默认值提供；ZIP模式source/startedAt必填，channels省略时为1。"
        },
        {
          "name": "title",
          "type": "string",
          "required": false,
          "description": "可选录音标题，最多200字符；省略或空字符串时使用filename。"
        },
        {
          "name": "startedAt",
          "type": "string",
          "required": false,
          "description": "录音真实开始时间，带时区ISO字符串；重跑保持一致。 清单模式由子项或顶层默认值提供；ZIP模式source/startedAt必填，channels省略时为1。"
        },
        {
          "name": "channels",
          "type": "number",
          "required": false,
          "description": "1或2；必须与服务端解码所得声道数一致。 清单模式由子项或顶层默认值提供；ZIP模式source/startedAt必填，channels省略时为1。"
        },
        {
          "name": "channelMapping",
          "type": "object",
          "required": false,
          "description": "双声道角色标注：left/right取agent、customer或unknown；只标注provider声道，不执行音轨分离。"
        },
        {
          "name": "asrResourceId",
          "type": "string",
          "required": false,
          "description": "已授权的独立洞察 ASR 或复用语音 ASR 资源 ID；仅一个独立资源时优先使用，多个独立资源必须明确选择。"
        },
        {
          "name": "asrModel",
          "type": "string",
          "required": false,
          "description": "fun-asr或qwen-audio-3.1-asr-flash-filetrans；省略时使用独立资源的默认模型。"
        }
      ],
      "responseFields": [
        {
          "name": "received / conversationId / review",
          "type": "action-dependent",
          "description": "chunk返回received分块序号而非累计数；analyze首次成功返回{conversationId,status:\"completed\",accepted:false}，重复已完成requestId返回duplicate:true且可省略accepted；review直接返回完整会话及递增revision/review。结果详情请再调用read。"
        },
        {
          "name": "job",
          "type": "object",
          "description": "按分支返回任务状态、真实文件元数据、原音时长（秒）、说话人片段、usage及retentionDays/expiresAt；batch返回jobs，ZIP创建返回archiveJob，ZIP complete另含jobs；chunk/analyze/review不返回job。不暴露供应商密钥或私有任务凭证。"
        },
        {
          "name": "conversation",
          "type": "object",
          "description": "read指定jobId且转写已入库时返回会话：revision、messages、runs、review等；电话号码遵循隐私权限。"
        }
      ],
      "curl": "curl -X POST \"$YUNFU_BASE_URL/v1/operations/insights.audio.batch\" -H \"Authorization: Bearer $YUNFU_API_KEY\" -H \"Idempotency-Key: YOUR_UNIQUE_REQUEST_KEY\" -H 'Content-Type: application/json' --data '{\"batchId\":\"YOUR_STABLE_BATCH_ID\",\"manifest\":[{\"requestId\":\"YOUR_ITEM_REQUEST_ID\",\"filename\":\"call.wav\",\"bytes\":32044,\"source\":\"CRM录音\",\"startedAt\":\"2026-10-17T09:00:00+08:00\",\"channels\":1,\"asrResourceId\":\"YOUR_ASR_RESOURCE_ID\",\"asrModel\":\"fun-asr\"}]}'",
      "callbackEvents": [],
      "idempotency": "POST必须携带8–100位Idempotency-Key（字母数字、下划线、短横线、点、冒号）；同一次写入重传保持key及正文不变，不同操作/分块使用不同key，轮询advance每次使用新key。网关24小时有界响应重放；未知或过期不会重复执行。",
      "notes": [
        "响应示例仅说明结构，不代表已成功识别或质检。API Key必须绑定企业管理员并授权对应操作。",
        "单文件1–100MiB、最长7200秒、单/双声道；企业最多300个未清理任务、总声明容量2GiB；批量清单最多100项；ZIP必须平铺，解压最多100条且总量512MiB，超限、嵌套路径、重复文件名或路径穿越明确失败。",
        "清单子项支持create字段，覆盖顶层默认值；requestId省略时生成batchId-序号。清单创建可能部分成功，失败后保持原清单重放，不是全有或全无事务。",
        "ZIP模式省略manifest或传空数组，并传archive:{filename,bytes}及source/startedAt；上传archiveJob的ZIP字节并complete，随后逐条跟踪jobs或archiveChildren。archive.manifest只是元数据，不代替真实ZIP字节。",
        "uncertain为提交未知；不要自动重提。识别使用语音分钟额度，文本模型质检另计。",
        "所有角色确认且含客户后才能分析；语义模型基于转写，噪音、音量与抢话需回听原音核对。",
        "原音回放为登录态私有接口，不提供公开音频URL。本组未新增异步完成Webhook，使用read/advance接续。",
        "原音默认保留365天，可在控制台设置1–3650天；到期返回410并清理原始字节，转写、质检和复核记录仍保留。本组没有修改保留策略的公开操作。"
      ]
    },
    {
      "id": "insights-audio-chunk",
      "group": "洞察与质检",
      "name": "上传录音分块",
      "method": "POST",
      "currentPath": "/api/insights-audio",
      "publicPath": "/v1/operations/insights.audio.chunk",
      "actualPaths": [
        "/api/insights-audio"
      ],
      "status": "available",
      "description": "私有录音上传、异步转写、角色确认、质检及人工复核；请先阅读录音导入指南。",
      "scopes": [
        "tenant_admin",
        "reports",
        "service",
        "applications",
        "企业洞察授权",
        "insights.audio.chunk"
      ],
      "request": "{\"jobId\":\"YOUR_AUDIO_JOB_ID\",\"index\":0,\"data\":\"BASE64_OF_THIS_CHUNK\"}",
      "response": "{\n  \"received\": 0\n}",
      "requestFields": [
        {
          "name": "jobId",
          "type": "string",
          "required": true,
          "description": "当前企业录音任务ID，不可跨企业读取。"
        },
        {
          "name": "index",
          "type": "number",
          "required": true,
          "description": "从0开始的连续分块序号。"
        },
        {
          "name": "data",
          "type": "string",
          "required": true,
          "description": "该块纯Base64，不带data:前缀；每块原始字节1MiB，最后一块可不足。"
        }
      ],
      "responseFields": [
        {
          "name": "received / conversationId / review",
          "type": "action-dependent",
          "description": "chunk返回received分块序号而非累计数；analyze首次成功返回{conversationId,status:\"completed\",accepted:false}，重复已完成requestId返回duplicate:true且可省略accepted；review直接返回完整会话及递增revision/review。结果详情请再调用read。"
        },
        {
          "name": "job",
          "type": "object",
          "description": "按分支返回任务状态、真实文件元数据、原音时长（秒）、说话人片段、usage及retentionDays/expiresAt；batch返回jobs，ZIP创建返回archiveJob，ZIP complete另含jobs；chunk/analyze/review不返回job。不暴露供应商密钥或私有任务凭证。"
        },
        {
          "name": "conversation",
          "type": "object",
          "description": "read指定jobId且转写已入库时返回会话：revision、messages、runs、review等；电话号码遵循隐私权限。"
        }
      ],
      "curl": "curl -X POST \"$YUNFU_BASE_URL/v1/operations/insights.audio.chunk\" -H \"Authorization: Bearer $YUNFU_API_KEY\" -H \"Idempotency-Key: YOUR_UNIQUE_REQUEST_KEY\" -H 'Content-Type: application/json' --data '{\"jobId\":\"YOUR_AUDIO_JOB_ID\",\"index\":0,\"data\":\"BASE64_OF_THIS_CHUNK\"}'",
      "callbackEvents": [],
      "idempotency": "POST必须携带8–100位Idempotency-Key（字母数字、下划线、短横线、点、冒号）；同一次写入重传保持key及正文不变，不同操作/分块使用不同key，轮询advance每次使用新key。网关24小时有界响应重放；未知或过期不会重复执行。",
      "notes": [
        "响应示例仅说明结构，不代表已成功识别或质检。API Key必须绑定企业管理员并授权对应操作。",
        "单文件1–100MiB、最长7200秒、单/双声道；企业最多300个未清理任务、总声明容量2GiB；批量清单最多100项；ZIP必须平铺，解压最多100条且总量512MiB，超限、嵌套路径、重复文件名或路径穿越明确失败。",
        "清单子项支持create字段，覆盖顶层默认值；requestId省略时生成batchId-序号。清单创建可能部分成功，失败后保持原清单重放，不是全有或全无事务。",
        "ZIP模式省略manifest或传空数组，并传archive:{filename,bytes}及source/startedAt；上传archiveJob的ZIP字节并complete，随后逐条跟踪jobs或archiveChildren。archive.manifest只是元数据，不代替真实ZIP字节。",
        "uncertain为提交未知；不要自动重提。识别使用语音分钟额度，文本模型质检另计。",
        "所有角色确认且含客户后才能分析；语义模型基于转写，噪音、音量与抢话需回听原音核对。",
        "原音回放为登录态私有接口，不提供公开音频URL。本组未新增异步完成Webhook，使用read/advance接续。",
        "原音默认保留365天，可在控制台设置1–3650天；到期返回410并清理原始字节，转写、质检和复核记录仍保留。本组没有修改保留策略的公开操作。"
      ]
    },
    {
      "id": "insights-audio-complete",
      "group": "洞察与质检",
      "name": "完成录音上传",
      "method": "POST",
      "currentPath": "/api/insights-audio",
      "publicPath": "/v1/operations/insights.audio.complete",
      "actualPaths": [
        "/api/insights-audio"
      ],
      "status": "available",
      "description": "私有录音上传、异步转写、角色确认、质检及人工复核；请先阅读录音导入指南。",
      "scopes": [
        "tenant_admin",
        "reports",
        "service",
        "applications",
        "企业洞察授权",
        "insights.audio.complete"
      ],
      "request": "{\"jobId\":\"YOUR_AUDIO_JOB_ID\"}",
      "response": "{\n  \"job\": {\n    \"id\": \"YOUR_AUDIO_JOB_ID\",\n    \"status\": \"queued\"\n  }\n}",
      "requestFields": [
        {
          "name": "jobId",
          "type": "string",
          "required": true,
          "description": "当前企业录音任务ID，不可跨企业读取。"
        }
      ],
      "responseFields": [
        {
          "name": "received / conversationId / review",
          "type": "action-dependent",
          "description": "chunk返回received分块序号而非累计数；analyze首次成功返回{conversationId,status:\"completed\",accepted:false}，重复已完成requestId返回duplicate:true且可省略accepted；review直接返回完整会话及递增revision/review。结果详情请再调用read。"
        },
        {
          "name": "job",
          "type": "object",
          "description": "按分支返回任务状态、真实文件元数据、原音时长（秒）、说话人片段、usage及retentionDays/expiresAt；batch返回jobs，ZIP创建返回archiveJob，ZIP complete另含jobs；chunk/analyze/review不返回job。不暴露供应商密钥或私有任务凭证。"
        },
        {
          "name": "conversation",
          "type": "object",
          "description": "read指定jobId且转写已入库时返回会话：revision、messages、runs、review等；电话号码遵循隐私权限。"
        }
      ],
      "curl": "curl -X POST \"$YUNFU_BASE_URL/v1/operations/insights.audio.complete\" -H \"Authorization: Bearer $YUNFU_API_KEY\" -H \"Idempotency-Key: YOUR_UNIQUE_REQUEST_KEY\" -H 'Content-Type: application/json' --data '{\"jobId\":\"YOUR_AUDIO_JOB_ID\"}'",
      "callbackEvents": [],
      "idempotency": "POST必须携带8–100位Idempotency-Key（字母数字、下划线、短横线、点、冒号）；同一次写入重传保持key及正文不变，不同操作/分块使用不同key，轮询advance每次使用新key。网关24小时有界响应重放；未知或过期不会重复执行。",
      "notes": [
        "响应示例仅说明结构，不代表已成功识别或质检。API Key必须绑定企业管理员并授权对应操作。",
        "单文件1–100MiB、最长7200秒、单/双声道；企业最多300个未清理任务、总声明容量2GiB；批量清单最多100项；ZIP必须平铺，解压最多100条且总量512MiB，超限、嵌套路径、重复文件名或路径穿越明确失败。",
        "清单子项支持create字段，覆盖顶层默认值；requestId省略时生成batchId-序号。清单创建可能部分成功，失败后保持原清单重放，不是全有或全无事务。",
        "ZIP模式省略manifest或传空数组，并传archive:{filename,bytes}及source/startedAt；上传archiveJob的ZIP字节并complete，随后逐条跟踪jobs或archiveChildren。archive.manifest只是元数据，不代替真实ZIP字节。",
        "uncertain为提交未知；不要自动重提。识别使用语音分钟额度，文本模型质检另计。",
        "所有角色确认且含客户后才能分析；语义模型基于转写，噪音、音量与抢话需回听原音核对。",
        "原音回放为登录态私有接口，不提供公开音频URL。本组未新增异步完成Webhook，使用read/advance接续。",
        "原音默认保留365天，可在控制台设置1–3650天；到期返回410并清理原始字节，转写、质检和复核记录仍保留。本组没有修改保留策略的公开操作。"
      ]
    },
    {
      "id": "insights-audio-advance",
      "group": "洞察与质检",
      "name": "推进录音识别",
      "method": "POST",
      "currentPath": "/api/insights-audio",
      "publicPath": "/v1/operations/insights.audio.advance",
      "actualPaths": [
        "/api/insights-audio"
      ],
      "status": "available",
      "description": "私有录音上传、异步转写、角色确认、质检及人工复核；请先阅读录音导入指南。",
      "scopes": [
        "tenant_admin",
        "reports",
        "service",
        "applications",
        "企业洞察授权",
        "insights.audio.advance"
      ],
      "request": "{\"jobId\":\"YOUR_AUDIO_JOB_ID\"}",
      "response": "{\n  \"job\": {\n    \"id\": \"YOUR_AUDIO_JOB_ID\",\n    \"status\": \"queued\"\n  }\n}",
      "requestFields": [
        {
          "name": "jobId",
          "type": "string",
          "required": true,
          "description": "当前企业录音任务ID，不可跨企业读取。"
        }
      ],
      "responseFields": [
        {
          "name": "received / conversationId / review",
          "type": "action-dependent",
          "description": "chunk返回received分块序号而非累计数；analyze首次成功返回{conversationId,status:\"completed\",accepted:false}，重复已完成requestId返回duplicate:true且可省略accepted；review直接返回完整会话及递增revision/review。结果详情请再调用read。"
        },
        {
          "name": "job",
          "type": "object",
          "description": "按分支返回任务状态、真实文件元数据、原音时长（秒）、说话人片段、usage及retentionDays/expiresAt；batch返回jobs，ZIP创建返回archiveJob，ZIP complete另含jobs；chunk/analyze/review不返回job。不暴露供应商密钥或私有任务凭证。"
        },
        {
          "name": "conversation",
          "type": "object",
          "description": "read指定jobId且转写已入库时返回会话：revision、messages、runs、review等；电话号码遵循隐私权限。"
        }
      ],
      "curl": "curl -X POST \"$YUNFU_BASE_URL/v1/operations/insights.audio.advance\" -H \"Authorization: Bearer $YUNFU_API_KEY\" -H \"Idempotency-Key: YOUR_UNIQUE_REQUEST_KEY\" -H 'Content-Type: application/json' --data '{\"jobId\":\"YOUR_AUDIO_JOB_ID\"}'",
      "callbackEvents": [],
      "idempotency": "POST必须携带8–100位Idempotency-Key（字母数字、下划线、短横线、点、冒号）；同一次写入重传保持key及正文不变，不同操作/分块使用不同key，轮询advance每次使用新key。网关24小时有界响应重放；未知或过期不会重复执行。",
      "notes": [
        "响应示例仅说明结构，不代表已成功识别或质检。API Key必须绑定企业管理员并授权对应操作。",
        "单文件1–100MiB、最长7200秒、单/双声道；企业最多300个未清理任务、总声明容量2GiB；批量清单最多100项；ZIP必须平铺，解压最多100条且总量512MiB，超限、嵌套路径、重复文件名或路径穿越明确失败。",
        "清单子项支持create字段，覆盖顶层默认值；requestId省略时生成batchId-序号。清单创建可能部分成功，失败后保持原清单重放，不是全有或全无事务。",
        "ZIP模式省略manifest或传空数组，并传archive:{filename,bytes}及source/startedAt；上传archiveJob的ZIP字节并complete，随后逐条跟踪jobs或archiveChildren。archive.manifest只是元数据，不代替真实ZIP字节。",
        "uncertain为提交未知；不要自动重提。识别使用语音分钟额度，文本模型质检另计。",
        "所有角色确认且含客户后才能分析；语义模型基于转写，噪音、音量与抢话需回听原音核对。",
        "原音回放为登录态私有接口，不提供公开音频URL。本组未新增异步完成Webhook，使用read/advance接续。",
        "原音默认保留365天，可在控制台设置1–3650天；到期返回410并清理原始字节，转写、质检和复核记录仍保留。本组没有修改保留策略的公开操作。"
      ]
    },
    {
      "id": "insights-audio-roles",
      "group": "洞察与质检",
      "name": "确认录音说话人",
      "method": "POST",
      "currentPath": "/api/insights-audio",
      "publicPath": "/v1/operations/insights.audio.roles",
      "actualPaths": [
        "/api/insights-audio"
      ],
      "status": "available",
      "description": "私有录音上传、异步转写、角色确认、质检及人工复核；请先阅读录音导入指南。",
      "scopes": [
        "tenant_admin",
        "reports",
        "service",
        "applications",
        "企业洞察授权",
        "insights.audio.roles"
      ],
      "request": "{\"jobId\":\"YOUR_AUDIO_JOB_ID\",\"revision\":1,\"roles\":{\"channel-0-speaker-0\":\"customer\",\"channel-1-speaker-0\":\"agent\"}}",
      "response": "{\n  \"job\": {\n    \"id\": \"YOUR_AUDIO_JOB_ID\",\n    \"status\": \"queued\"\n  }\n}",
      "requestFields": [
        {
          "name": "jobId",
          "type": "string",
          "required": true,
          "description": "当前企业录音任务ID，不可跨企业读取。"
        },
        {
          "name": "revision",
          "type": "number",
          "required": true,
          "description": "查询返回的会话修订号；过期返回409，保留输入并重新读取。"
        },
        {
          "name": "roles",
          "type": "object",
          "required": true,
          "description": "对象：实际返回的segments[].speaker键映射为customer/agent/ai/unknown。不得猜测角色。"
        }
      ],
      "responseFields": [
        {
          "name": "received / conversationId / review",
          "type": "action-dependent",
          "description": "chunk返回received分块序号而非累计数；analyze首次成功返回{conversationId,status:\"completed\",accepted:false}，重复已完成requestId返回duplicate:true且可省略accepted；review直接返回完整会话及递增revision/review。结果详情请再调用read。"
        },
        {
          "name": "job",
          "type": "object",
          "description": "按分支返回任务状态、真实文件元数据、原音时长（秒）、说话人片段、usage及retentionDays/expiresAt；batch返回jobs，ZIP创建返回archiveJob，ZIP complete另含jobs；chunk/analyze/review不返回job。不暴露供应商密钥或私有任务凭证。"
        },
        {
          "name": "conversation",
          "type": "object",
          "description": "read指定jobId且转写已入库时返回会话：revision、messages、runs、review等；电话号码遵循隐私权限。"
        }
      ],
      "curl": "curl -X POST \"$YUNFU_BASE_URL/v1/operations/insights.audio.roles\" -H \"Authorization: Bearer $YUNFU_API_KEY\" -H \"Idempotency-Key: YOUR_UNIQUE_REQUEST_KEY\" -H 'Content-Type: application/json' --data '{\"jobId\":\"YOUR_AUDIO_JOB_ID\",\"revision\":1,\"roles\":{\"channel-0-speaker-0\":\"customer\",\"channel-1-speaker-0\":\"agent\"}}'",
      "callbackEvents": [],
      "idempotency": "POST必须携带8–100位Idempotency-Key（字母数字、下划线、短横线、点、冒号）；同一次写入重传保持key及正文不变，不同操作/分块使用不同key，轮询advance每次使用新key。网关24小时有界响应重放；未知或过期不会重复执行。",
      "notes": [
        "响应示例仅说明结构，不代表已成功识别或质检。API Key必须绑定企业管理员并授权对应操作。",
        "单文件1–100MiB、最长7200秒、单/双声道；企业最多300个未清理任务、总声明容量2GiB；批量清单最多100项；ZIP必须平铺，解压最多100条且总量512MiB，超限、嵌套路径、重复文件名或路径穿越明确失败。",
        "清单子项支持create字段，覆盖顶层默认值；requestId省略时生成batchId-序号。清单创建可能部分成功，失败后保持原清单重放，不是全有或全无事务。",
        "ZIP模式省略manifest或传空数组，并传archive:{filename,bytes}及source/startedAt；上传archiveJob的ZIP字节并complete，随后逐条跟踪jobs或archiveChildren。archive.manifest只是元数据，不代替真实ZIP字节。",
        "uncertain为提交未知；不要自动重提。识别使用语音分钟额度，文本模型质检另计。",
        "所有角色确认且含客户后才能分析；语义模型基于转写，噪音、音量与抢话需回听原音核对。",
        "原音回放为登录态私有接口，不提供公开音频URL。本组未新增异步完成Webhook，使用read/advance接续。",
        "原音默认保留365天，可在控制台设置1–3650天；到期返回410并清理原始字节，转写、质检和复核记录仍保留。本组没有修改保留策略的公开操作。"
      ]
    },
    {
      "id": "insights-audio-retry",
      "group": "洞察与质检",
      "name": "确认重试录音识别",
      "method": "POST",
      "currentPath": "/api/insights-audio",
      "publicPath": "/v1/operations/insights.audio.retry",
      "actualPaths": [
        "/api/insights-audio"
      ],
      "status": "available",
      "description": "私有录音上传、异步转写、角色确认、质检及人工复核；请先阅读录音导入指南。",
      "scopes": [
        "tenant_admin",
        "reports",
        "service",
        "applications",
        "企业洞察授权",
        "insights.audio.retry"
      ],
      "request": "{\"jobId\":\"YOUR_AUDIO_JOB_ID\",\"confirmProviderRetry\":true}",
      "response": "{\n  \"job\": {\n    \"id\": \"YOUR_AUDIO_JOB_ID\",\n    \"status\": \"queued\"\n  }\n}",
      "requestFields": [
        {
          "name": "jobId",
          "type": "string",
          "required": true,
          "description": "当前企业录音任务ID，不可跨企业读取。"
        },
        {
          "name": "confirmProviderRetry",
          "type": "boolean",
          "required": true,
          "description": "必须为true；先核对供应商任务及费用，未知提交不会自动退款或重提。"
        },
        {
          "name": "asrResourceId",
          "type": "string",
          "required": false,
          "description": "已授权的独立洞察 ASR 或复用语音 ASR 资源 ID；仅一个独立资源时优先使用，多个独立资源必须明确选择。"
        },
        {
          "name": "asrModel",
          "type": "string",
          "required": false,
          "description": "fun-asr或qwen-audio-3.1-asr-flash-filetrans；省略时使用独立资源的默认模型。"
        }
      ],
      "responseFields": [
        {
          "name": "received / conversationId / review",
          "type": "action-dependent",
          "description": "chunk返回received分块序号而非累计数；analyze首次成功返回{conversationId,status:\"completed\",accepted:false}，重复已完成requestId返回duplicate:true且可省略accepted；review直接返回完整会话及递增revision/review。结果详情请再调用read。"
        },
        {
          "name": "job",
          "type": "object",
          "description": "按分支返回任务状态、真实文件元数据、原音时长（秒）、说话人片段、usage及retentionDays/expiresAt；batch返回jobs，ZIP创建返回archiveJob，ZIP complete另含jobs；chunk/analyze/review不返回job。不暴露供应商密钥或私有任务凭证。"
        },
        {
          "name": "conversation",
          "type": "object",
          "description": "read指定jobId且转写已入库时返回会话：revision、messages、runs、review等；电话号码遵循隐私权限。"
        }
      ],
      "curl": "curl -X POST \"$YUNFU_BASE_URL/v1/operations/insights.audio.retry\" -H \"Authorization: Bearer $YUNFU_API_KEY\" -H \"Idempotency-Key: YOUR_UNIQUE_REQUEST_KEY\" -H 'Content-Type: application/json' --data '{\"jobId\":\"YOUR_AUDIO_JOB_ID\",\"confirmProviderRetry\":true}'",
      "callbackEvents": [],
      "idempotency": "POST必须携带8–100位Idempotency-Key（字母数字、下划线、短横线、点、冒号）；同一次写入重传保持key及正文不变，不同操作/分块使用不同key，轮询advance每次使用新key。网关24小时有界响应重放；未知或过期不会重复执行。",
      "notes": [
        "响应示例仅说明结构，不代表已成功识别或质检。API Key必须绑定企业管理员并授权对应操作。",
        "单文件1–100MiB、最长7200秒、单/双声道；企业最多300个未清理任务、总声明容量2GiB；批量清单最多100项；ZIP必须平铺，解压最多100条且总量512MiB，超限、嵌套路径、重复文件名或路径穿越明确失败。",
        "清单子项支持create字段，覆盖顶层默认值；requestId省略时生成batchId-序号。清单创建可能部分成功，失败后保持原清单重放，不是全有或全无事务。",
        "ZIP模式省略manifest或传空数组，并传archive:{filename,bytes}及source/startedAt；上传archiveJob的ZIP字节并complete，随后逐条跟踪jobs或archiveChildren。archive.manifest只是元数据，不代替真实ZIP字节。",
        "uncertain为提交未知；不要自动重提。识别使用语音分钟额度，文本模型质检另计。",
        "所有角色确认且含客户后才能分析；语义模型基于转写，噪音、音量与抢话需回听原音核对。",
        "原音回放为登录态私有接口，不提供公开音频URL。本组未新增异步完成Webhook，使用read/advance接续。",
        "原音默认保留365天，可在控制台设置1–3650天；到期返回410并清理原始字节，转写、质检和复核记录仍保留。本组没有修改保留策略的公开操作。"
      ]
    },
    {
      "id": "insights-audio-analyze",
      "group": "洞察与质检",
      "name": "执行录音质检",
      "method": "POST",
      "currentPath": "/api/insights-audio",
      "publicPath": "/v1/operations/insights.audio.analyze",
      "actualPaths": [
        "/api/insights-audio"
      ],
      "status": "available",
      "description": "私有录音上传、异步转写、角色确认、质检及人工复核；请先阅读录音导入指南。",
      "scopes": [
        "tenant_admin",
        "reports",
        "service",
        "applications",
        "企业洞察授权",
        "insights.audio.analyze"
      ],
      "request": "{\"jobId\":\"YOUR_AUDIO_JOB_ID\",\"revision\":2,\"requestId\":\"YOUR_ANALYSIS_REQUEST_ID\",\"engine\":\"model\",\"planMode\":\"latest\"}",
      "response": "{\n  \"conversationId\": \"YOUR_CONVERSATION_ID\",\n  \"status\": \"completed\",\n  \"accepted\": false\n}",
      "requestFields": [
        {
          "name": "jobId",
          "type": "string",
          "required": true,
          "description": "当前企业录音任务ID，不可跨企业读取。"
        },
        {
          "name": "revision",
          "type": "number",
          "required": true,
          "description": "查询返回的会话修订号；过期返回409，保留输入并重新读取。"
        },
        {
          "name": "requestId",
          "type": "string",
          "required": true,
          "description": "本次分析独立请求编号；结果未知时先读取既有运行回执。"
        },
        {
          "name": "engine",
          "type": "string",
          "required": true,
          "description": "model使用配置模型；local仅执行本地字面规则，不代表模型语义质检。"
        },
        {
          "name": "planMode",
          "type": "string",
          "required": true,
          "description": "bound使用已绑定方案；latest使用当前发布方案。"
        },
        {
          "name": "planId",
          "type": "string",
          "required": false,
          "description": "可选已发布方案ID；bound且会话已有execution时忽略；否则选择指定方案，省略时使用原方案或服务端可用默认方案。"
        }
      ],
      "responseFields": [
        {
          "name": "received / conversationId / review",
          "type": "action-dependent",
          "description": "chunk返回received分块序号而非累计数；analyze首次成功返回{conversationId,status:\"completed\",accepted:false}，重复已完成requestId返回duplicate:true且可省略accepted；review直接返回完整会话及递增revision/review。结果详情请再调用read。"
        },
        {
          "name": "job",
          "type": "object",
          "description": "按分支返回任务状态、真实文件元数据、原音时长（秒）、说话人片段、usage及retentionDays/expiresAt；batch返回jobs，ZIP创建返回archiveJob，ZIP complete另含jobs；chunk/analyze/review不返回job。不暴露供应商密钥或私有任务凭证。"
        },
        {
          "name": "conversation",
          "type": "object",
          "description": "read指定jobId且转写已入库时返回会话：revision、messages、runs、review等；电话号码遵循隐私权限。"
        }
      ],
      "curl": "curl -X POST \"$YUNFU_BASE_URL/v1/operations/insights.audio.analyze\" -H \"Authorization: Bearer $YUNFU_API_KEY\" -H \"Idempotency-Key: YOUR_UNIQUE_REQUEST_KEY\" -H 'Content-Type: application/json' --data '{\"jobId\":\"YOUR_AUDIO_JOB_ID\",\"revision\":2,\"requestId\":\"YOUR_ANALYSIS_REQUEST_ID\",\"engine\":\"model\",\"planMode\":\"latest\"}'",
      "callbackEvents": [],
      "idempotency": "POST必须携带8–100位Idempotency-Key（字母数字、下划线、短横线、点、冒号）；同一次写入重传保持key及正文不变，不同操作/分块使用不同key，轮询advance每次使用新key。网关24小时有界响应重放；未知或过期不会重复执行。",
      "notes": [
        "响应示例仅说明结构，不代表已成功识别或质检。API Key必须绑定企业管理员并授权对应操作。",
        "单文件1–100MiB、最长7200秒、单/双声道；企业最多300个未清理任务、总声明容量2GiB；批量清单最多100项；ZIP必须平铺，解压最多100条且总量512MiB，超限、嵌套路径、重复文件名或路径穿越明确失败。",
        "清单子项支持create字段，覆盖顶层默认值；requestId省略时生成batchId-序号。清单创建可能部分成功，失败后保持原清单重放，不是全有或全无事务。",
        "ZIP模式省略manifest或传空数组，并传archive:{filename,bytes}及source/startedAt；上传archiveJob的ZIP字节并complete，随后逐条跟踪jobs或archiveChildren。archive.manifest只是元数据，不代替真实ZIP字节。",
        "uncertain为提交未知；不要自动重提。识别使用语音分钟额度，文本模型质检另计。",
        "所有角色确认且含客户后才能分析；语义模型基于转写，噪音、音量与抢话需回听原音核对。",
        "原音回放为登录态私有接口，不提供公开音频URL。本组未新增异步完成Webhook，使用read/advance接续。",
        "原音默认保留365天，可在控制台设置1–3650天；到期返回410并清理原始字节，转写、质检和复核记录仍保留。本组没有修改保留策略的公开操作。"
      ]
    },
    {
      "id": "insights-audio-review",
      "group": "洞察与质检",
      "name": "人工复核录音质检",
      "method": "POST",
      "currentPath": "/api/insights-audio",
      "publicPath": "/v1/operations/insights.audio.review",
      "actualPaths": [
        "/api/insights-audio"
      ],
      "status": "available",
      "description": "私有录音上传、异步转写、角色确认、质检及人工复核；请先阅读录音导入指南。",
      "scopes": [
        "tenant_admin",
        "reports",
        "service",
        "applications",
        "企业洞察授权",
        "insights.audio.review"
      ],
      "request": "{\"jobId\":\"YOUR_AUDIO_JOB_ID\",\"revision\":3,\"score\":80,\"reason\":\"已逐段核对原始录音与质检证据，现确认人工评分。\"}",
      "response": "{\n  \"id\": \"YOUR_CONVERSATION_ID\",\n  \"revision\": 4,\n  \"review\": {\n    \"score\": 80,\n    \"reason\": \"人工复核依据\",\n    \"at\": \"2026-10-17T09:30:00+08:00\"\n  }\n}",
      "requestFields": [
        {
          "name": "jobId",
          "type": "string",
          "required": true,
          "description": "当前企业录音任务ID，不可跨企业读取。"
        },
        {
          "name": "revision",
          "type": "number",
          "required": true,
          "description": "查询返回的会话修订号；过期返回409，保留输入并重新读取。"
        },
        {
          "name": "score",
          "type": "number",
          "required": true,
          "description": "人工复核分数0–100；不覆盖模型原结论。"
        },
        {
          "name": "reason",
          "type": "string",
          "required": true,
          "description": "人工复核依据，1–3000 字。"
        }
      ],
      "responseFields": [
        {
          "name": "received / conversationId / review",
          "type": "action-dependent",
          "description": "chunk返回received分块序号而非累计数；analyze首次成功返回{conversationId,status:\"completed\",accepted:false}，重复已完成requestId返回duplicate:true且可省略accepted；review直接返回完整会话及递增revision/review。结果详情请再调用read。"
        },
        {
          "name": "job",
          "type": "object",
          "description": "按分支返回任务状态、真实文件元数据、原音时长（秒）、说话人片段、usage及retentionDays/expiresAt；batch返回jobs，ZIP创建返回archiveJob，ZIP complete另含jobs；chunk/analyze/review不返回job。不暴露供应商密钥或私有任务凭证。"
        },
        {
          "name": "conversation",
          "type": "object",
          "description": "read指定jobId且转写已入库时返回会话：revision、messages、runs、review等；电话号码遵循隐私权限。"
        }
      ],
      "curl": "curl -X POST \"$YUNFU_BASE_URL/v1/operations/insights.audio.review\" -H \"Authorization: Bearer $YUNFU_API_KEY\" -H \"Idempotency-Key: YOUR_UNIQUE_REQUEST_KEY\" -H 'Content-Type: application/json' --data '{\"jobId\":\"YOUR_AUDIO_JOB_ID\",\"revision\":3,\"score\":80,\"reason\":\"已逐段核对原始录音与质检证据，现确认人工评分。\"}'",
      "callbackEvents": [],
      "idempotency": "POST必须携带8–100位Idempotency-Key（字母数字、下划线、短横线、点、冒号）；同一次写入重传保持key及正文不变，不同操作/分块使用不同key，轮询advance每次使用新key。网关24小时有界响应重放；未知或过期不会重复执行。",
      "notes": [
        "响应示例仅说明结构，不代表已成功识别或质检。API Key必须绑定企业管理员并授权对应操作。",
        "单文件1–100MiB、最长7200秒、单/双声道；企业最多300个未清理任务、总声明容量2GiB；批量清单最多100项；ZIP必须平铺，解压最多100条且总量512MiB，超限、嵌套路径、重复文件名或路径穿越明确失败。",
        "清单子项支持create字段，覆盖顶层默认值；requestId省略时生成batchId-序号。清单创建可能部分成功，失败后保持原清单重放，不是全有或全无事务。",
        "ZIP模式省略manifest或传空数组，并传archive:{filename,bytes}及source/startedAt；上传archiveJob的ZIP字节并complete，随后逐条跟踪jobs或archiveChildren。archive.manifest只是元数据，不代替真实ZIP字节。",
        "uncertain为提交未知；不要自动重提。识别使用语音分钟额度，文本模型质检另计。",
        "所有角色确认且含客户后才能分析；语义模型基于转写，噪音、音量与抢话需回听原音核对。",
        "原音回放为登录态私有接口，不提供公开音频URL。本组未新增异步完成Webhook，使用read/advance接续。",
        "原音默认保留365天，可在控制台设置1–3650天；到期返回410并清理原始字节，转写、质检和复核记录仍保留。本组没有修改保留策略的公开操作。"
      ]
    },
    {
      "group": "洞察与质检",
      "currentPath": "/api/insights-import",
      "actualPaths": [
        "/api/insights-import"
      ],
      "status": "available",
      "callbackEvents": [],
      "notes": [
        "仅导入调用方已合法持有并获授权处理的明文会话；企业微信会话专区的明文提取须使用其专用授权链路。本接口不提取企业微信明文。",
        "企业须已开通洞察；API Key绑定企业管理员，账号同时具有reports、service、applications权限，密钥逐项授权本操作。企业及归属由服务端确定。",
        "导入不调用ASR或文本模型，不自动启动分析，不产生供应商调用费用；analysisStarted始终为false。需要分析时在洞察控制台明确发起。",
        "严格按字段契约提交：请求、会话和消息对象中的未知字段都会被拒绝；查询只接受externalId，不接受其他参数。"
      ],
      "id": "insights-conversations-import",
      "name": "导入标准会话",
      "method": "POST",
      "publicPath": "/v1/operations/insights.conversations.import",
      "description": "整批原子导入1–50条已有明文会话，以稳定externalId识别重复与更新；不自动分析。",
      "scopes": [
        "tenant_admin",
        "reports",
        "service",
        "applications",
        "企业洞察授权",
        "insights.conversations.import"
      ],
      "request": "{\n  \"records\": [\n    {\n      \"externalId\": \"wecom-demo-001\",\n      \"source\": \"企业微信授权会话\",\n      \"title\": \"退款咨询（演示）\",\n      \"startedAt\": \"2026-10-20T09:00:00+08:00\",\n      \"demo\": true,\n      \"messages\": [\n        {\n          \"id\": \"m1\",\n          \"role\": \"customer\",\n          \"speaker\": \"客户\",\n          \"text\": \"退款什么时候到账？\",\n          \"sentAt\": \"2026-10-20T09:00:00+08:00\"\n        },\n        {\n          \"id\": \"m2\",\n          \"role\": \"agent\",\n          \"speaker\": \"客服\",\n          \"text\": \"我会核对退款进度并向您反馈。\",\n          \"sentAt\": \"2026-10-20T09:01:00+08:00\"\n        }\n      ]\n    }\n  ]\n}",
      "response": "{\n  \"results\": [\n    {\n      \"externalId\": \"wecom-demo-001\",\n      \"conversationId\": \"YOUR_CONVERSATION_ID\",\n      \"revision\": 1,\n      \"status\": \"created\",\n      \"messageCount\": 2\n    }\n  ],\n  \"created\": 1,\n  \"updated\": 0,\n  \"unchanged\": 0,\n  \"analysisStarted\": false\n}",
      "requestFields": [
        {
          "name": "records",
          "type": "array",
          "description": "1–50条会话；整份JSON正文最多150000字节。任意一项无效或冲突则整批不写入。",
          "required": true
        },
        {
          "name": "records[].externalId",
          "type": "string",
          "description": "稳定的外部会话标识，1–100字符；同一企业内识别既有导入，不是幂等请求键。",
          "required": true
        },
        {
          "name": "records[].source",
          "type": "string",
          "description": "来源，1–80字符；不授予读取外部平台数据的权限。",
          "required": true
        },
        {
          "name": "records[].title",
          "type": "string",
          "description": "可选标题；提供时为1–200字符。",
          "required": false
        },
        {
          "name": "records[].startedAt",
          "type": "string",
          "description": "会话开始时间，必须为带时区ISO时间。",
          "required": true
        },
        {
          "name": "records[].duration",
          "type": "number",
          "description": "可选会话时长，单位为秒，必须覆盖所有消息起止偏移。",
          "required": false
        },
        {
          "name": "records[].demo",
          "type": "boolean",
          "description": "可选演示数据标记。",
          "required": false
        },
        {
          "name": "records[].revision",
          "type": "integer",
          "description": "修改既有会话时必填，使用insights.conversations.read返回的最新revision；遗漏或过期返回409。内容规范化后相同返回unchanged。",
          "required": false
        },
        {
          "name": "records[].messages",
          "type": "array",
          "description": "每条会话1–1000条消息，按会话顺序提交。",
          "required": true
        },
        {
          "name": "records[].messages[].id",
          "type": "string",
          "description": "可选外部消息标识，1–200字符。",
          "required": false
        },
        {
          "name": "records[].messages[].role",
          "type": "string",
          "description": "customer、agent、ai或unknown；unknown保留待确认角色。",
          "required": true
        },
        {
          "name": "records[].messages[].speaker",
          "type": "string",
          "description": "可选说话人名称，1–200字符。",
          "required": false
        },
        {
          "name": "records[].messages[].text",
          "type": "string",
          "description": "已获授权的消息明文，1–10000字符，不能只有空白。",
          "required": true
        },
        {
          "name": "records[].messages[].sentAt",
          "type": "string",
          "description": "可选消息时间；提供时必须为带时区ISO时间。",
          "required": false
        },
        {
          "name": "records[].messages[].seconds / endSeconds",
          "type": "number",
          "description": "可选消息起止偏移，单位为秒；endSeconds必须大于等于seconds（缺省为0）。",
          "required": false
        }
      ],
      "responseFields": [
        {
          "name": "results[]",
          "type": "object",
          "description": "每条包含externalId、conversationId、revision、status与messageCount；status为created、updated或unchanged。",
          "required": true
        },
        {
          "name": "created / updated / unchanged",
          "type": "integer",
          "description": "本批新建、更新、无变化的会话数量。",
          "required": true
        },
        {
          "name": "analysisStarted",
          "type": "boolean",
          "description": "固定false；已保存不代表已分析。",
          "required": true
        }
      ],
      "curl": "curl --fail-with-body \"$YUNFU_BASE_URL/v1/operations/insights.conversations.import\" \\\n  -H \"Authorization: Bearer $YUNFU_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: wecom-demo-import-001\" \\\n  --data-binary @insights-api-import.json",
      "idempotency": "POST必须携带8–100位Idempotency-Key。同键同请求只重放结果，同键不同内容返回409。externalId另行保证业务级去重；修改内容使用新请求键及最新revision。"
    },
    {
      "group": "洞察与质检",
      "currentPath": "/api/insights-import",
      "actualPaths": [
        "/api/insights-import"
      ],
      "status": "available",
      "callbackEvents": [],
      "notes": [
        "仅导入调用方已合法持有并获授权处理的明文会话；企业微信会话专区的明文提取须使用其专用授权链路。本接口不提取企业微信明文。",
        "企业须已开通洞察；API Key绑定企业管理员，账号同时具有reports、service、applications权限，密钥逐项授权本操作。企业及归属由服务端确定。",
        "导入不调用ASR或文本模型，不自动启动分析，不产生供应商调用费用；analysisStarted始终为false。需要分析时在洞察控制台明确发起。",
        "严格按字段契约提交：请求、会话和消息对象中的未知字段都会被拒绝；查询只接受externalId，不接受其他参数。"
      ],
      "id": "insights-conversations-read",
      "name": "查询标准会话导入回执",
      "method": "GET",
      "publicPath": "/v1/operations/insights.conversations.read",
      "description": "按externalId查询当前企业已导入会话的元数据和最新revision，供更新或未知结果核对；不返回明文消息。",
      "scopes": [
        "tenant_admin",
        "reports",
        "service",
        "applications",
        "企业洞察授权",
        "insights.conversations.read"
      ],
      "request": "?externalId=wecom-demo-001",
      "response": "{\n  \"record\": {\n    \"externalId\": \"wecom-demo-001\",\n    \"conversationId\": \"YOUR_CONVERSATION_ID\",\n    \"revision\": 1,\n    \"source\": \"企业微信授权会话\",\n    \"title\": \"退款咨询（演示）\",\n    \"startedAt\": \"2026-10-20T09:00:00+08:00\",\n    \"messageCount\": 2,\n    \"resultStatus\": \"stale\"\n  }\n}",
      "requestFields": [
        {
          "name": "externalId (query)",
          "type": "string",
          "description": "必填，1–100字符，使用原导入的稳定externalId；不存在或不属于当前企业返回404。",
          "required": true
        }
      ],
      "responseFields": [
        {
          "name": "record",
          "type": "object",
          "description": "包含externalId、conversationId、revision、source、title、startedAt、messageCount与resultStatus；仅返回元数据，不含messages明文。",
          "required": true
        },
        {
          "name": "record.revision",
          "type": "integer",
          "description": "修改导入时传回的最新会话修订号。",
          "required": true
        },
        {
          "name": "record.resultStatus",
          "type": "string",
          "description": "stale表示尚未分析或内容变化后待重新分析；current表示已有当前结果。导入不会自动把结果置为current。",
          "required": true
        }
      ],
      "curl": "curl --fail-with-body --get \"$YUNFU_BASE_URL/v1/operations/insights.conversations.read\" \\\n  -H \"Authorization: Bearer $YUNFU_API_KEY\" \\\n  --data-urlencode \"externalId=wecom-demo-001\"",
      "idempotency": "只读请求不要求Idempotency-Key。查询不会重新导入或启动分析。"
    }
  ]
}