Text-to-Video-API: Integration in 10 Minuten

01

Was Text-to-Video-API hier bedeutet

"Text zu Video" deckt mehrere verschiedene Produkte ab. Einige APIs verwandeln einen kurzen Prompt in einen fünfsekündigen Filmclip. Andere animieren ein Bild, legen einen digitalen Moderator über ein Skript oder stellen Stockmaterial zusammen. TapVid übernimmt eine andere Aufgabe: Umwandlung von Quellmaterial im Besitz von Creatorn in ein strukturiertes Informationsvideo mit mehreren Szenen. In diesem Tutorial ist die Eingabe kein vager visueller Prompt. Es handelt sich um die öffentliche TapVid-API und die MCP-Seite sowie eine Zusammenfassung, die Zielgruppe, Dauer, Seitenverhältnis, Nachricht und verbotene Behauptungen definiert. Das Ausgabeziel ist ein komplettes 30-Sekunden-Informationsvideo und nicht eine isolierte Aufnahme. Für Agenturen und kleine Unternehmen bedeutet die prompte Szenenbearbeitung auch, dass eine Szene regeneriert werden kann, während der Rest intakt bleibt.

Der Ausdruck "build it in 10 Minuten" bezieht sich auf die Integration der vier REST-Operationen, die kein 10-minütiges Rendering versprechen. Die Videogenerierung ist asynchron. Der create-Endpunkt gibt sofort `202 Accepted` zurück, der Status kann für längere Zeiträume unverändert bleiben, und die Exportvorbereitung kann fortgesetzt werden, nachdem die Generierungsberichte abgeschlossen sind. Ein wahrheitsgemäßer Client trennt die Anforderungslatenz von der Generierungslatenz. Es zeigt an, dass der Auftrag angenommen wurde, speichert die ID, meldet den aktuellen Status und wird später fortgesetzt. Es ersetzt nie einen aktiven Job durch ein Duplikat, nur weil ein Browser-Tab oder eine Netzwerkverbindung verschwunden ist.

Dies ist die tatsächliche 30-Sekunden-TapVid-Ausgabe, die von der öffentlichen API- und MCP-Seite mit dem in diesem Tutorial verwendeten Briefing erstellt wurde. Wir haben das abgeschlossene Fünf-Szenen-Projekt in TapVid Studio verifiziert, das vollständige Ergebnis abgespielt und diese lokale MP4 heruntergeladen. Es beweist den Workflow von Source to-Finish-Video und die herunterladbare Ausgabe. Es verwandelt die zuvor unterbrochene REST-Umfrage nicht rückwirkend in einen abgeschlossenen REST-Benchmark.

02

Den Vertrag vor dem Code verstehen

Das aktuelle offizielle Gateway ist `https://api.tapvid.ai/api/public/v1`, und jede Anfrage verwendet `Authorization: Bearer YOUR_KEY` über HTTPS. Erstellen Sie den Schlüssel bei TapVid API Keys und setzen Sie ihn dem lokalen Code als `process.env.TAPVID_API_KEY` aus. Kodieren Sie es nicht in das Skript, das in einem Blog, Repository, Frontend-Bundle, Screenshot oder clientseitiger Anwendung angezeigt wird. Der Erstellungsablauf akzeptiert eine bis 30 Material-IDs, eine erforderliche Eingabeaufforderung, einen optionalen Titel `16:9` oder `9:16`, Dauern von `30s` bis `5m` und eine optionale Sprache. Dies sind Drahtwerte, also spielen Rechtschreibung und Zeichensetzung eine Rolle.

• Nutze die öffentliche REST-Basis der TapVid API `https://api.tapvid.ai/api/public/v1` über HTTPS.
• Key serverseitig aus `process.env.TAPVID_API_KEY` laden.
• Genau URL oder Datei pro Materialaufruf senden.
• `materialId` und nach HTTP 202 sofort `videoId` speichern.
• Nach `pollAfterSeconds` mit resumierbarem Timeout pollen.

03

Schritt 1: URL oder Datei hochladen

Beginne für die TapVid MCP API mit genau einer Quellform. Sende für eine URL JSON mit einer HTTPS-`url`. Sende für eine Datei Multipart-Formulardaten mit einer Datei von höchstens 100 MB. URL-Zeichenfolgen dürfen bis zu 4,096 Zeichen lang sein und keine internen Hosts ansprechen. Das Beispiel verwendet `https://tapvid.ai/api-mcp`, weil die Seite öffentlich, für diesen Test ausreichend stabil und eine Beschreibung des erklärten Dienstes ist. Die Upload-Antwort gibt `materialId` zurück. Behandle sie als privaten Anwendungszustand. Sie ist kein menschenlesbarer Slug und gehört weder in Analytics-Bezeichnungen noch in öffentliche Protokolle.

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" }'

Das cURL-Beispiel legt eine Umgebungsvariable fest, nur um die Anforderung leicht zu befolgen. Verwenden Sie in einem gemeinsam genutzten Computer oder einem CI-System den geheimen Speicher der Plattform, anstatt einen langlebigen Wert in einen Shell-Verlauf zu exportieren. Die JSON-Antwort sollte `materialId` und `type` enthalten. Speichern Sie beide mit dem Auftragsdatensatz, den Sie erstellen werden. Wenn der Upload mit `payload_too_large` fehlschlägt, hilft das Ändern der Erstellungsaufforderung nicht. Repariere das Material. Wenn die URL abgelehnt wird, überprüfen Sie HTTPS, Länge, Erreichbarkeit, Weiterleitungen und ob die Quelle abgerufen werden darf.

04

Schritt 2: asynchronen Videojob erstellen

Erstellen Sie das Video erst, nachdem der Quell-Upload erfolgreich war. Das erforderliche `userPrompt` kann bis zu 12.000 Zeichen enthalten, aber die Länge ist kein Ersatz für einen überprüfbaren Brief. Geben Sie das Publikum, die Quellgrenze, die beabsichtigte Dauer, das Seitenverhältnis, die Sprache, die obligatorische Reihenfolge und verbotene Ansprüche an. Das Beispiel fordert 30 Sekunden und 16:9 explizit an, anstatt sich auf automatische Entscheidungen zu verlassen. Die Antwort kommt als HTTP 202 mit `videoId`, `status` und `createdAt`. Die offizielle HTTP-Semantik-Spezifikation definiert 202 als akzeptiert zur Verarbeitung, nicht abgeschlossen. Es bedeutet nicht, dass das Video herunterladbar oder genehmigt werden kann.

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"
  }'

Halten Sie `videoId` vor dem nächsten Netzwerkaufruf. Diese eine Linie ist die wichtigste Produktionsänderung, die durch den kontrollierten Test identifiziert wurde. Ein Prozess kann nach der Erstellung und vor seiner ersten Statusantwort abstürzen. Wenn die ID nur im Speicher vorhanden ist, kann die Anwendung nicht fortgesetzt werden und kann einen zweiten bezahlten Job erstellen. Speichern Sie die ID neben Ihrer eigenen Anforderungs-ID, Material-IDs, Prompt-Version, angeforderten Einstellungen und Benutzer. Der Statusendpunkt erwartet den Abfrageparameter `video_id`, während die create-Antwort Camel-case `videoId` verwendet. Kopieren Sie die aktuellen offiziellen Drahtnamen genau, anstatt sie aus dem Gedächtnis zu normalisieren.

05

Schritt 3: speichern, pollen und herunterladen

Umfrage `GET /video/status` mit der akzeptierten ID und respektiere `pollAfterSeconds`. Die dokumentierten Terminalzustände sind `completed` und `failed`; Zwischenzustände umfassen `queued` und `running`. Der Fortschritt ist ein Bruchteil von 0 bis 1, nicht eine geschätzte verbleibende Zeit. Sobald dies abgeschlossen ist, fragen Sie erneut, ob `creditsUsed` immer noch null ist, da die Abrechnung auf die Terminal-Aktualisierung folgen kann. Dann fordern Sie `GET /video/download` mit Auflösungs-, Wasserzeichen- und Untertiteloptionen an. Die signierte `downloadUrl` läuft in etwa einer Stunde ab. Speichern Sie die dauerhafte Video-ID, nicht die signierte URL, und aktualisieren Sie die URL, wenn ein Benutzer sie erneut benötigt.

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 })

Das Node.js-Beispiel umschließt Lesungen in begrenzten Wiederholungen und schreibt die akzeptierte Video-ID vor der Abfrage auf die Festplatte. Ersetzen Sie in einem echten Dienst die lokale JSON-Datei durch eine Datenbankzeile und verwenden Sie einen Warteschlangenarbeiter. Der Helfer versucht erneut Netzwerkfehler, HTTP 429 und Serverfehler. Es versucht nicht, eine normale 400 oder 401 zu wiederholen, als ob die Zeit schlechte Argumente oder Anmeldeinformationen reparieren würde. Die 180-Zoll-Decke schafft einen klaren Endzustand für den Arbeiter. Wenn diese Obergrenze erreicht ist, behält der Code die ID bei und meldet eine wiederaufforderbare Zeitüberschreitung, anstatt eine weitere Erstellungsanfrage zu senden.

06

Was der echte REST-Test zeigte

Der REST-Test vom 7. August 2026 verwendete dieselbe Quelle, Eingabeaufforderung, 30-Sekunden-Dauer, 16:9-Verhältnis und die gleiche englische Sprache wie der MCP-Test. Der Material-Upload gab HTTP 200 in etwa 1,4 Sekunden zurück. Erstellt zurückgegebenes HTTP 202 und Warteschlange in etwa 0,3 Sekunden. Der erste Laufzustand erschien nach etwa 81 Sekunden. Bei etwa 331 Sekunden gab der Job immer noch an, mit 50 Prozent zu laufen. Der lokale Knotenprozess erhielt dann `ECONNRESET`, bevor eine TLS-Verbindung hergestellt wurde. Das war ein Umfrage-Client-Fehler, kein dokumentierter Video-Job-Fehler.

Das erste Testskript behielt die private Video-ID nur im Prozessspeicher, so dass es nach dem Beenden des Prozesses den akzeptierten Auftrag nicht fortsetzen konnte. Es wurde kein doppelter Auftrag erstellt. Der Kontonutzungszähler war bereits von 90 auf 180 Credits in den MCP- und REST-Läufen erhöht worden, was 90 Credits pro Erstellung und der genehmigten Gesamtobergrenze entspricht. Aus diesem Grund behält die endgültige Stichprobe die ID vor der Abfrage bei und gibt GET-Anforderungen einen begrenzten Wiederholungsversuch. Das ist auch der Grund, warum dieser Artikel nicht behauptet, dass der REST-Lauf in 10 Minuten eine herunterladbare Datei erzeugt hat. Die Beweise unterstützen die schnelle Annahme von Anfragen, nicht ein festes Rendering-Zeit-Versprechen.

07

Fehler ohne doppelte Kosten behandeln

Behandeln Sie Fehler entsprechend ihrer Bedeutung. `unauthorized` fordert die Überprüfung oder den Widerruf des Schlüssels auf. `invalid_request` fordert die Korrektur von Feldern auf. `payload_too_large` fordert die Reduzierung von Materialien auf. `insufficient_credits` fordert das Stoppen und das Einholen einer Autorisierung, bevor ein Limit geändert wird. `rate_limited` fordert die Honorierung von `Retry-After` auf. `internal_error` und Transportfehler können eingeschränkte Wiederholungen empfangen. `invalid_state` beim Herunterladen bedeutet normalerweise, dass die Generierung oder der Export nicht bereit ist. Eine doppelte Erstellung innerhalb von fünf Sekunden kann abgelehnt werden, aber das ist keine vollständige Idempotenzstrategie für Abstürze, die später auftreten.

08

Produktionscheckliste

Eine zuverlässige Integration braucht mehr als ein funktionierendes Happy-Path-Snippet. Speichergeheimnisse auf der Serverseite. Akzeptierte IDs atomar beibehalten. Notieren Sie Statusübergänge, Anforderungslatenz, Generierungslatenz, Credits und sichere Fehlercodes. Fügen Sie ein maximales Umfragefenster und einen wieder aufgenommenen Status hinzu. Separate Quell-Upload-Berechtigung, Generation-Spend-Berechtigung, Export-Berechtigung und Veröffentlichungsberechtigung. Aktualisieren Sie signierte URLs, anstatt sie als permanente Assets zu speichern. Testen Sie sowohl 429 als auch Netzwerk-Resets. Zeigen Sie den Benutzern den zuletzt bestätigten Status. Überprüfen Sie schließlich das generierte Erklärvideo für die Quelltreue, die tatsächliche Dauer, die Reihenfolge der Szenen, die Lesbarkeit der Untertitel, das Audio, die Rechte und die Marke vor der externen Veröffentlichung.

• Key nur serverseitig.
• IDs atomar speichern.
• Latenzen getrennt messen.
• Pollintervall und Timeout beachten.
• Reads und Writes getrennt behandeln.
• Signierte URL erneuern.
• Credits sicher protokollieren.
• Mensch prüft und veröffentlicht.

09

API für fertige Erklärvideos statt Zufallsclips

Verwenden Sie diese Text-zu-Video-API, wenn Sie genehmigte Inhalte in ein kohärentes Erklärvideo mit mehreren Szenen, Erzählung, Bewegung und einer herunterladbaren Ausgabe umwandeln müssen. Beschreiben Sie es nicht als Rohmodell-Benchmark oder versprechen Sie das visuelle Verhalten einer filmischen Prompt-to-Clip-Engine. Wenn Sie den Prompt gesprächsweise erkunden möchten, zeigt der Begleiter Claude und TapVid MCP-Tutorial dieselbe Quelle und einen Überblick über MCP. Wenn Sie eine dauerhafte Anwendungssteuerung wünschen, behalten Sie den REST-Fluss hier und überprüfen Sie vor dem Versand die aktuelle TapVid API und MCP-Übersicht.

10

Frequently asked questions