媒体生成

异步媒体生成：图像、视频、配音（TTS）、语音转文本、音乐和 3D。你需要创建任务并轮询结果。完整模型列表位于 media-models catalog；webhook、错误和计费信息位于 webhook section。

创建操作返回 202 和 { ok: true, jobId, status: "processing" }。轮询 GET /api/media/jobs/{jobId} 直到 status: "success"，然后获取 resultUrls。

# 1. create a generation job
curl https://getvibeapi.com/api/media/generate \
  -H "Authorization: Bearer $GETVIBE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1",
    "prompt": "a cat on a skateboard, slow motion"
  }'
# → {"ok":true,"jobId":"...","status":"processing"}

除了 model 和 prompt 外，还可以在 opts 中传递额外选项。可用选项取决于模型。完整的机器可读契约可通过 GET /api/model-capabilities 获取（特定模型则通过 GET /api/model-capabilities/{model} 获取）。

URL 选项（image_url、input_urls、mask_url 等）是 provider 获取的链接，因此只接受公开的 https:// 地址。这些字段中的某个字段若包含内联 data:image/...;base64,… 字符串，将被拒绝并返回 400。

要发送自己的文件，请改用匹配的 *_base64 字段：服务会存储文件字节，发布文件，并将生成的链接传递给提供商。在 input_base64 中每个请求最多支持 16 个文件。

POST /api/media/generate 和 POST /api/media/price 接受相同的请求正文，因此你可以先获取报价，然后原样提交。不存在其他顶层字段：未知字段会在两个端点上被拒绝，并返回 400 以及指明该字段的代码 unknown_field（field、fields），无论是否使用 strict。生成参数应放在 opts 中。

任何源文件都可以通过三种方式发送：作为链接（image_url、audio_url、video_url…），作为内联字节（image_base64、audio_base64、video_base64…），或作为你自己的文件在 POST /v1/files 中返回的 id。id 字段会列在每个操作的 requestJsonSchema 中，并且在严格模式下也被接受。

对于输出长度取决于所上传素材的模型——kling-ai-avatar、omnihuman-v2、omnihuman-2-0、omnihuman-v1.5、omnihuman-1-5、volcengine-lipsync（音频）、kling-motion-control、wan-animate、topaz-video-upscale、p-video-edit（视频）、lipsync-2-pro、sync-3、react-1（两个输入）——/api/media/price 和 /api/media/generate 上的 max_price_rub 预检会在服务器端测量该文件（link、data: URI、base64 或 *_file_id），并按测得的秒数计价。响应会携带 sourceSeconds（唇形同步为 outputSeconds），estimateReason 会说明时长已完成测量。如果无法读取文件，价格将沿用之前的计价依据（1 秒、目录估算值或路由最大值），并由 estimateReason 说明原因。费用为每秒费率 × 实际渲染的秒数，且绝不会超过 max_price_rub。这些模型会接受 opts.duration，但会忽略该参数，并发出 param_ignored 警告。

Create: { name, consent: true, engine, audio_url | audio_base64 } or several recordings samples: [{ audio_url } | { audio_base64 }, …] (engine: "elevenlabs" only). An ElevenLabs voice is used by voice-clone-tts and by the Voice Changer (elevenlabs-voice-changer). Appending recordings to an ElevenLabs voice is free. Every recording is downloaded and measured before the supplier is called: a refusal changes and charges nothing.

变声器和强制对齐

如果供应商的启动确认未到达，任务会保持以下状态：status: "submitting"，stage: "submission_unknown"，errorCode: "media_submission_uncertain"，failure.advice: "reconcile_first"。请继续轮询同一个 jobId，不要创建重复任务。要免费测试此路径，请使用 sandbox key 发送 POST /api/media/generate，并添加请求头 x-pv-sandbox-outcome: submission_uncertain。响应是正常的 202，并包含 jobId；轮询该任务时，前 60 秒会返回提交状态未知，之后会返回任务从未启动（failure.code: "submission_not_started"，charged: false）。不会存储任何内容、不会向供应商发送任何内容，也不会产生费用。使用普通 key 搭配此请求头会返回 400 sandbox_outcome_requires_sandbox_key。

与其余生成请求使用相同的端点：将 STT 模型名称放入model，将prompt留为空字符串，并在opts.audio_url中传入录音。转录文本会在GET /api/media/jobs/{id}的resultText中返回；resultUrls保持为空，因为转录不会生成文件。

# speech-to-text: create the job, then read the transcript
curl https://getvibeapi.com/api/media/generate \
  -H "Authorization: Bearer $GETVIBE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "whisper-large-v3-turbo",
    "prompt": "",
    "opts": {
      "audio_url": "https://example.com/meeting.mp3",
      "language_code": "en"
    }
  }'
# → {"ok":true,"jobId":"JOB_ID","status":"processing","priceRub":0.03}

curl https://getvibeapi.com/api/media/jobs/JOB_ID \
  -H "Authorization: Bearer $GETVIBE_API_KEY"
# → {"status":"success","resultText":"the transcribed text…","resultUrls":[],"priceRub":0.03}

模型

• whisper-large-v3-turbo — 每分钟音频 $0.00025。价格最低、速度最快，支持 99 种语言。
• nemotron-asr-multilingual — 每分钟 $0.00025。NVIDIA 多语言 ASR，可自动添加标点。
• whisper-large-v3 — 每分钟 $0.000563。完整 Whisper：比 turbo 慢，但对含噪音频更准确。
• universal-2 — 每分钟 $0.003125。
• speech-to-text — 每分钟 $0.01（ElevenLabs Scribe）。支持说话人分离和音频事件标签。

参数

格式和限制

接受 mp3、wav、m4a/mp4、flac、ogg/opus 和 webm。文件大小最大为 25 MB，大约相当于 26 分钟的 128 kbps mp3，或数小时的 opus 语音。任何更大的文件都会立即被拒绝，并返回明确的消息，不会产生费用；请改为拆分录音。

为避免轮询，请在仪表板中注册一个地址 mediaWebhookUrl。任务完成时（成功或错误），服务会对带有 JSON 请求体的 POST 最多尝试投递五次：

// POST to your mediaWebhookUrl when a job finishes
{
  "jobId": "...",
  "status": "success",            // or "fail"
  "model": "veo-3.1",
  "kind": "video",                // image | video | audio | music | 3d
  "resultUrls": ["https://getvibeapi.com/api/media/file/..."],
  "failMsg": null,
  "createdAt": "2026-06-17T10:00:00.000Z"
}

来自 resultUrls 的生成结果 URL（图像、视频、音频或 3D 模型）。请按服务返回的方式使用它：无需 API key 即可打开，并可在 <img>、<video> 或浏览器中使用。提供商信息会被隐藏：上游地址在服务器端解析，客户端永远不会看到。

# The signed URL is returned in resultUrls of the /api/media/jobs/{id} response
# or in the webhook body. Opens directly in the browser / <img> — no key needed.
https://getvibeapi.com/api/media/file/JOB_ID/0?sig=HMAC_SIGNATURE