从素材到生成结果

本章以 MiniMax H3 为完整样板。先确定调用身份，再依次完成：发现服务 → 准备素材 → 可选优化 → 提交一次 → 查询同一任务 → 下载结果。图像、音频和文档任务沿用相同的异步读取方式，但创建地址和请求字段不同，不能直接套用 H3 的参数。

1. 先选对入口

正式地址已经包含平台要求的基础前缀，直接拼接本章的相对路径，不能手工再补 /v1。个人、调试、正式应用的素材身份不互通。不要把个人素材 ID 放进正式应用的 params，也不要把公开创建正文原样传给 create_job。

公网下文的 API_BASE、API_TOKEN 来自所选身份，均只在后端或本地环境保存。联网调用会按当前价格计费；服务发现、查询成功不是免费推理的承诺。预检不会锁定额度或算力；优化与生成是两个独立调用，不会自动互相触发。

2. 发现服务与规格

HTTP：GET {API_BASE}/services?serviceKind=video_generation，无请求体。公网响应是 {"object":"list","data":[...]}；正式应用用 GET {JUSP_APP_RUNTIME_BASE_URL}/available-services。使用发现结果的公开模型别名 modelAlias（SDK 归一为 model），不使用部署名、实例 ID 或平台内部发布编号。

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer ${API_TOKEN}" \
  "${API_BASE}/services?serviceKind=video_generation"

检查服务可用性、mediaSpecContract 和 promptOptimization。H3 当前规格为 768p、横向 1376×768 或纵向 768×1376、24 fps、5～15 整数秒，实际最高 362 帧。不要推算为固定 365 帧，不提交 fps、宽高、帧数、推理步数或设备参数。

3. 准备素材：POST /assets/input

仅用于个人 Key 或联网调试。查询参数 model 必填；请求为 multipart/form-data，每次上传一个文件。通用字段名为 file，也接受 image、video、audio。浏览器或 HTTP 库生成 multipart boundary，不手工设置不完整的 Content-Type。

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -F 'file=@storyboard.png;type=image/png' \
  "${API_BASE}/assets/input?model=minimax-h3"

成功为 201，从 asset.assetId 取素材 ID，不是 id 或顶层 assetId。主要响应字段：

默认短期有效期为24小时；以 expiresAt 为准。已受理任务持有它需要的素材，不要求用户持续上传保活。输入素材不是永久资产库，过期后需重新准备。415 表示格式不支持；413 表示体积超限；422 表示素材事实或规格不符合要求；404/403 不允许换身份绕过校验。

H3 全能参考：图片 JPG/PNG/WEBP ≤30 MiB；视频 MP4 ≤50 MiB；音频 WAV/MP3/FLAC/M4A/AAC/OGG，或包含音轨的 MOV，≤15 MiB，每段2～15秒、最多3段且合计≤15秒。MOV 必须使用 audio 上传字段，保留原始字节和音频参考身份，不占视频名额；是否能解码仍取决于实际编码。首尾帧图片另有16 MiB限制。详细像素与预处理规则见H3 视频 API。

4. 可选优化：POST /media/prompt-optimizations

Content-Type 为 application/json。必须发送 Idempotency-Key，值与 clientRequestId 完全相同。预计0～3分钟，调用超时按实时 capability 的 clientTimeoutSeconds 配置；不要把3分钟文案当作必然完成的 SLA。

优化器中的首帧、尾帧使用 first_frame、last_frame；全能参考使用 reference_image、reference_video、reference_audio。下例中的 ID 先由上一步上传取得：

{
  "clientRequestId": "storyboard-opt-001",
  "model": "minimax-h3",
  "generationMode": "universal_reference_video",
  "originalPrompt": "参考分镜图，按从左到右、从上到下的顺序表现雨夜站台递伞和共同离开。",
  "mediaSpec": {"resolutionTier": "768p", "orientation": "landscape", "seconds": 5},
  "referenceInputs": [{"role": "reference_image", "assetId": "input_storyboard"}]
}

成功为 201，响应 requestId 用于诊断，optimization.optimizedPrompt 是优化后的文本；optimization.status 为 succeeded，另有 optimizationId、模式、原文、创建/到期时间和可选 outcome/noticeCodes。确认后把完整优化文本放进生成的 prompt，不需要传 optimizationId 才能生成。

音频文件不送给 VLM，不做音频内容识别，只按原文保留音色参考等明确用途。输出以约6000字符为写作目标，最终严格≤7000；超限最多一次定向压缩，不能直接截断。失败保留原文，不自动生成视频，也不能静默删除某个参考素材。网络结果未知时仅用同一正文和同一幂等键恢复，不能新建键重复优化。完整错误说明见提示词优化 API。

5. 创建公网视频：POST /media/generations

Content-Type 为 application/json。发送稳定的 Idempotency-Key；缺省不构成安全重试合同。X-Client-Request-Id 可选，仅供关联，不能代替幂等键。请求参数在正文顶层，没有 params 包裹，也不需要 serviceKind。

全能参考的 role 与 mediaType 必须成对：reference_image/image、reference_video/video、reference_audio/audio。同类素材按数组顺序编号；不要把优化请求的“只有role/assetId”结构和生成结构混为一谈。建议把连续分镜整理成一张六/九宫格故事板并明确阅读顺序，有助于表达镜头连贯性；它不是强制规则，也不承诺所有输入都更快。

{
  "model": "minimax-h3",
  "generationMode": "universal_reference_video",
  "prompt": "参考分镜图，按从左到右、从上到下的顺序表现雨夜站台递伞和共同离开。",
  "resolutionTier": "768p", "orientation": "landscape", "seconds": 5,
  "seed": 1234,
  "referenceInputs": [{"role": "reference_image", "assetId": "input_storyboard", "mediaType": "image"}]
}

首次受理为 202，表示排队/执行中，不表示已经生成成功。典型响应（省略可选元数据）：

{"id":"job_example","jobId":"job_example","jobUrl":"https://api.example.test/v1/jobs/job_example?model=minimax-h3","object":"media.generation.job","status":"queued","requestId":"req_example","serviceKind":"video_generation","model":"minimax-h3","stage":"queued","retryAfterSeconds":3,"refreshAfterSeconds":3}

应原子保存幂等键、规范请求、jobId 和 requestId。同键同正文恢复同一任务；同键改变正文会冲突。终态重放可能返回200或对应失败状态，不应强制只接收202。创建超时且还没取得jobId时，在同一身份下重放同键同正文，而不是查询一个未取得的jobId或换键再创建。H3不提供用户取消 API，关闭页面不会撤销已经受理的任务。

6. 查询和下载

GET /jobs/{jobId}?model={model}

创建响应同时以正文 jobUrl 和响应头 Location 返回可直接调用的绝对查询地址，并用 Retry-After 给出建议秒数。使用创建任务的同一 API Key 原样请求 jobUrl；兼容旧响应时才按 jobId + model 回退拼接。轮询的网络/HTTP成功不是任务成功，应读取正文 status。支持处理中 queued/running，终态 succeeded/failed；通用 Job 还可能有历史取消状态，不能据此推导 H3 可取消。客户端必须设置总等待上限，不能无界轮询或超时后自动重提生成请求。

succeeded 后从 outputs[] 取得结果，并优先以同一 Key 原样请求绝对 contentUrl。兼容旧响应时才读取 assets[].assetId 并按公开合同拼接。不要把结果 assetId 写成 jobId，不要猜对象存储 URL，也不要把 contentUrl 当成匿名永久外链。

GET /assets/{assetId}/content?model={model}

返回二进制正文，不能用 .json() 解析。保留 Authorization；用响应 Content-Type、实际长度及可用的摘要验证文件。HEAD 同路径只读取响应头，不下载正文。下载失败可重试同一读操作，不重新创建视频。

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer ${API_TOKEN}" \
  "${API_BASE}/jobs/${JOB_ID}?model=minimax-h3"
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer ${API_TOKEN}" \
  "${API_BASE}/assets/${ASSET_ID}/content?model=minimax-h3" --output result.mp4

7. Python：联网调试完整示例

先按应用开发者工作台实时安装命令安装SDK，再通过 jusp app dev --online -- python demo.py 运行。下例使用已发行公开方法，不把返回字典误当作DTO。示例创建一次真实计费任务；生产应用应将业务键、请求和已受理标识持久保存后再继续轮询。

import time
from pathlib import Path
from jusp_sdk.runtime import RuntimeHttpClient

client = RuntimeHttpClient()  # 读取 jusp app dev 注入的地址和短期身份
model = "minimax-h3"
business_key = "project-42-shot-7-v1"  # 同一业务重试保留；新任务才更换
use_optimization = False  # 可选且单独计费；需要时设True
try:
    services = client.services(serviceKind="video_generation")
    uploaded = client.upload_input_asset(
        model=model, filename="storyboard.png",
        content=Path("storyboard.png").read_bytes(), mime_type="image/png",
    )
    asset_id = uploaded["assetId"]  # SDK 已提升 asset 信封
    payload = {
        "model": model, "generationMode": "universal_reference_video",
        "prompt": "按故事板从左到右、从上到下表现雨夜递伞与共同离开。",
        "resolutionTier": "768p", "orientation": "landscape", "seconds": 5,
        "referenceInputs": [{"role": "reference_image", "assetId": asset_id, "mediaType": "image"}],
    }
    if use_optimization:
        optimized = client.optimize_prompt({
            "clientRequestId": business_key + "-opt", "model": model,
            "generationMode": payload["generationMode"], "originalPrompt": payload["prompt"],
            "mediaSpec": {key: payload[key] for key in ("resolutionTier", "orientation", "seconds")},
            "referenceInputs": [{"role": "reference_image", "assetId": asset_id}],
        }, timeout=630)  # 应用中使用所选服务capability的clientTimeoutSeconds
        payload["prompt"] = optimized["optimization"]["optimizedPrompt"]
    accepted = client.video_generation(payload, idempotency_key=business_key)
    job_id = accepted["jobId"]  # 此处是字典，不是 RuntimeJob
    deadline = time.monotonic() + 900  # 调用方等待预算，不是服务完成时限
    while time.monotonic() < deadline:
        job = client.get_job(job_id, model=model)  # 此处才是 RuntimeJob
        if job.status == "succeeded":
            if not job.results:
                raise RuntimeError("任务成功但结果未就绪，请稍后查询同一任务")
            result = client.download_result_with_metadata(job_id, job.results[0].result_id, model=model)
            Path("result.mp4").write_bytes(result.content)
            print(result.content_type, result.byte_size, result.sha256)
            break
        if job.status in {"failed", "canceled"}:
            raise RuntimeError(f"任务终止：{job.job_id} / {job.status}")
        time.sleep(5)
    else:
        raise TimeoutError(f"停止本地等待，不取消任务；以后继续查询 {job_id}")
finally:
    client.close()

RuntimeDownload 的字段是 content: bytes、content_type: str、byte_size: int、sha256: str。摘要和字节数由SDK对实际正文计算；没有 content_length 或 etag 属性。head_asset() 是另一种返回字典的操作，不要混用其字段。

8. 正式应用：POST /media/jobs

使用 RuntimeHttpClient(session=session)，其中session来自用户从应用中心打开后兑换的 RuntimeSession。SDK读取平台托管凭据。不要把用户主体ID当作session，也不要在浏览器里保存平台凭据。

正文与公网创建不同：

inputs[] 的 readUrl 必填，另有 role/mimeType/byteSize/sha256/expiresAt。URL必须由应用自己的存储签发，满足平台读取策略；不能指向任意用户内网地址或本机文件。期限需覆盖平台读取过程，摘要/字节数与内容一致；平台校验后暂存。H3角色为首帧 first_frame、尾帧 last_frame，或全能参考的三种 reference_*；数量及音频时长约束与公网相同。

client = RuntimeHttpClient(session=session)
job = client.create_job({
    "model": "minimax-h3", "serviceKind": "video_generation",
    "clientTaskId": "project-42-shot-7-v1",
    "params": {"prompt": "清晨湖面薄雾缓慢流动，固定镜头，自然环境声。"},
    "mediaSpec": {"generationMode": "t2v", "resolutionTier": "768p", "orientation": "landscape", "seconds": 5},
}, idempotency_key="project-42-shot-7-v1")
# 将以下三个值原子持久化；recovery_ref 是秘密，只在应用后端保存。
job_id, task_id, recovery_ref = job.job_id, job.client_task_id, job.recovery_ref

首次受理202，HTTP正文直接包含 platformJobId/clientTaskId/status/stage/jobRecoveryRef；results尚无结果时可能省略。SDK转换为 RuntimeJob，results为tuple，恢复引用保存在 recovery_ref。同键终态重放可返回200或相应失败码。正式响应不能套用公网的 assets[] 解析。

正常查询 GET /media/jobs/{jobId} 使用session；服务重启后的受控恢复使用该任务的 X-Jusp-Job-Recovery-Ref，不同时发送session头。SDK的 get_job(job_id, recovery_ref=...) 和 download_result_with_metadata(job_id, result_id, recovery_ref=...) 自动选择恢复头。恢复引用只允许访问绑定的已有任务，不能用于新建任务、其它任务或代替用户登录。

正式下载是 GET /media/jobs/{jobId}/results/{resultId}/download。RuntimeResult 包含 result_id/download_url，以及可选 mime_type/byte_size/sha256。原始HTTP结果对应 resultId/resultDownloadUrl/mimeType/byteSize/sha256。结果下载URL不代表匿名永久外链。

正式优化仍调用 /media/prompt-optimizations，但 referenceInputs 每项必须含应用素材的role/readUrl、正数byteSize及真实内容的小写64位sha256；可附mimeType/expiresAt。不能复制公网role/assetId示例，也不接受mediaType。优化成功只提取文本，再构造上述create_job正文；优化不会替应用创建任务或持久保存最终业务资产。

9. 错误与恢复决策

更多恢复入口包括事件流、批量查询、导出和资源用量聚合，见应用 HTTP API参考。SDK全部方法、同步/异步差异见Python API参考。