阿里云视频理解API的PHP调用必须使用OpenAPI V3签名及官方SDK，上传需先调CreateUploadVideo获取VideoId再提交分析任务，结果需轮询获取且标签摘要位于Response.Data.Result下。
阿里云视频理解 API 的 PHP 调用必须走 OpenAPI V3 签名
阿里云所有 AI 类服务（包括 video_analysis）在 2023 年底已全面下线旧版签名方式，PHP 直接拼 AccessKeyId + AccessKeySecret 到 URL 或 header 会稳定返回 InvalidAccessKeyId.NotFound 或 SignatureDoesNotMatch。这不是权限问题，是签名算法不兼容。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 必须使用阿里云官方 SDK：
alibabacloud/tea-openapi和alibabacloud/viapi20230117（注意不是aliyun-php-sdk-xxx那套老包） - 不要自己实现 HMAC-SHA256 签名 —— OpenAPI V3 的 canonicalized headers、query string 排序、body hash 规则极容易出错
- 上传视频必须先调用
CreateUploadVideo获取临时上传地址，不能直接 POST 视频文件到分析接口
PHP 提交视频分析任务前要处理好文件路径和格式
常见错误是传入本地路径如 /var/www/html/test.mp4，但阿里云接口根本不接收本地文件系统路径 —— 它只认 OSS URL 或上传后返回的 VideoId。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 用
CreateUploadVideo获取上传凭证后，用cURL或GuzzleHttp\Client向返回的UploadAddress发起 PUT 请求上传（注意设置Content-Type为视频 MIME 类型，如video/mp4） - 上传成功后拿到
VideoId，再调用SubmitVideoAnalysisJob，参数里填的是这个VideoId，不是文件名或 URL - 视频时长建议控制在 5 分钟内；超长视频可能触发
JobQuotaExceeded，需检查配额或分段提交
获取分析结果时别卡在轮询逻辑里
阿里云不支持“同步返回结果”，SubmitVideoAnalysisJob 只返回一个 JobId，后续必须主动轮询 GetVideoAnalysisJobResult。很多人写个死循环每秒查一次，结果被限流或超时。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 首次提交后等待至少 3 秒再开始轮询，避免服务端 job 还没初始化完
- 推荐指数退避：第 1 次等 2s，第 2 次等 4s，第 3 次等 8s，最多查 10 次（约 200 秒），超过就判定失败
- 检查返回的
Status字段：只有Succeed才表示完成；Running继续等，Failed要读ErrorMessage（比如VideoFormatNotSupported）
标签和摘要字段藏在嵌套 JSON 里，不是顶层 key
很多人调通接口后发现返回数据里没有 tags 或 summary，其实它们在 Response.Data.Result 下的深层结构中，且字段名随模型版本变化 —— 当前主流返回结构是 Response.Data.Result.Tags（数组）和 Response.Data.Result.Summary（字符串）。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 别直接
json_decode($res, true)['tags']—— 先确认Response.Data.Result存在，再取子键 - 标签置信度阈值默认是 0.5，如果想拿更多低置信标签，提交时加参数
TagThreshold: 0.3 - 摘要长度不可控，但可通过
SummaryLength参数指定（单位：字数），范围 50–300，超出会被截断
最易被忽略的一点：阿里云视频理解服务对中文语音识别依赖音频轨道质量，如果视频只有画面无声音，Summary 可能为空或极短 —— 不是代码问题，是输入本身缺失关键模态信息。
