已部署应用 Runtime

本章仅适用于已部署应用后端。基础地址使用完整的 JUSP_APP_RUNTIME_BASE_URL；应用凭据由平台注入，普通请求另带 X-Jusp-Runtime-Session-Id。不要手填集群地址，不复用个人 API Key。会话取得方式见会话与应用授权。

本文所有地址都是相对于该基础地址的路径。JSON 请求使用 Content-Type: application/json；成功正文直接是本章描述的对象，没有统一的 data 信封。HTTP 和 Python 完整媒体样例见媒体生成全链路，字段机器定义见开发者 OpenAPI。

1. GET /available-services

查询当前应用版本、用户会话可以调用的服务；无请求体。不代表后续任务必然被受理。

200 返回 object: "list"、items、page、pageSize、total 和可选筛选信息。每项核心字段为 model/displayName/serviceKind/status，适用时含 mediaSpecContract、apiUsageContract、promptOptimization。业务请求保存公开 model，不把工作负载或内部发布编号当模型别名。SDK：services(serviceKind="video_generation")。

2. 同步推理接口

以下均为 POST JSON。model 使用服务发现的别名；先检查该服务实际声明的参数。推理可能计费，响应丢失不能直接无条件重放。

对话消息、embedding/rerank输出的逐字段表和示例见公共 AI 接口。素材传输不同：正式 OCR/ASR 是 JSON inputs[].readUrl，平台读取后转换；公网 ASR 是 multipart，不能复制到这里。同步接口也可携带下文的 resourceAttribution 用于按应用业务资源归集。

{
  "model": "服务发现中的转写模型别名",
  "inputs": [{"readUrl": "https://media.example.com/signed/audio.wav", "mimeType": "audio/wav"}]
}

readUrl 必须是平台能受控访问、在处理期间有效的应用素材链接；不能是本地路径、集群内部地址或其他用户的素材引用。URL只是示例域名，使用前替换为应用自己的有效链接。

3. POST /media/prompt-optimizations

优化与生成独立，不会自动提交任务。发送 Idempotency-Key，与 clientRequestId 一致。正式身份仍需有效用户会话；不能用已有视频任务的恢复引用授权优化。

201 返回 requestId 和 optimization：optimizationId/publicationId/serviceKind/generationMode/originalPrompt/optimizedPrompt/status/createdAt/expiresAt，可选 outcome/noticeCodes。publicationId 是响应关联信息，客户端继续使用公开model。H3输出≤7000字符；音频只保留音色等意图，不送VLM理解。预计0～3分钟，超时取实时capability；失败保留原文。完整素材组合条件和错误处理见媒体样板。

4. POST /media/jobs

创建图像、视频、音频或文档异步任务。首次受理202；同一幂等业务重放返回已有任务，HTTP状态可能随任务状态变化。受理不代表生成成功。

inputs[]：readUrl 必填；按模式给 role（first_frame、last_frame、reference_image、reference_video、reference_audio），可附 mimeType/sha256/byteSize/expiresAt。不传mediaType或purpose，不能把优化素材结构原样复制。摘要与字节数是校验事实，不能伪造。H3不能用个人素材assetId替代readUrl。

{
  "clientTaskId": "project-42-shot-7",
  "model": "minimax-h3",
  "serviceKind": "video_generation",
  "params": {"prompt": "雨夜站台，两个人共同撑伞离开。"},
  "mediaSpec": {"generationMode": "t2v", "resolutionTier": "768p", "orientation": "landscape", "seconds": 5},
  "resourceAttribution": {"resourceType": "project", "resourceId": "project-42"}
}

RuntimeJob 响应

创建成功即保存 platformJobId、原幂等键、规范正文、jobRecoveryRef。查询响应不保证重新发送恢复引用；不要用空值覆盖已保存值。H3无取消API，不提供取消按钮或自行构造取消路径。SDK：create_job(payload, idempotency_key=...) → RuntimeJob。

5. POST /media/jobs:dry-run

输入与创建任务相同，检查身份、模型、规格、素材和当前准入；可能读取/探测素材，但不执行生成、不扣实际生成费用。200返回 accepted/clientTaskId/appContext，适用时有 serviceKind/model/normalizedSpec/estimatedCost/admission/blockers/readUrlChecks/traceId。normalizedSpec 是去掉提示词等内容后的规范规格；estimatedCost含resourceType、usage、unit、estimatedAmount、currency等估算字段。accepted:false 是有效预检结果；每项blocker含code/phase/message/retryable和可选httpStatus/details。早期认证或JSON错误仍返回4xx。通过预检不锁定余额、队列或算力。

SDK使用 request("POST", "/media/jobs:dry-run", payload=payload)；不可把联网 preview_admission 的 {model,request} 包裹复制到这里。

6. GET /media/jobs/{jobId}

jobId 必填且来自创建结果；无请求体，无model查询参数。200返回上述RuntimeJob，即使任务已经failed也要读status。普通读取使用同一有效会话；进程恢复可改用 X-Jusp-Job-Recovery-Ref 加托管应用凭据，不同时发送会话与恢复引用。恢复引用不能跨任务、跨应用或创建新任务。

SDK get_job(job_id, recovery_ref=original_recovery_ref)。从2秒开始退避，最长10秒；429遵守Retry-After；取得终态停止轮询。

7. GET /media/jobs/{jobId}/results/{assetId}/download

两个路径参数必填；assetId 使用该任务 results[].resultId。鉴权与单任务查询一致。200为原始二进制，不是JSON；检查Content-Type和实际字节摘要。404受控地覆盖资源不存在或不属于调用方，不能改ID枚举。

SDK download_result 返回bytes；download_result_with_metadata 返回content、content_type、byte_size、sha256，后两项是对下载正文计算的事实，没有etag属性。不要从downloadUrl推测存储桶或绕过平台鉴权。

8. POST /media/jobs:batch-get

请求：{"platformJobIds":["job_1","job_2"]}。1～100个非空ID，平台会去重；普通应用用户会话作用域。200返回 items（任务快照数组）与 missing（未命中ID）。missing也可能表示无权访问，不代表可以重新创建。

SDK batch_get_jobs(job_ids)。单任务恢复引用不能授权全局批量检索。用于进程重启后的有界补偿，不用它不停扫描所有历史任务。

9. GET /media/events

任务事件流，200为 text/event-stream；普通应用会话作用域。

先读取snapshot，再处理job阶段事件、heartbeat和done；每个 data: 是JSON，id: 是需持久化的游标。先处理成功再确认游标，重复事件按ID去重；断线以最后已确认ID重连。快照有界，不包含所有历史任务，未出现不代表任务丢失。创建响应的job关联eventCursor不能当数值SSE重连游标。

SDK consume_events(cursor=..., once=True, limit=50) 返回JSON事件字典列表，不保留SSE原始头。任务事件从字典的 id 取游标，snapshot/heartbeat/done从 cursor 取游标；网关同时将数值写进JSON，所以无需依赖被SDK忽略的SSE id行。处理成功后才保存游标；continuous模式请设置有界连接/重连策略。业务结果仍以单任务快照及结果下载为准。

10. POST /media/exports

为应用自有素材创建带平台标识的下载副本，不是传jobId做转码，也不重新调用模型。源文件不变，仅支持 intent: download 与 deliveryMode: marked（均为默认值）。

{"source":{"readUrl":"https://media.example.com/signed/shot.mp4","mimeType":"video/mp4","appAssetRef":"shot-7-v1"},"intent":"download","deliveryMode":"marked","idempotencyKey":"shot-7-download-v1"}

准备中202，已有ready副本200。返回 exportId/status/statusUrl，可选 contentUrl/mimeType/byteSize/errorCode/retryAfterSeconds/expiresAt，以及 deliveryMode/intent。按返回时间查询，不因准备中反复创建新导出。SDK使用 request("POST", "/media/exports", payload=...)。

11. GET /media/exports/{exportId}

exportId必填，无请求体。200返回导出对象；只有status为ready且有contentUrl才可下载。准备或处理中有界等待；failed按errorCode处理，不把URL存在当作成功。普通会话鉴权，视频任务恢复引用不能替代它。

12. GET /media/exports/{exportId}/download

exportId必填，无请求体。200返回二进制带标识副本，含Content-Disposition、X-Jusp-Asset-Variant: marked_export。409 export_not_ready，Retry-After为5秒；404为受控不存在/越权。SDK使用 request 时不能期待JSON解码的通用调用直接返回文件；二进制下载用带同等身份的HTTP客户端，不把session或token放到浏览器URL。

13. POST /resource-usage:aggregate

仅有活动组织会话时可用；组织和appKey由身份推导，不由请求指定。用于应用自己的项目、作品等业务资源用量，不暴露H3内部角色计费。

{"resourceType":"project","resourceIds":["project-42"],"groupBy":["serviceKind"]}

200返回 items/amountScale/asOf/freshness。每项含resourceId和所选分组，以及 ledgerSettledCredits/reservedCredits/releasedCredits/failedCredits/pendingCredits/requestCount。金额精度由amountScale确定，不能把原始整数直接显示成积分，也不要把预留与结算简单相加当收入。SDK使用 request("POST", "/resource-usage:aggregate", payload=...)。

14. 错误、未知结果与重试

错误正文主要为 code/message，适用时含 phase/retryable/requestId/traceId/details。不要把服务器堆栈或凭据交给最终用户。

SDK异常与生命周期见Python方法参考。