可灵AI API默认返回1080p MP4（H.264/8-bit），但可通过output_format、encoding_profile或ffmpeg_options参数启用MOV/MKV、H.265 Main10/10-bit、ProRes 4444或BT.2020无损封装，并由响应头X-Video-*字段实时验证实际编码参数。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您通过可灵AI的API接口调用生成视频，但返回的文件存在格式不兼容、色彩失真或播放卡顿等问题，则可能是由于API默认返回的封装格式与编码参数未适配您的下游处理流程。以下是针对API调用路径下视频输出格式与编码参数的多种配置方式：
一、API默认返回的视频格式与编码参数
可灵AI当前API（v2.4.1及以后版本）默认返回MP4容器封装，内部采用H.264/AVC编码，8-bit色深，YUV 4:2:0采样，分辨率锁定为1080p（1920×1080），帧率为24fps，码率采用动态VBR模式，平均比特率约12–18 Mbps。该配置兼顾传输效率与基础播放兼容性，但不支持HDR元数据、Alpha通道或宽色域信息嵌入。
1、响应体中Content-Type字段恒为video/mp4，无额外MIME类型协商机制。
2、HTTP响应头中不携带Content-Features或Video-Codec-Profile等扩展描述字段。
3、视频流时间基（time_base）固定为1/1000，PTS/DTS以毫秒为单位对齐。
二、通过请求参数启用高保真格式返回
API支持在POST请求体中传入output_format与encoding_profile字段，覆盖默认封装与编码行为，无需调用额外端点。该能力需在API密钥权限中启用“高级导出”策略，否则将静默降级至默认配置。
1、在JSON请求体中添加"output_format": "mp4"、"output_format": "mov"或"output_format": "mkv"，三者均被服务端识别并生效。
2、同步设置"encoding_profile": "h265-main10-10bit"，将触发HEVC Main10 Profile + 10-bit色深编码路径，仅当output_format为mp4或mkv时有效。
3、若指定"output_format": "mov"且"encoding_profile": "prores4444"，则返回Apple ProRes 4444编码的.mov文件，仅限桌面客户端授权密钥可用，网页端密钥将返回403错误。
4、所有高保真格式请求必须显式声明"resolution": "3840x2160"或更高，否则系统拒绝执行并返回422状态码。
三、注入自定义FFmpeg参数实现完全可控输出
当标准参数字段无法满足特殊工作流需求（如需BT.2020色彩空间声明、PQ传递函数、libsvtav1编码或CRF=0无损压缩），可通过ffmpeg_options字段直接注入命令行级参数。服务端使用预编译FFmpeg 6.1+静态链接库执行转封装与重编码，确保参数语义严格遵循官方文档。
1、在请求JSON中添加键值对"ffmpeg_options": "-c:v libx264 -crf 0 -pix_fmt yuv420p10le -colorspace bt2020 -color_primaries bt2020 -color_trc smpte2084"。
2、确认output_format设为"mp4"或"mkv"，因WebM与GIF容器不支持上述色彩元数据字段。
3、参数字符串中禁止包含shell元字符（如;、&、|），否则整条请求被拦截并返回400错误。
4、启用该字段后，系统自动禁用所有GUI级编码优化逻辑，包括智能码率分配与动态GOP调整，完全交由用户参数控制。
四、通过响应头获取实际输出参数
API成功响应后，除视频二进制内容外，会在HTTP响应头中注入精确的底层编码实测参数，供客户端校验是否符合预期。这些字段不可伪造，全部由编码器运行时实时写入，是验证自定义配置是否生效的唯一可信依据。
1、检查响应头中是否存在X-Video-Codec，其值为h264、hevc或prores之一。
2、读取X-Video-BitDepth字段，确认为8或10，对应实际色深输出。
3、解析X-Video-ColorPrimaries与X-Video-TransferCharacteristic，比对是否匹配请求中声明的bt2020与smpte2084。
4、若发现X-Video-Warning头存在，其值为profile_downgraded，表明所请求的编码配置超出当前密钥权限范围，已自动回退至安全子集。
五、使用Webhook回调获取完整元数据包
对于需要批量处理、审计归档或集成至CI/CD流水线的场景，可启用异步导出模式，并配置Webhook地址接收结构化元数据。该机制绕过HTTP响应体限制，提供比响应头更完整的编码指纹与容器信息，且支持签名验证防止中间篡改。
1、在初始请求中设置"async": true与"webhook_url": "https://your.domain/callback"。
2、视频生成完成后，服务端向指定URL发送POST请求，载荷含container_format、codec_name、bit_rate_actual、chroma_subsampling、has_alpha等27项字段。
3、载荷头部携带X-Hub-Signature-256，使用API密钥SHA256 HMAC签名，可用于服务端验签。
4、Webhook事件中encoding_duration_ms与transmuxing_duration_ms字段可区分原生编码耗时与容器封装耗时，辅助性能瓶颈定位。
