Video Translator API

PopNow 出品

配成 28 種語言並附字幕，按分鐘計費

popnow/video-translator-v1/video-translate

影片翻譯

在 POST /jobs/createTask 把模型名稱填成 popnow/video-translator-v1/video-translate 就能呼叫，US$0.005 起。

模型名稱popnow/video-translator-v1/video-translate

端點POST https://api.popnow.ai/api/v1/jobs/createTask

# 1. Create the task. Keep the Idempotency-Key if you retry after a network error.
export IDEMPOTENCY_KEY="$(uuidgen)"
curl -X POST https://api.popnow.ai/api/v1/jobs/createTask \
  -H "Authorization: Bearer $POPNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
  "model": "popnow/video-translator-v1/video-translate",
  "input": {
    "video_url": "https://media.popnow.ai/effects/flower-bloom-1abd6efb.mp4",
    "target_language": "en",
    "source_language": "auto"
  }
}'

# 2. Copy data.taskId from the response, then poll until state is succeeded, failed, canceled or expired.
TASK_ID="TASK_ID_FROM_RESPONSE"
curl "https://api.popnow.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
  -H "Authorization: Bearer $POPNOW_API_KEY"

// Node 18+ (or any runtime with fetch). Keep the API key on your server.
const BASE = "https://api.popnow.ai/api/v1";
const headers = { Authorization: `Bearer ${process.env.POPNOW_API_KEY}` };
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

async function call(path, init = {}) {
  const res = await fetch(BASE + path, { ...init, headers: { ...headers, ...init.headers } });
  const body = await res.json();
  if (body.code !== 200) throw new Error(`${body.code} ${body.msg}`);
  return body.data;
}

const { taskId } = await call("/jobs/createTask", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Idempotency-Key": crypto.randomUUID() },
  body: JSON.stringify({
    "model": "popnow/video-translator-v1/video-translate",
    "input": {
      "video_url": "https://media.popnow.ai/effects/flower-bloom-1abd6efb.mp4",
      "target_language": "en",
      "source_language": "auto"
    }
  }),
});

// Poll with backoff. A finished task may still be copying files: wait while an asset is pending.
let task;
for (let delay = 2000; ; delay = Math.min(delay * 1.5, 15000)) {
  await sleep(delay);
  task = await call(`/jobs/recordInfo?taskId=${taskId}`);
  const copying = (task.output?.assets ?? []).some((a) => a.pending && !a.unavailable);
  if (["succeeded", "failed", "canceled", "expired"].includes(task.state) && !copying) break;
}
if (task.state !== "succeeded") throw new Error(`${task.state}: ${task.errorMessage ?? "no detail"}`);

// Each asset has a signed url (no API key needed) that expires at expiresAt: save the file.
for (const asset of task.output.assets) console.log(asset.url);

import os, time, uuid, requests

BASE = "https://api.popnow.ai/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['POPNOW_API_KEY']}"}


def call(method, path, **kwargs):
    body = requests.request(method, BASE + path, headers={**HEADERS, **kwargs.pop("headers", {})}, timeout=30, **kwargs).json()
    if body["code"] != 200:
        raise RuntimeError(f'{body["code"]} {body["msg"]}')
    return body["data"]


task_id = call(
    "POST",
    "/jobs/createTask",
    headers={"Idempotency-Key": str(uuid.uuid4())},  # reuse it if you retry
    json={
        "model": "popnow/video-translator-v1/video-translate",
        "input": {
            "video_url": "https://media.popnow.ai/effects/flower-bloom-1abd6efb.mp4",
            "target_language": "en",
            "source_language": "auto"
        }
    },
)["taskId"]

# Poll with backoff. A finished task may still be copying files: wait while an asset is pending.
delay = 2.0
while True:
    time.sleep(delay)
    task = call("GET", "/jobs/recordInfo", params={"taskId": task_id})
    assets = (task.get("output") or {}).get("assets") or []
    copying = any(a.get("pending") and not a.get("unavailable") for a in assets)
    if task["state"] in ("succeeded", "failed", "canceled", "expired") and not copying:
        break
    delay = min(delay * 1.5, 15.0)

if task["state"] != "succeeded":
    raise RuntimeError(f'{task["state"]}: {task.get("errorMessage", "no detail")}')

# Each asset has a signed url (no API key needed) that expires at expiresAt: save the file.
for asset in assets:
    print(asset["url"])

input 依下方的 Schema 產生，原樣就能通過驗證。把提示詞和連結換成你自己的即可。

價格

選項	USD /秒
標準	US$0.005

美元計費 · 全部選項及價格：GET /models/popnow/video-translator-v1/video-translate

參數

這些欄位與請求驗證使用同一份 Schema。未列出的欄位無法通過驗證。

video_urlstring必填
要處理的影片。
範圍
字元數: 1 – … · video/mp4, video/webm, video/quicktime, video/x-m4v
target_languagestring選填
要配成的語言，必須和影片裡的語言不同。
預設值
"en"
可用值
"en""es""fr""de""it""pt""nl""sv""da""no""fi""el""ru""pl""tr""he""id""ms""vi""th""tl""sw""zh-CN""zh-TW""ja""ko""ar""hi"
source_languagestring選填
影片裡說的語言。自動辨識；有背景音樂、口音重或停頓長時手動選。
預設值
"auto"
可用值
"auto""en""zh-CN""zh-TW""yue""es""fr""de""it""pt""ru""ja""ko""ar""hi""tr""vi""th""id""ms""nl""pl""uk""sv""fi""da""no""nn""cs""sk""ro""hu""el""bg""hr""sr""sl""bs""mk""sq"+62
clone_voiceboolean選填
每位說話人用接近自己原聲的聲音重新配音。
預設值
false
keep_background_audioboolean選填
配音下保留原片的音樂與音效；關掉只回傳人聲。
預設值
true
speaker_countinteger選填
說話人數，1 到 4。留空自動辨識。
可用值
1234
glossaryarray<object>選填
固定譯法的人名與詞語，最多 100 組。
範圍
項目數: 0 – 100
巢狀欄位
- glossary[].termstring必填
  用來輔助轉錄的詞語或短語。
  範圍
  字元數: 1 – 100
- glossary[].translationstring必填
  這個詞在配音裡怎麼說。重複原詞則不翻譯。
  範圍
  字元數: 1 – 100

原始 JSON Schema

{
  "additionalProperties": false,
  "properties": {
    "clone_voice": {
      "default": false,
      "description": "Re-voice each speaker in a voice modelled on their own.",
      "type": "boolean"
    },
    "glossary": {
      "description": "Names and phrases with a fixed translation, up to 100 pairs.",
      "items": {
        "additionalProperties": false,
        "properties": {
          "term": {
            "description": "The word or phrase as it is spoken in the clip.",
            "maxLength": 100,
            "minLength": 1,
            "pattern": "^[^=]+$",
            "type": "string"
          },
          "translation": {
            "description": "How it should come out in the dub. Repeat the term to keep it untranslated.",
            "maxLength": 100,
            "minLength": 1,
            "pattern": "^[^=]+$",
            "type": "string"
          }
        },
        "required": [
          "term",
          "translation"
        ],
        "type": "object"
      },
      "maxItems": 100,
      "type": "array"
    },
    "keep_background_audio": {
      "default": true,
      "description": "Keep the original music and sound effects under the dub; off returns the translated voices only.",
      "type": "boolean"
    },
    "source_language": {
      "default": "auto",
      "description": "Language spoken in the clip. auto detects it; set it when there is music under the voice, a heavy accent or long pauses.",
      "enum": [
        "auto",
        "en",
        "zh-CN",
        "zh-TW",
        "yue",
        "es",
        "fr",
        "de",
        "it",
        "pt",
        "ru",
        "ja",
        "ko",
        "ar",
        "hi",
        "tr",
        "vi",
        "th",
        "id",
        "ms",
        "nl",
        "pl",
        "uk",
        "sv",
        "fi",
        "da",
        "no",
        "nn",
        "cs",
        "sk",
        "ro",
        "hu",
        "el",
        "bg",
        "hr",
        "sr",
        "sl",
        "bs",
        "mk",
        "sq",
        "lt",
        "lv",
        "et",
        "he",
        "fa",
        "ur",
        "ps",
        "sd",
        "bn",
        "as",
        "pa",
        "gu",
        "mr",
        "ne",
        "sa",
        "ta",
        "te",
        "kn",
        "ml",
        "si",
        "my",
        "km",
        "lo",
        "bo",
        "ka",
        "hy",
        "az",
        "kk",
        "uz",
        "tg",
        "tk",
        "mn",
        "ba",
        "tt",
        "be",
        "is",
        "fo",
        "cy",
        "br",
        "eu",
        "gl",
        "ca",
        "oc",
        "lb",
        "la",
        "mt",
        "af",
        "sw",
        "so",
        "am",
        "ha",
        "yo",
        "ln",
        "sn",
        "mg",
        "tl",
        "jw",
        "su",
        "haw",
        "mi",
        "ht",
        "yi"
      ],
      "type": "string"
    },
    "speaker_count": {
      "description": "Number of people speaking, 1 to 4. Leave it out to detect it.",
      "enum": [
        1,
        2,
        3,
        4
      ],
      "type": "integer"
    },
    "target_language": {
      "default": "en",
      "description": "Language to dub into. It must differ from the language spoken in the clip.",
      "enum": [
        "en",
        "es",
        "fr",
        "de",
        "it",
        "pt",
        "nl",
        "sv",
        "da",
        "no",
        "fi",
        "el",
        "ru",
        "pl",
        "tr",
        "he",
        "id",
        "ms",
        "vi",
        "th",
        "tl",
        "sw",
        "zh-CN",
        "zh-TW",
        "ja",
        "ko",
        "ar",
        "hi"
      ],
      "type": "string"
    },
    "video_url": {
      "contentMediaType": [
        "video/mp4",
        "video/webm",
        "video/quicktime",
        "video/x-m4v"
      ],
      "minLength": 1,
      "type": "string"
    }
  },
  "required": [
    "video_url"
  ],
  "type": "object"
}

回應、輪詢與回呼

所有模型採用相同流程：建立任務後輪詢狀態，或透過回呼接收結果。

先報價

cURL

curl -X POST https://api.popnow.ai/api/v1/jobs/quote \
  -H "Authorization: Bearer $POPNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "popnow/video-translator-v1/video-translate",
  "input": {
    "video_url": "https://media.popnow.ai/effects/flower-bloom-1abd6efb.mp4",
    "target_language": "en",
    "source_language": "auto"
  }
}'

執行前，將相同請求內容傳送至 POST /jobs/quote，即可查看預估費用與最高費用，單位為美元。報價不會執行任務或扣款。

已受理

HTTP

HTTP/1.1 202 Accepted

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task_01k3m8x9q2z4v7n5p6r8s0t1w3",
    "state": "queued"
  },
  "request_id": "req_example_create"
}

HTTP 202 表示任務已受理。我們會從 API 餘額中保留報價的最高金額，完成後按實際用量結算，實際扣款不超過保留金額，並釋放剩餘金額；任務失敗則全額釋放保留金額。

查詢狀態

cURL

curl "https://api.popnow.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
  -H "Authorization: Bearer $POPNOW_API_KEY"

每隔幾秒查詢一次並逐步拉長間隔，state 變成 succeeded、failed、canceled 或 expired 時停止。

完成的任務

JSON

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task_01k3m8x9q2z4v7n5p6r8s0t1w3",
    "model": "popnow/video-translator-v1/video-translate",
    "state": "succeeded",
    "output": {
      "assets": [
        {
          "url": "https://cdn.popnow.ai/tasks/task_01k3m8x9q2z4v7n5p6r8s0t1w3/output.mp4?signature=FROM_RESPONSE",
          "expiresAt": "2026-10-17T12:20:00Z",
          "mime": "video/mp4",
          "width": 1280,
          "height": 720,
          "durationSeconds": 5
        }
      ]
    },
    "settled": true
  },
  "request_id": "req_example_record"
}

請在 expiresAt 之前從 url 下載。之後需要新連結，請呼叫 POST /common/download-url。

驗證回呼

Node.js

import { createHash, createHmac, timingSafeEqual } from "node:crypto";
import express from "express";

const app = express();
// express.raw keeps the exact bytes that were signed; express.json would not match.
app.post("/hooks/popnow", express.raw({ type: "application/json" }), (req, res) => {
  const timestamp = req.header("X-Webhook-Timestamp");
  const signature = req.header("X-Webhook-Signature") ?? "";
  const body = JSON.parse(req.body.toString("utf8"));
  const taskId = body.data?.taskId ?? body.task_id;
  const digest = createHash("sha256").update(req.body).digest("hex");
  const expected = createHmac("sha256", process.env.POPNOW_WEBHOOK_SECRET)
    .update(`${taskId}.${timestamp}.${digest}`)
    .digest("base64");
  const ok = expected.length === signature.length && timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
  // Check the signature first, then reject anything older than five minutes.
  if (!ok || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return res.status(401).end();
  res.status(200).end(); // answer fast, then fetch the task and store its files
});

設定 callBackUrl 後，我們會傳送已完成任務的資訊。請先使用原始請求內容驗證簽章，再處理回呼內容。

上傳本機檔案

cURL

curl -X POST https://api.popnow.ai/api/v1/common/upload-url \
  -H "Authorization: Bearer $POPNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contentType": "image/png", "bytes": 482113}'

# PUT the file bytes to data.uploadUrl with every header in data.headers, then commit it:
curl -X POST https://api.popnow.ai/api/v1/files/$FILE_ID/commit \
  -H "Authorization: Bearer $POPNOW_API_KEY"
# The commit returns a popnow://f/... reference. Put it in any image, video or
# audio field of the task input instead of a public https URL.

公開的 https 連結可以直接用。本機檔案要先經過 upload-url 和 commit。