Mit spicyapi/talking-avatar-v1/talking-avatar machen Sie aus einem Porträt und 3–60 Sekunden MP3- oder WAV-Sprache einen sprechenden MP4-Clip. Die Aufnahme liefert Worte und Timing, das Porträt Gesicht und Szene. Der Preis beträgt 0,018 $ pro zurückgegebener Sekunde, aufgerundet und mit drei Sekunden Minimum; eine Zeile von 4–5 Sekunden ist in etwa einer Minute gerendert (eine 60-Sekunden-Aufnahme braucht länger). Das Ergebnis ist kompakt, etwa 0,2 Megapixel bei 25 fps, und passt damit zu einer Karte, einem Feed oder einem Chatfenster, nicht zu einem HD-Moderator im Vollbild. Brauchen Sie HD oder längeres Audio, lesen Sie am Ende die Option Kling Avatar 2.0. Ein echtes Ergebnis können Sie auf der Modellseite anhören.
Porträt und Aufnahme vorbereiten
Das Beispiel nutzt Mara, eine fiktive erwachsene Kurssprecherin in türkisfarbener Bluse. Das Porträt sollte so aussehen:
- ein klares Gesicht, ungefähr frontal zur Kamera, gleichmäßig beleuchtet, Kopf und Schultern;
- ohne Hände, Haare, Sonnenbrille oder Mikrofon vor dem Mund;
- JPEG, PNG oder WebP, höchstens 10 MB, mit Platz um Kinn und Haare für Ihren späteren Player.
Die Aufnahme ist eine MP3- oder WAV-Datei mit höchstens 90 MB und 3–60 Sekunden, mit einer Stimme und ohne Musik oder sich überlagernde Sprecher. Entfernen Sie versehentliche Stille, aber nicht das erste oder letzte Wort: Stille zählt zur bezahlten Länge. Dateien außerhalb von 3–60 Sekunden werden vor jeder Abbuchung abgelehnt.
Illustration des Vorbereitungsschritts, kein Talking-Avatar-Bild.
Es gibt kein Feld script, voice_id oder language. Für eine andere Sprache nehmen Sie eine andere Audiodatei auf oder erzeugen sie und verwenden dasselbe Porträt weiter. Wenn Sie bereits Aufnahmen eines sich bewegenden Sprechers haben und nur die Sprache ersetzen wollen, nutzen Sie stattdessen den Lip-Sync-Workflow.
Eingaben
| Eingabe | Verwendung in diesem Beispiel |
|---|---|
image_url | Pflicht: Maras freigegebenes Porträt |
audio_url | Pflicht: die exportierte Aufnahme |
prompt | Optional: calm and welcoming; nur für den Ausdruck, er ändert weder, wer spricht, noch den Ort |
mask_url | Bei einer Person weglassen. Für ein Gruppenporträt ein gleich großes Schwarz-Weiß-Bild mit Weiß über dem Sprecher |
seed | Optionale Ganzzahl, 0–2147483647. Festlegen, um zwei Aufnahmen am selben Porträt zu vergleichen; weglassen für einen neuen Durchlauf |
Es gibt kein Feld für Auflösung, Bildrate, Dauer oder Kamera. Ein 16:9-Foto kommt mit 640×352 zurück, ein 3:4-Porträt mit 400×544.
Ihre Dateien müssen über einen direkten HTTPS-Link erreichbar sein. Hochladen ist zuverlässiger als der Verweis auf eine Seite oder einen Freigabelink; hochgeladene Referenzen sind nur kurz gültig, bewahren Sie daher Ihre Originale auf.
Was es kostet und warum das Angebot 1,08 $ lautet
Abgerechnet wird die zurückgegebene Dauer, aufgerundet auf ganze Sekunden, mindestens drei Sekunden:
| Zurückgegebene Dauer | Abgerechnete Sekunden | Endgültiger Preis |
|---|---|---|
| 3 Sekunden | 3 | 0,054 $ |
| 12,2 Sekunden | 13 | 0,234 $ |
| 60 Sekunden | 60 | 1,08 $ |
Das Angebot und die beim Erstellen der Aufgabe reservierte Summe gelten für das 60-Sekunden-Maximum: 1,08 $, unabhängig von der Länge Ihres Audios. Ist der Clip fertig, wird die endgültige Summe nach der tatsächlichen Dauer abgerechnet und der Rest freigegeben; bei einer fehlgeschlagenen Aufgabe wird die gesamte Reserve freigegeben. Bis dahin zählt die Reserve auf Ihr Guthaben und Ihre Ausgabenlimits an, sodass ein fast leeres Guthaben oder ein knappes Limit sogar einen 12-Sekunden-Clip blockieren kann. Ein Angebot allein reserviert nichts.
Zuerst im Playground ausprobieren
- Öffnen Sie die Talking-Avatar-Modellseite und bleiben Sie im Tab Playground in der Ansicht Form. Zum Ausführen melden Sie sich mit einem aufgeladenen Konto an; der Preis erscheint, sobald Sie angemeldet sind.
- Ziehen Sie unter Input image Maras Porträt hinein oder fügen Sie den Link mit Add URL ein.
- Fügen Sie unter Input audio die MP3- oder WAV-Datei auf dieselbe Weise hinzu. Hochladen ist zuverlässiger als ein Link.
- Tragen Sie optional unter Prompt ein paar Worte zum Ausdruck ein (
calm and welcoming), fügen Sie für ein Gruppenporträt eine Mask hinzu oder setzen Sie einen Seed, um zwei Aufnahmen zu vergleichen. - Starten Sie den Lauf und spielen Sie das Ergebnis mit Ton in der Größe ab, in der Sie es anzeigen werden.
Der Playground sendet dieselbe Anfrage wie die API. Ein Porträt und eine Aufnahme, die hier funktionieren, funktionieren also auch im Code. Ist der Mund hier schwer zu erkennen, verbessern Sie die Quelldateien, bevor Sie Code schreiben.
Dann per Code aufrufen
Installieren Sie das Python-SDK (pip install spicyapi), setzen Sie SPICY_API_KEY und führen Sie Folgendes aus. Das Erstellen der Aufgabe wird berechnet, und die Reserve ist die oben beschriebene Obergrenze von 1,08 $.
import shutil
import urllib.request
import uuid
from spicyapi import SpicyClient, output_assets
client = SpicyClient() # reads SPICY_API_KEY from the environment
portrait = client.upload_file("./mara.png") # local files become spicy:// URIs
speech = client.upload_file("./mara-intro.mp3")
task = client.create_task(
model="spicyapi/talking-avatar-v1/talking-avatar",
input_data={
"image_url": portrait["uri"],
"audio_url": speech["uri"],
"prompt": "calm and welcoming",
"seed": 42,
},
idempotency_key=str(uuid.uuid4()), # new key per new request; reuse only to retry the same one
)
final = client.wait_for_terminal(task["taskId"])
if final["state"] != "succeeded":
raise RuntimeError(f"Task {task['taskId']} ended as {final['state']}")
url = output_assets(final)[0]["url"]
request = urllib.request.Request(url, headers={"User-Agent": "avatar-example/1.0"}) # default Python clients can get a 403
with urllib.request.urlopen(request, timeout=60) as response, open("avatar.mp4", "wb") as target:
shutil.copyfileobj(response, target)
print("Saved avatar.mp4")Angebote, Warten, Wiederholungen und Fehler sind in der Python-SDK-Referenz und im Leitfaden zu asynchronen Aufgaben beschrieben. Eine angenommene Aufgabe lässt sich nicht abbrechen, prüfen Sie den Preis also vor dem Start. Ergebnislinks sind nur befristet gültig, speichern Sie daher eine eigene Kopie, wie in Erzeugte Medien dauerhaft speichern beschrieben.
Oder von einem Agenten ausführen lassen
Soll ein Assistent die Clips erzeugen, geben Sie ihm die CLI oder den MCP-Server. Beide zeigen den Preis und bitten vor einem kostenpflichtigen Aufruf um Bestätigung. Der Skill ergänzt beides um Anweisungen.
- CLI.
spicyapiführt eine Aufgabe im Terminal aus (npx @spicyapi/clifunktioniert ohne Installation):
``bash spicyapi files upload ./mara.png # prints a spicy:// URI; repeat for the audio spicyapi tasks create --model spicyapi/talking-avatar-v1/talking-avatar \ --input-file input.json --wait ``
input.json enthält dasselbe input-Objekt wie oben, mit den beiden spicy://-URIs.
- MCP-Server. Fügen Sie den MCP-Server Ihrem Assistenten hinzu und fragen Sie dann: „Make Mara speak ./mara-intro.mp3 using ./mara.png with Talking Avatar.“ Er ruft
spicyapi_upload_fileauf, dannspicyapi_task_create(das für Ihre Preisbestätigung anhält) und danachspicyapi_task_wait.
``json { "mcpServers": { "spicyapi": { "command": "npx", "args": ["--yes", "--package=@spicyapi/mcp", "spicyapi-mcp"], "env": { "SPICY_API_KEY": "YOUR_SPICY_API_KEY" } } } } ``
- Skill.
npx skills add spicyapi-ai/spicy-skillinstalliert den Agent Skill, der einem Coding-Assistenten beibringt, das aktuelle Schema zu lesen und Idempotency-Keys wiederzuverwenden, statt zu raten. Er kann Aufgaben nicht selbst ausführen, nutzen Sie ihn daher mit der CLI oder MCP.
Probleme an der Quelle beheben
Spielen Sie avatar.mp4 mit Ton in der Größe ab, in der Sie es anzeigen werden, und vergleichen Sie Augen, Gesichtsumriss und Haaransatz mit dem Quellporträt: Ein sich bewegender Mund allein beweist nicht, dass die Figur konsistent geblieben ist.
| Symptom | Nächster Schritt |
|---|---|
| Das Gesicht ist klein oder der Mund schwer zu erkennen | Die Quelle auf Kopf und Schultern mit sichtbarem Kinn zuschneiden und erneut senden |
| Die Sprache klingt gehetzt oder falsch ausgesprochen | Neu aufnehmen; ein Stimmungs-Prompt behebt weder Worte noch Tempo |
| Musik oder mehrere Stimmen trüben die Sprache | Eine saubere Aufnahme mit einer Stimme exportieren und Musik erst nach der Animation hinzufügen |
| In einem Gruppenporträt spricht die falsche Person | Eine Maske in exakt der Porträtgröße hinzufügen, Weiß über dem Sprecher |
| Gleichbleibender Audioversatz nach dem Schnitt | Das heruntergeladene Original mit Ihrem Export vergleichen und die Tonspur-Synchronität im Schnitt korrigieren |
| Seltsame Mund- oder Zahnbewegung bei einer Phrase | Ein klareres Porträt oder eine langsamere Lesung dieser Phrase versuchen |
Illustration der Identitätsprüfung; die gedruckten Porträts sind konstruierte Grafiken, keine Avatar-Bilder.
Inhaltsregeln und wann ein anderes Modell passt
SpicyAPI ergänzt bei Talking Avatar v1 keine Sicherheitsprüfung, und das Modell selbst entscheidet, was zurückkommt; ein Gesicht, das es nicht erkennt, oder ein abgelehntes Bild lässt die Aufgabe fehlschlagen. Verwenden Sie nur fiktive Porträts oder Porträts einwilligender Erwachsener.
Kling Avatar 2.0 nimmt ebenfalls ein Porträt und Audio entgegen, in 720p (0,0512 $ pro Sekunde) oder 1080p (0,1024 $ pro Sekunde), mit Clips bis zu etwa fünf Minuten. Es ist ein gefiltertes Modell: Explizite Porträts werden abgelehnt, es eignet sich also für Sprecher- und Markenclips, nicht für erwachsenenorientierte Figuren. Wählen Sie Talking Avatar v1 für kurze, günstige Clips in Kartengröße und Kling Avatar 2.0, wenn der Clip in voller Größe scharf aussehen oder länger als eine Minute laufen muss.
