Text-to-Video API 教學：10 分鐘完成串接

01

這篇教學裡的 Text-to-Video API 是什麼

Text to video 可能指 prompt 短片、图片动画、数字人或素材拼接。TapVid 把现有内容变成多场景、结构化的信息影片。公开頁面和 brief 提供事实、受众、时长和禁止项。需要修改时，可以只重新生成一个场景并保留其余内容。

“10 分钟”指接好四个 REST 操作，不是承诺 10 分钟渲染完成。Create 返回 `202 Accepted` 后，status 和 export 仍会继续。客户端必须保存 ID，连接中断后也不能重复 create。

下方嵌入的是另一條已驗證工作流程產出的 TapVid 成片，用於展示 API 可交付的多場景結果。它不是本次 REST 測試的終態結果，因為輪詢器在觀察到終態前斷線。

02

寫程式前先看清介面契約

网关是 `https://api.tapvid.ai/api/public/v1`。API Keys 建立 Bearer key，在伺服器端用 `process.env.TAPVID_API_KEY` 读取。不要放进前端、截图或仓库。

• 使用 HTTPS REST base。
• 在伺服器端读取 `process.env.TAPVID_API_KEY`。
• 每次只传 URL 或文件一种。
• 儲存 `materialId`，HTTP 202 后立即儲存 `videoId`。
• 按 `pollAfterSeconds` 轮询并设置可恢复超时。

03

第一步：上傳公開 URL 或檔案

URL 用 HTTPS JSON，文件用不超过 100 MB 的 multipart。URL 最长 4,096 字符。返回的 `materialId` 是私有应用狀態，应立即保存。

export TAPVID_API_KEY="replace-with-your-local-secret"

curl -X POST https://api.tapvid.ai/api/public/v1/materials \
  -H "Authorization: Bearer ${TAPVID_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://tapvid.ai/api-mcp" }'

cURL 示例用于本地理解，CI 应使用 secret store。`payload_too_large` 要修改素材，URL 被拒要检查 HTTPS、长度、可访问性和重定向。

04

第二步：建立非同步影片任務

只有上傳成功后才 create。明确受众、來源、30 秒、16:9、英文、步骤和禁止声明。HTTP 202 和 `videoId` 代表已受理，不代表完成。

curl -X POST https://api.tapvid.ai/api/public/v1/video/create \
  -H "Authorization: Bearer ${TAPVID_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "materialIds": ["MATERIAL_ID_FROM_UPLOAD"],
    "userPrompt": "Create a concise 30-second English explainer for developers. Stay faithful to the supplied source and do not invent claims.",
    "title": "TapVid API developer explainer",
    "aspectRatio": "16:9",
    "duration": "30s",
    "language": "en"
  }'

下一次網路调用前先持久化 `videoId`。进程崩溃后才能恢复并防止重复建立。响应欄位是 `videoId`，查詢参数是 `video_id`。

05

第三步：持久化、輪詢並請求下載

按 `pollAfterSeconds` 查詢 status。progress 不是剩余时间。completed 后再请求 download，并在需要时刷新约一小时有效的签名 URL。

import { writeFile } from 'node:fs/promises'

const apiKey = process.env.TAPVID_API_KEY
if (!apiKey) throw new Error('TAPVID_API_KEY is required')

const base = 'https://api.tapvid.ai/api/public/v1'
const headers = { Authorization: `Bearer ${apiKey}` }

async function request(path, init = {}, { attempts = 1 } = {}) {
  let lastError
  for (let attempt = 1; attempt <= attempts; attempt += 1) {
    try {
      const response = await fetch(`${base}${path}`, {
        ...init,
        headers: { ...headers, ...init.headers },
      })
      const data = await response.json()
      if (response.ok) return { response, data }
      if (response.status !== 429 && response.status < 500) {
        const error = new Error(`HTTP ${response.status}: ${data.code ?? 'unknown'}`)
        error.retryable = false
        throw error
      }
      lastError = new Error(`retryable HTTP ${response.status}`)
    } catch (error) {
      if (error?.retryable === false) throw error
      lastError = error
    }
    if (attempt === attempts) break
    await new Promise((resolve) => setTimeout(resolve, attempt * 1000))
  }
  throw lastError
}

const { data: material } = await request('/materials', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ url: 'https://tapvid.ai/api-mcp' }),
})

const { response: createResponse, data: video } = await request('/video/create', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    materialIds: [material.materialId],
    userPrompt: 'Create a concise 30-second English explainer for developers. Stay faithful to the source.',
    title: 'TapVid API developer explainer',
    aspectRatio: '16:9',
    duration: '30s',
    language: 'en',
  }),
})

if (createResponse.status !== 202) throw new Error('Expected 202 Accepted')

// Persist before the next network call. A lost poll must not cause a duplicate create.
await writeFile('.tapvid-job.json', JSON.stringify({ videoId: video.videoId }))

let status
for (let poll = 0; poll < 180; poll += 1) {
  const result = await request(
    `/video/status?video_id=${encodeURIComponent(video.videoId)}`,
    {},
    { attempts: 4 },
  )
  status = result.data
  if (status.status === 'completed' || status.status === 'failed') break
  await new Promise((resolve) =>
    setTimeout(resolve, Math.max(status.pollAfterSeconds ?? 5, 5) * 1000),
  )
}

if (!status) throw new Error('No status received')
if (status.status === 'failed') throw new Error(status.error?.code ?? 'generation_failed')
if (status.status !== 'completed') throw new Error('Polling timeout; resume with the saved videoId')

const query = new URLSearchParams({
  video_id: video.videoId,
  resolution: '1080P',
  watermark: 'true',
  subtitle: 'false',
})
const { data: download } = await request(`/video/download?${query}`, {}, { attempts: 4 })
console.log({ status: download.status, expiresAt: download.expiresAt })

Node 示例会保存 ID，只对安全读取做有限重试。生产环境把本地 JSON 换成数据库。400 和 401 要修正，429、伺服器端和網路错误才退避重试。

06

真實 REST 測試暴露了什麼

实测上傳约 1.4 秒，建立约 0.3 秒并返回 HTTP 202。约 81 秒进入 running 50%，331 秒时仍相同，随后轮询进程在 TLS 建连前收到 `ECONNRESET`。

第一版脚本只把 ID 放在进程内存，退出后无法恢复。测试没有重复建立任務。MCP 和 REST 总用量达到 180 credits，每次 create 90。因此本文不会声称 10 分钟成片。

07

處理錯誤，但不要重複消耗

unauthorized 要修密钥，invalid_request 要修 body，insufficient_credits 要停止，rate_limited 遵守 Retry-After，網路错误只重试安全读取。丢失 create 响应后不要再建立。

08

可靠生產串接檢查清單

生产接入需要伺服器端 secret、原子保存 ID、分开测量请求和生成时延、可恢复超时、安全日志、可刷新的下載 URL，以及人工审核事实、时长、版权和品牌。

• 密钥只在伺服器端。
• 原子儲存 ID。
• 分开記錄时延。
• 遵守间隔和超时。
• 区分读取和写入。
• 刷新签名 URL。
• 不含 secret 地記錄 credits。
• 由人审核并發布。

09

用 API 做完整解說影片，而不是隨機短片

这套 API 适合把已批准内容做成连贯解释影片，不是随机电影感短片承诺。对话探索看 Claude MCP 教程，持久控制看 REST 和 API/MCP 概览。

10

常見問題