提交媒体 URL,然后等待 Webhook。
MediaRuntime 可直接接受公共 HTTP(S) URL 或限时签名读取 URL。该 URL 必须保持可访问,直到 worker 下载输入。提交成功会立即返回 QUEUED;完成的输出随后通过已签名的 Webhook 送达。
# Submit a public or time-limited HTTPS source directly.
# Keep the URL fetchable until MediaRuntime has downloaded the input.
curl -sS -X POST "https://mediaruntime.com/v1/jobs" \
-H "X-API-Key: $MEDIARUNTIME_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"file_url": "https://cdn.example.com/media/launch-trailer.mp4",
"metadata": { "asset_id": "asset_0426", "media_type": "video" },
"outputs": [{
"type": "mp4",
"preset": "mp4_720p_h264_aac",
"poster_time_sec": 2
}]
}'# Optional: use this when you have local bytes but no fetchable source URL.
UPLOAD=$(curl -sS -X POST "https://mediaruntime.com/v1/upload-url" \
-H "X-API-Key: $MEDIARUNTIME_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filename":"launch-trailer.mp4","content_type":"video/mp4"}')
UPLOAD_URL=$(printf '%s' "$UPLOAD" | jq -r .upload_url)
FILE_URI=$(printf '%s' "$UPLOAD" | jq -r .file_uri)
UPLOAD_CONTENT_TYPE=$(printf '%s' "$UPLOAD" | jq -r '.upload_headers["Content-Type"]')
UPLOAD_AUTH=$(printf '%s' "$UPLOAD" | jq -r '.upload_headers.Authorization // empty')
UPLOAD_ARGS=(-H "Content-Type: $UPLOAD_CONTENT_TYPE")
if [[ -n "$UPLOAD_AUTH" ]]; then
UPLOAD_ARGS+=(-H "Authorization: $UPLOAD_AUTH")
fi
curl -sS -X PUT "$UPLOAD_URL" "${UPLOAD_ARGS[@]}" \
--upload-file ./launch-trailer.mp4
# Then use "$FILE_URI" as file_url in POST /v1/jobs.{
"job_id": "job_1320c28b72104811b075a26a99496cf6",
"status": "QUEUED",
"tier": "standard",
"msg": "accepted"
}将 API 密钥保留在您的服务器上。
从帐户 → API 密钥创建密钥。原始密钥仅显示一次并属于您的秘密管理器,而不是浏览器代码、移动二进制文件、日志或源代码控制。
标头
在每个 /v1 请求上发送 X-API-Key。
存储
将 MEDIARUNTIME_API_KEY 存储在服务器端秘密管理器中。
旋转
创建替换密钥,部署它,验证流量,然后撤销旧密钥。
让元数据完成集成关联。
wMedia 使用的生产模式有意保持简单:提交输入、输出配方以及足够的不透明元数据,以便将终态事件关联回您自己的数据库记录。
{
"file_url": "https://cdn.example.com/media/source.mp4",
"metadata": {
"producer": "my-api",
"entity_id": "video_01J8Y4",
"owner_id": "user_482",
"media_type": "video",
"trace_id": "req_f839"
},
"moderation": {
"enabled": true,
"mode": "report",
"checks": ["sexual", "violence", "dangerous"]
},
"watermark": { "enabled": true },
"outputs": [
{
"type": "mp4",
"preset": "mp4_720p_h264_aac",
"path_suffix": "web",
"poster_time_sec": 2,
"gif_preview": {
"enabled": true,
"width": 320,
"fps": 8,
"start_time": 2,
"duration": 2.5
}
},
{
"type": "image",
"preset": "image_multi_v1",
"path_suffix": "covers",
"images": [
{ "width": 1280, "height": 720, "mode": "fit", "format": "webp", "quality": 84 },
{ "width": 480, "height": 480, "mode": "cover", "format": "webp", "quality": 80 }
]
}
]
}| 领域 | 类型 | 注释 |
|---|---|---|
| file_url | 字符串 | 一个公共 HTTP(S)、限时签名 HTTP(S) 或可访问的 gs:// 输入。使用此或 输入,切勿同时使用。 |
| inputs | 数组 | 1–25 输入 的批量扇出。每个都可以携带 input_id 和 元数据。 |
| outputs | 数组 | 1–10 个输出配方。每个都需要类型;强烈推荐预设。 |
| metadata | 对象 | JSON 高达 32 KiB。在meta.request_metadata 上坚持并回应。 |
| moderation | 对象 | Premium 视觉媒体 检查:性、暴力、危险。 |
| watermark | 对象 | Premium 视觉媒体叠加。该帐户必须已有 PNG 徽标。 |
批量扇出
当每个输入需要相同的 输出 时,请使用批处理。每个输入 元数据 合并到每个子作业中;父作业将成为您的批次参考。
{
"inputs": [
{
"file_url": "https://cdn.example.com/a.mp4",
"input_id": "asset-a",
"metadata": { "position": 0 }
},
{
"file_url": "https://cdn.example.com/b.mp4",
"input_id": "asset-b",
"metadata": { "position": 1 }
}
],
"metadata": { "batch_id": "import_2026_08_09" },
"outputs": [{ "type": "mp4", "preset": "mp4_720p_h264_aac" }]
}使用 Idempotency-Key 安全重试
超时请求是不明确的:作业可能已排队,但仅丢失了响应。发送 Idempotency-Key 标头并重试是安全的 - 相同的密钥返回原始作业,而不是排队并为第二个作业收费。如果没有标头,行为不会改变,并且每个 POST 都会创建一个新作业。
# One key per logical job. Generate it in your client, not inside the retry loop.
KEY=$(uuidgen) # or a deterministic id you can regenerate: asset_0426:mp4_720p:v1
curl -sS -X POST "https://mediaruntime.com/v1/jobs" \
-H "X-API-Key: $MEDIARUNTIME_API_KEY" \
-H "Idempotency-Key: $KEY" \
-H "Content-Type: application/json" \
-d '{
"file_url": "https://example.com/source.mp4",
"metadata": { "asset_id": "asset_0426" },
"outputs": [{ "type": "mp4", "preset": "mp4_720p_h264_aac" }]
}'
# Timed out? Send the exact same request again with the SAME key.
# You get the original job_id back - no second job, no second charge.关键规则
- UUID 有效;像
asset_0426:mp4_720p:v1这样的确定性 ID 更好,因为您可以在崩溃后重新生成它。 - 密钥的范围仅限于您的帐户,并且 24 小时内有效。
- 重复使用具有不同主体的密钥会返回 422 — 通常在循环中重复使用一个密钥。
- 当第一个仍在运行时发送的重试返回 409;短暂退避后重试。
- 故意提交同一个文件两次?使用两个不同的键。
选择您希望引擎生成的工件。
`type` 和 `preset` 共同构成可执行配方。请使用下方列出的准确 `type`:只有 `preset` 名称不会改变输出类型,不匹配的组合可能被拒绝或错误路由。
{
"file_url": "https://cdn.example.com/landscape-interview.mp4",
"outputs": [{
"type": "social",
"preset": "social_vertical_blur"
}]
}social_vertical_blur 创建 1080×1920 H.264/AAC MP4。源被缩放以适应而不裁剪;其后面的 9:16 画布上充满了模糊的副本。将其用于 Reels、TikTok 和 Shorts。它是 Premium 配方,因为垂直输出高为 1920 像素。视频文件和海报
| 预设 | 发送 | 作业执行 | 基础层 |
|---|---|---|---|
| mp4_720p_h264_aac (type: mp4) | 视频 | 720p H.264/AAC MP4 具有快速启动功能,可进行网络播放。 | Standard |
| mp4_ladder_v1 (type: mp4) | 视频 | 三个 MP4 版本(1080p、720p 和 480p),以及每个版本的海报。 | Standard |
| transmux_mp4_fast (type: mp4) | 兼容的音频/视频 | 将现有流复制到快速启动 MP4 中,无需重新编码。如果复制失败并且启用了回退,引擎将使用 720p H.264 预设 重新编码。 | Standard |
| poster_frame_v1 (type: mp4) | 视频 | 在 poster_time_sec 处捕获的一张 720p JPG。请求类型仍然是mp4。 | Standard |
| mp4_hevc_1080p (type: mp4) | 视频 | 1080p HEVC/H.265 + AAC MP4 带有适用于 Apple 播放的 hvc1 标签。 | Premium |
| mp4_av1_smart (type: mp4) | 视频 | 1080p AV1 + Opus MP4 针对压缩效率进行了优化;编码是 CPU 密集型的。 | Premium |
| mov_prores_422 (type: mp4) | 视频 | ProRes 422 HQ + PCM MOV 编辑大师。保留源尺寸并生成大的夹层文件。 | Premium |
社交视频
| 预设 | 发送 | 作业执行 | 基础层 |
|---|---|---|---|
| social_vertical_blur (type: social) | 视频 | 1080×1920 H.264/AAC MP4。适合 Reels、TikTok 和 Shorts 的模糊 9:16 背景。 | Premium |
动画 GIF
| 预设 | 发送 | 作业执行 | 基础层 |
|---|---|---|---|
| gif_hq (type: gif) | 视频 | 使用调色板生成以 480 像素宽度和 15 fps 制作动画 GIF,以获得更好的颜色质量。 | Standard |
帧提取
| 预设 | 发送 | 作业执行 | 基础层 |
|---|---|---|---|
| extract_frames_1 (type: frames) | 视频 | 编号为 JPG 的帧序列以每秒 1 帧的速度采样。 | Standard |
| extract_frames_5 (type: frames) | 视频 | 编号为 JPG 的帧序列以每秒 5 帧的速度采样。 | Standard |
| scene_detect_v1 (type: frames) | 查看输入规则 | Detects shot boundaries and exports one keyframe per shot (scene_00001.jpg…), plus scenes.txt with each boundary's timestamp and score. Frame count equals shot count — a single continuous take yields one. | 各不相同 |
| perceptual_hash_v1 (type: frames) | 查看输入规则 | Fingerprints the video by sampling one frame per second and reducing each to a 64-bit dHash, written to phash.json. Compare two videos with Hamming distance to answer “is this the same content?” — it survives re-encoding and rescaling, where a checksum does not. Useful for deduplication and reupload detection. Not crop-invariant. | 各不相同 |
流媒体
| 预设 | 发送 | 作业执行 | 基础层 |
|---|---|---|---|
| hls_ladder_v1 (type: hls) | 视频 | HLS VOD 包,包含 1080p 和 720p H.264/AAC 变体、主播放列表和 6 秒片段。 | Standard |
音频
| 预设 | 发送 | 作业执行 | 基础层 |
|---|---|---|---|
| audio_copy_fast (type: audio) | 音频或带音频的视频 | 复制源音频流而不重新编码。如果复制失败并且启用了回退,引擎将改为写入 128 kbps AAC。 | Standard |
| audio_aac_128k (type: audio) | 音频或带音频的视频 | 快速启动 M4A 文件中的 128 kbps AAC。 | Standard |
| audio_mp3_128k (type: audio) | 音频或带音频的视频 | 128 kbps MP3 文件。 | Standard |
| audio_opus_96k (type: audio) | 音频或带音频的视频 | 96 kbps Opus 文件,非常适合语音传送。 | Standard |
| audio_loudnorm_aac_128k (type: audio) | 音频或带音频的视频 | 标准化为 -16 LUFS,然后写入 128 kbps AAC。 | Standard |
| audio_trim_silence_aac_128k (type: audio) | 音频或带音频的视频 | 删除前导和尾随静音,然后写入 128 kbps AAC。 | Premium |
| audio_loudnorm_trim_aac_128k (type: audio) | 音频或带音频的视频 | 修剪边界静默,标准化为 -16 LUFS,然后写入 128 kbps AAC。 | Premium |
| audio_whisper_prep (type: audio) | 音频或带音频的视频 | 16 kHz 单声道 PCM WAV 为 Whisper、ASR 或其他语音管道准备。 | Premium |
图像衍生品
| 预设 | 发送 | 作业执行 | 基础层 |
|---|---|---|---|
| image_multi_v1 (type: image) | 图片 | 使用 fit、fill、cover 或 contains 创建您请求的图像数组。层级取决于格式、大小、数量、智能裁剪和背景去除。 | Standard 或 Premium |
| media_report_v1 (type: image) | 查看输入规则 | Inspects the file without transcoding it and writes media_report.json: container and stream detail, encoder strings, GOP/keyframe structure, and EXIF including GPS coordinates converted to decimal degrees. This READS metadata rather than stripping it — image renditions still strip metadata as before. Accepts video or images; audio-only inputs are not supported. | 各不相同 |
transmux_mp4_fast 避免了质量改变编码。如果复制失败并且启用了回退,引擎将使用 mp4_720p_h264_aac 重新编码;当您需要可预测的输出特性时,请直接使用 预设。使用一个来源。生成您的产品所需的格式和边车工件。
源扩展不选择输出。 类型 和 预设 选择可执行配方,因此上传的视频可以在同一异步作业中成为播放视频、纯音频媒体、脚本、GIF 预览、海报或帧序列。
| 来源 | 可交付成果 | 食谱 |
|---|---|---|
| JPG、PNG 或 WebP | JPG、PNG、WebP 或 AVIF 衍生物 | 图像+image_multi_v1;选择图像[].格式、尺寸、mode 和质量。 |
| 视频 | Web MP4、HLS、社交视频或编辑大师 | 选择匹配的 mp4、hls 或社交 预设。 |
| 视频 | 动画 GIF、海报或 JPG 帧序列 | 使用 gif_hq、poster_frame_v1、extract_frames_1/5 或将 gif_preview 连接到视频输出。 |
| 视频或音频 | M4A、MP3、Opus 或语音 WAV | 选择对应的audio_* 预设;视频 输入 已提取其音频流。 |
| 视频或音频演讲 | SRT、WebVTT 或两者 | 将字幕添加到音频或视频输出并选择 srt、vtt 或两者。 |
{
"file_url": "https://cdn.example.com/media/product-photo.png",
"metadata": {
"media_type": "image",
"asset_id": "product-photo-0426"
},
"outputs": [{
"type": "image",
"preset": "image_multi_v1",
"path_suffix": "converted",
"images": [
{ "width": 1600, "height": 1200, "mode": "fit", "format": "jpg", "quality": 88 },
{ "width": 1600, "height": 1200, "mode": "fit", "format": "webp", "quality": 82 }
]
}]
}{
"file_url": "https://cdn.example.com/media/interview.mov",
"outputs": [
{ "type": "mp4", "preset": "mp4_720p_h264_aac", "path_suffix": "web-video" },
{ "type": "audio", "preset": "audio_mp3_128k", "path_suffix": "audio-only" }
]
}{
"file_url": "https://cdn.example.com/media/interview.mp4",
"metadata": { "media_type": "video", "asset_id": "interview-0426" },
"outputs": [{
"type": "audio",
"preset": "audio_aac_128k",
"path_suffix": "audio-and-transcript",
"subtitles": {
"enabled": true,
"languages": ["auto"],
"format": "both",
"model": "ggml-base.bin",
"translate_to_english": false
}
}]
}{
"file_url": "https://cdn.example.com/media/trailer.mp4",
"metadata": { "media_type": "video", "asset_id": "trailer-0426" },
"outputs": [{
"type": "mp4",
"preset": "mp4_720p_h264_aac",
"path_suffix": "web",
"poster_time_sec": 4,
"poster_format": "jpg",
"gif_preview": {
"enabled": true,
"width": 480,
"fps": 10,
"start_time": 4,
"duration": 3
}
}]
}{
"file_url": "https://cdn.example.com/media/feature-film.mp4",
"metadata": { "media_type": "video", "asset_id": "stream-0426" },
"outputs": [{
"type": "hls",
"preset": "hls_ladder_v1",
"path_suffix": "stream"
}]
}{
"file_url": "https://cdn.example.com/media/clip.mp4",
"metadata": { "media_type": "video", "asset_id": "clip-0426" },
"outputs": [
{ "type": "gif", "preset": "gif_hq", "path_suffix": "animated-preview" },
{ "type": "frames", "preset": "extract_frames_1", "path_suffix": "sampled-frames" }
]
}hls_ladder_v1 创建主播放列表、1080p 和 720p H.264/AAC 变体播放列表以及 6 秒媒体片段。使用报告的主播放列表 URL,或将整个捆绑包一起移动。gif_hq 创建完整的 480px、15 fps 主 GIF。 gif_preview 将更短、明确定时的 GIF 添加到另一个视频输出。帧预设以每秒一帧或五帧的速度返回编号为 JPG 的序列。有用的开关
audio_aac_128k 返回 M4A,audio_mp3_128k 返回 MP3,audio_opus_96k 返回 Opus,audio_whisper_prep 返回 16 kHz 单声道 WAV。将 subtitles.format 设置为 srt、vtt 或 both。仅针对一张海报图像,发送 type: mp4 以及 preset: poster_frame_v1 和所需的 poster_time_sec。
从预设开始;仅覆盖重要的内容。
预设使请求保持可读性并为引擎提供稳定的基线。仅当产品需要时才添加显式再现、字幕、预览、编解码器或比特率选项。
{
"file_url": "https://cdn.example.com/source.jpg",
"outputs": [{
"type": "image",
"preset": "image_multi_v1",
"images": [
{ "width": 1200, "height": 630, "mode": "cover", "format": "webp", "quality": 84 },
{ "width": 320, "height": 320, "mode": "cover", "format": "webp", "quality": 78 }
]
}]
}{
"file_url": "https://cdn.example.com/interview.wav",
"outputs": [{
"type": "audio",
"preset": "audio_aac_128k",
"subtitles": {
"enabled": true,
"languages": ["auto"],
"format": "both",
"model": "ggml-base.bin"
}
}]
}{ "watermark": { "enabled": true } }; MediaRuntime 解析服务器拥有的徽标。在工作中添加分层视觉安全分析。
审核对一幅图像或视频输入使用分层管道:清晰的信号采用快速路径,而不确定或高风险的信号则升级以进行更深入的分析。它通过当前的仅报告合同返回尽力而为的证据和决策,而不会阻止转码。
{
"file_url": "https://cdn.example.com/upload.mp4",
"metadata": { "media_type": "video", "asset_id": "asset_0426" },
"moderation": {
"enabled": true,
"mode": "report",
"checks": ["sexual", "violence", "dangerous"]
},
"outputs": [{
"type": "mp4",
"preset": "mp4_720p_h264_aac"
}]
}{
"moderation": {
"requested": {
"enabled": true,
"mode": "report",
"checks": ["sexual", "violence", "dangerous"],
"media_type": "video",
"phase": "phase1_video_report"
},
"result": {
"ok": true,
"media_type": "video",
"verdict": "review",
"flagged_checks": ["violence"],
"scores": {
"violence": { "yes": 0.82, "no": 0.18 }
},
"decisions": {
"violence": { "decision": "review", "raw_decision": "review" }
},
"evidence": {
"frames_sampled": 8,
"frames_flagged": [{
"frame_index": 3,
"timestamp_sec": 20,
"verdict": "review",
"flagged_checks": ["violence"]
}]
},
"video": {
"frame_interval_sec": 10,
"max_frames": 24
}
}
},
"meta": {
"moderation_result": {
"url": "https://storage.googleapis.com/.../moderation_result.json"
}
},
"usage": {
"breakdown": { "moderation_units": 120 }
}
}| Contract | Value | Notes |
|---|---|---|
| Plan | Premium | The API returns 403 unless the account is Premium or auto-upgrade is allowed. |
| Mode | report | This is the only accepted mode today. Do not send block. |
| Checks | sexual, violence, dangerous | Send one to three checks. Omitting checks selects all three. |
| Inputs | One image or video | Audio-only inputs, batches, and Sandbox moderation are rejected. |
| Video sampling | Fixed interval, bounded frames | The service chooses the interval and cap; read the actual values from result.video and result.evidence. |
| Decision | allow, review, or block signal | Report mode never blocks execution. Use result.verdict, decisions, flagged_checks, and evidence in your own policy. |
| Artifact | meta/moderation_result.json | Included in the output ZIP and exposed through meta.moderation_result.url when available. |
| Billing | Separate moderation units | Estimated and settled with the job at usage.breakdown.moderation_units. |
review 视为人工队列、发布保留或您控制的其他策略的信号。完整的报告并不保证媒体安全、合法或符合政策。在信任事件之前验证原始字节。
终端事件至少发送一次,并且不保证订购。验证 HMAC-SHA256、拒绝过时的时间戳、删除重复的 event_id、快速确认并将繁重的工作移至队列。
{
"event_id": "webhook_evt_job_1320c28b72104811b075a26a99496cf6",
"job_id": "job_1320c28b72104811b075a26a99496cf6",
"account_id": "acc_xxx",
"status": "COMPLETED",
"completedAt": "2026-08-09T02:41:23Z",
"billing": { "status": "PAID", "estimatedUnits": 31 },
"usage": { "units_total": 31, "breakdown": {} },
"delivery": {
"mode": "PULL",
"retentionDays": 7,
"expiresAt": "2026-08-16T02:41:23Z",
"bundle": {
"type": "zip",
"filename": "outputs.zip",
"download": {
"url": "https://mediaruntime.com/v1/jobs/job_1320c28b72104811b075a26a99496cf6/bundle?token=...",
"expiresAt": "2026-08-16T02:41:23Z"
}
}
},
"meta": {
"engine_result_url": "https://storage.googleapis.com/...",
"outputs_root_gs": "gs://.../jobs/acc_xxx/job_.../outputs",
"request_metadata": {
"producer": "my-api",
"entity_id": "video_01J8Y4",
"media_type": "video"
}
}
}delivery.bundle.download.url 下载完整的 ZIP,或获取 meta.engine_result_url 以枚举各个输出和工件路径。import crypto from "node:crypto";
import express from "express";
const app = express();
// Register this route before any express.json() middleware.
app.post("/webhooks/mediaruntime", express.raw({ type: "application/json" }), (req, res) => {
const eventId = req.get("X-Transcoder-Id") || "";
const signatureHeader = req.get("X-Transcoder-Signature") || "";
const parts = Object.fromEntries(
signatureHeader.split(",").map((part) => part.trim().split("="))
);
const timestamp = parts.t || "";
const received = parts.v1 || "";
const ageSeconds = Math.abs(Date.now() / 1000 - Number(timestamp));
if (!eventId || !timestamp || !received || ageSeconds > 300) {
return res.sendStatus(401);
}
const expected = crypto
.createHmac("sha256", process.env.MEDIARUNTIME_WEBHOOK_SECRET)
.update(timestamp + "." + eventId + ".")
.update(req.body) // raw Buffer; never JSON.stringify(req.body)
.digest("hex");
const a = Buffer.from(expected, "utf8");
const b = Buffer.from(received, "utf8");
if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
return res.sendStatus(401);
}
const event = JSON.parse(req.body.toString("utf8"));
// Enqueue work and deduplicate on event.event_id in your database.
console.log(event.event_id, event.job_id, event.status);
return res.sendStatus(200);
});发货规则
- 仅在签名验证和持久排队/重复数据删除后返回任何 2xx。
- 将 event_id 视为幂等键。
- 使用meta.request_metadata 无需第二个查找表即可查找您的实体。
- 下载保留前的输出.expiresAt。
- FAILED 或 REJECTED 事件具有 error.code/message 并且没有可用的捆绑包。
当 webhook 不实用时进行轮询。
提交立即返回,并带有 job_id。 Webhooks 仍然是了解已完成工作的最低延迟方式,但轮询可用于本地开发、没有公共端点的环境、协调和支持问题。
curl -sS "https://mediaruntime.com/v1/jobs/$JOB_ID" \
-H "X-API-Key: $MEDIARUNTIME_API_KEY"# Newest first. Filter by status and page with the cursor.
curl -sS "https://mediaruntime.com/v1/jobs?status=COMPLETED&limit=25" \
-H "X-API-Key: $MEDIARUNTIME_API_KEY"
# Next page: pass the previous response's next_cursor
curl -sS "https://mediaruntime.com/v1/jobs?limit=25&cursor=$NEXT_CURSOR" \
-H "X-API-Key: $MEDIARUNTIME_API_KEY"{
"job_id": "job_2ee8db582cdf4a2fafb49d52218b3159",
"status": "COMPLETED",
"tier": {
"requested": "premium",
"required": "standard",
"effective": "premium",
"billed": "standard",
"reasons": []
},
"usage": { "units_total": 4 },
"billing": {
"status": "PAID",
"currency": "USD",
"unit_price_cents": 1,
"final_units": 4,
"final_amount_cents": 4
},
"bundle": {
"available": true,
"download_url": "https://mediaruntime.com/v1/jobs/job_2ee8.../bundle?token=...",
"expires_at": "2026-08-18T03:14:27Z",
"size_bytes": 13056793,
"retention_days": 7
},
"media": {
"format": "mov,mp4,m4a,3gp,3g2,mj2",
"duration_sec": 61.5,
"bit_rate": 8000000,
"video": {
"codec": "h264",
"profile": "High",
"width": 1080,
"height": 1920,
"encoded_width": 1920,
"encoded_height": 1080,
"fps": 29.97,
"rotation_deg": 90,
"is_rotated": true,
"orientation": "portrait"
},
"audio": { "codec": "aac", "sample_rate_hz": 48000, "channels": 2, "layout": "stereo" },
"streams": { "video": 1, "audio": 1, "other": 0 }
},
"metadata": { "asset_id": "asset_0426", "media_type": "video" },
"error": null,
"completed_at": "2026-08-11T03:14:53Z"
}requested 是提交作业的 API 密钥的层。 required是工作实际需要的,effective是它运行的车道,billed是你被收费的。运行标准工作的高级钥匙显示 requested: premium 和 billed: standard — 您需要支付工作费用,而不是钥匙费用。media 报告 MediaRuntime 在提交时探测输入时在您的输入中发现的内容 — 与决定是否接受作业的探测相同。当作业因不兼容的配对而被拒绝时,这解释了原因:发送到图像输出的 MP3 显示 streams.video: 0,而发送到帧输出的静态图像没有 duration_sec。注意 video.width/height 是应用了旋转的显示尺寸,因此纵向手机夹的读数为 1080x1920,即使 encoded_width/encoded_height 为 1920x1080。每个字段都是可选的:缺少一个字段意味着探测器没有报告它,永远不会为零。GET /v1/jobs/{job_id}/moderation 只返回判定,因此轮询决策的客户端无需每次获取计费和 bundle 详情。响应包含 verdict、每项检查的 decision 与 confidence,以及升级的 likelihoods。标记为 review_only 的检查仅供参考:它可以产生 review 判定,但不能单独阻止内容。当作业存在但从未请求内容审核时,端点返回 **404**;空的成功响应会与“已审核但未发现问题”无法区分。每项决策的阈值不公开。GET /v1/jobs/{job_id}/media-report 返回 media_report_v1 文档,而不下载捆绑包。 report 内联携带;异常大的报告不会内联存储,然后响应将 report 设置为 null,而 download_url 仍然可以解析,因此请处理两者。当作业没有报告时返回404。| 领域 | 类型 | 注释 |
|---|---|---|
| 状态 | 字符串 | QUEUED、正在处理、COMPLETED、FAILED 或已拒绝。 |
| 层 | 对象 | 请求/必需/有效/计费,以及需要保费的原因。 |
| 用法.units_total | 整数 | 工作的计费单位。 |
| 计费 | 对象 | 货币、单价以及预计与最终单位和金额。 |
| 捆绑包.download_url | 字符串 | 作业范围内、即将到期的捆绑包 URL。仅限单一作业端点。 |
| 媒体 | 对象 | 输入的实际内容是什么,如提交时所探测的那样。旧作业上为空。 |
| 媒体.视频.宽度/高度 | 整数 | 显示尺寸,已应用旋转。 |
| 媒体.duration_sec | 数量 | 没有静态图像,没有时间线。 |
| metadata | 对象 | 您提交的 元数据 对象已回显。 |
| 错误 | 字符串 | 填充到 FAILED 或 REJECTED;否则为 null。 |
投票规则
- 更喜欢 webhook;仅当您无法收到邮件时才进行轮询。
- 带有 next_cursor 的页面,从不存在偏移量 — 行随着作业更新而移动。
- 您不拥有的职位 ID 返回 404,与不存在的职位 ID 相同。
- 列表行省略捆绑包 URL;获取要下载的单个作业。
- 在民意调查之间退后一步。终端状态不会改变。
预付费、随用随付、按实际使用情况结算。
添加卡、为钱包充值并提交工作,无需定期订阅。 MediaRuntime 在执行之前保留估计值,并在作业达到最终状态时结算最终费用。
| 计划 | 起始使用价 | 最低充值金额 | 默认自动充值 |
|---|---|---|---|
| Standard Pay-As-You-Go | 来自$0.02 | $20.00 | $20.00 在 $2.00 可用 |
| Premium Pay-As-You-Go | 来自$0.05 | $60.00 | $60.00 在 $5.00 可用 |
billing 和 usage 字段进行对账。钱包规则
- 可用信用等于钱包信用减去为运行作业预留的资金。
- 可用信用不足,执行前返回 HTTP 402。
- 自动充值是可选的,并且需要存档卡。
- 当不允许升级时,仅 Premium 请求将返回 403。
重试传输失败,而不是无效工作。
大多数 API 错误使用顶级详细信息字段。它可能是字符串或结构化对象,因此请记录整个响应以及相关 ID,但切勿记录 API 密钥。
| 状态 | 含义 | 您的集成应该做什么 |
|---|---|---|
| 400 | 该请求在逻辑上无效或估算器拒绝了它。 | 修复请求;不要重试不变。 |
| 401 | API 密钥无效、过期或已撤销。 | 纠正或轮换钥匙;不要盲目重试。 |
| 第402章 | 帐户、钱包或计费预检无法涵盖该作业。 | 首先为钱包充值或解决计费问题。 |
| 第403章 | 计划、角色或功能门不允许该请求。 | 改变计划/要求;不要重试不变。 |
| 第413章 | HTTP 请求正文超过 2 MiB。 | 单独上传媒体并仅发送 URL。 |
| 第422章 | JSON 与 API 架构不匹配。 | 更正命名字段。 |
| 第429章 | 帐户或密钥受到速率限制。 | 使用指数退避和抖动重试。 |
| 500/502/503 | 暂时的平台依赖性失败或通道已暂停。 | 通过退避安全重试;保留您的相关性 元数据。 |
{
"detail": "Insufficient wallet balance for this job"
}大多数集成所需的小表面。
以下所有服务器到服务器端点均使用 X-API-Key。标记化捆绑包 URL 是唯一的例外,因为它带有自己的短期、工作范围的凭证。
| 方法 | 路径 | 目的 |
|---|---|---|
| 后处理 | /v1/upload-url | 当您还没有可获取的媒体 URL 时,可以选择创建 15 分钟的上传目标。 |
| 后处理 | /v1/jobs | 对单输入或批量媒体作业进行排队。 |
| 获取 | /v1/jobs/{job_id} | 一项作业的状态、层决策、使用情况、计费和捆绑链接。 |
| 获取 | /v1/jobs | 列出您的职位,最新的在前。支持 ?status= 和光标分页。 |
| 获取 | /v1/jobs/{job_id}/moderation | 获取单个作业的内容审核判定。未请求内容审核时返回 404。 |
| 获取 | /v1/jobs/{job_id}/media-report | 法医媒体报道了一份工作。 404 当未请求 media_report_v1 时。 |
| 获取 | /v1/jobs/{job_id}/bundle?token=... | 将工作范围的代币兑换为捆绑包;不需要 API 密钥。 |
| 后处理 | /v1/jobs/{job_id}/retry-webhook | 重试您拥有的作业的终端 Webhook。 |
| 后处理 | /v1/account/watermark-logo/upload-url | 为帐户 PNG 徽标创建上传目标。 |
| 后处理 | /v1/account/watermark-logo/confirm | 确认徽标及其位置设置。 |