上传和读取素材
上传输入文件或直接提供公网 URL，并使用原调用身份读取输出。
输入素材有两种提供方式：先上传得到素材 ID，或在创建请求里直接给公网 HTTPS 地址。两者按槽位二选一。
直接使用公网 URL
图像、视频、音频生成与文档 OCR、解析接口里，每个素材 ID 字段都有并列的 URL 字段：单个 *_asset_id 对应 *_url，数组 *_asset_ids 对应 *_urls；H3 全能参考的 referenceInputs[] 每行用 url 代替 assetId。
{"model":"<MODEL_ALIAS>","generationMode":"i2v","prompt":"镜头缓慢推进","input_image_url":"https://example.com/first.png","resolutionTier":"768p","orientation":"landscape","seconds":5}| 规则 | 内容 |
|---|---|
| 地址 | 只接受公网 HTTPS；图片槽位另接受 data:image/... |
| 处理 | 平台下载并按与上传相同的格式、大小、时长与角色限制校验，作为本次请求的一小时临时素材，不进入“我的资源” |
| 冲突 | 同一槽位同时给 ID 与 URL 返回 400 ambiguous_input_source |
| 失败 | invalid_source_url（地址不合规）、source_fetch_failed、source_fetch_timeout（下载失败或超时），修正地址或改用上传 |
同一请求重复出现的 URL 只下载一次。素材需要在多个任务间复用，或源站不允许平台访问时，仍先上传再引用 ID。
上传输入
POST /assets/input 使用 multipart，查询参数 model 必填。图片、视频和音频按服务合同选择 image、video、audio 字段；通用文件和文档使用 file。不要用 JSON 编码原始二进制。
curl --fail-with-body --max-time 120 \
"$JUSP_BASE_URL/assets/input?model=$JUSP_MODEL" \
-H "Authorization: Bearer $JUSP_API_KEY" -F 'image=@reference.png'示例中的模型别名由平台提供；自己拼接查询参数时应 URL 编码。成功响应读取 asset.assetId，不是顶层 assetId。上传不等于启动模型生成。
保留素材边界
支持格式、字节大小、像素、时长和素材数量由目标模型及模式决定。提交前根据模型详情校验；不得通过改扩展名绕过格式限制。
文件大小与媒体时长是独立条件，不能按字节数推算秒数；压缩率和码率都会影响文件大小。H3 的各角色素材限制同时适用于 V1 上传后的任务与 V2 外部素材摄入。规格发现可读取 GET /v1/services 对应模型的 mediaSpecContract.inputAssets.roleLimits，按 generationMode 和 role 匹配。
H3 图片上传尚未指定首帧、尾帧或参考图角色时，按支持角色的通用安全上限做暂存准入；创建、估价和实际使用仍按所选角色重新校验。例如，长边6000像素且符合其他首帧限制的图片可以暂存并用作首帧，但超过参考图的5760像素上限，不能用作 reference_image。上传成功不代表适用于所有角色。
输入素材通常是临时资源，应读取响应的有效期，不把它当永久文件仓库。API 上传素材与 Portal“我的资源”上传列表不等价；不要假定任何可见资源 ID 都能跨模型、跨身份使用。
H3 全能参考中的音频使用 audio 字段；包含音轨的 MOV 作为音频参考时同样按音频身份上传，不消耗视频参考名额。上传身份不保证任意编码都可解码。
上传失败时保留具体原因
上传接口返回非2xx时，先保存原始 HTTP 状态、响应 JSON 的 error.code、error.message、error.requestId（或顶层 requestId）及 X-Request-ID。不要只记录“上传失败”或把上游400统一转成502后丢弃原始原因。V2 创建请求使用自己的错误格式：保留 error.code、error.message 和顶层 request_id。
400通常表示素材或请求未满足合同，例如视频时长越界、宽高比越界、格式与实际内容不符或无法解析；413表示请求或文件过大；415表示媒体格式不受支持。以本次响应的具体原因判断，修正素材后再提交，不对同一无效素材循环重试。文件很小也可能超过时长上限，改扩展名或 Content-Type 不能修复实际容器或编码问题。
向平台排查时提供请求时间、模型、原始状态、错误码、错误消息和请求追踪号；可附已移除 Authorization 的请求结构及不含私人内容的素材元信息。不要提供 API Key、签名 URL 或原始私人素材。若响应正文没有保留，请先提供请求追踪号，平台会依据可用日志核查；不能仅凭HTTP状态或响应字节数确定具体原因。
下载生成结果
任务成功后优先读取 outputs[].contentUrl，携带创建任务的同一 API Key。原样 URL 默认返回无可见水印的 source；只有显式追加 deliveryMode=marked 才生成带平台标识版本，并可能先返回 202。下载前可用对应 HEAD 操作检查元信息。不要拼接对象存储地址，不要将带鉴权的信息转发到不可信 Host。
生产客户端应校验响应 URL 与可信 API 基础地址同源，限制重定向，设置读超时和最大文件预算。示例中的链接不是匿名永久分享地址。