トーキングアバターAPI：肖像画像と音声から話す動画クリップを作る

spicyapi/talking-avatar-v1/talking-avatar を使うと、肖像画像1枚と3〜60秒のMP3またはWAV音声から、話しているMP4を作れます。録音が言葉とタイミングを決め、肖像が顔と場面を決めます。料金は返された1秒あたり$0.018で、秒単位に切り上げ、最低3秒です。4〜5秒のセリフなら約1分で生成されます（60秒の録音はそれより長くかかります）。出力は約0.2メガピクセル、25 fpsとコンパクトなので、カードやフィード、チャット画面向きで、フルスクリーンのHDプレゼンターには向きません。HD画質や長い音声が必要な場合は、末尾のKling Avatar 2.0の項を参照してください。実際の出力はモデルページで聞けます。

肖像と録音を準備する

この例では、ティール色のブラウスを着た架空の成人の講座プレゼンター、Maraを使います。肖像は次の条件を満たしてください。

• 顔がはっきり1つ写り、おおむね正面を向き、均一に照明された頭から肩までの構図であること
• 口の前に手、髪、サングラス、マイクがないこと
• JPEG、PNG、WebPのいずれかで10 MB以下、最終的なプレーヤーに合わせてあごや髪の周りに余白があること

録音は90 MB以下、3〜60秒のMP3またはWAVで、声は1人、音楽や重なる話者は入れません。誤って入った無音は削ってかまいませんが、最初と最後の言葉は削らないでください。無音も課金対象の長さに含まれます。3〜60秒の範囲外のファイルは、課金される前に拒否されます。

準備ステップを描いたイラストであり、Talking Avatarのフレームではありません。

script、voice_id、language というフィールドはありません。別の言語にしたい場合は、別の音声ファイルを録音または生成し、同じ肖像を再利用します。すでに動いているプレゼンターの映像があり、音声だけを差し替えたい場合は、代わりにリップシンクのワークフローを使ってください。

入力

解像度、フレームレート、長さ、カメラを指定するフィールドはありません。16:9の写真は640×352、3:4の肖像は400×544で返ります。

ファイルは直接アクセスできるHTTPSリンクで取得できる必要があります。ページや共有リンクを指すより、アップロードしたほうが確実です。アップロードした参照ファイルは短時間で失効するので、元のファイルは手元に残してください。

料金と、見積もりが$1.08になる理由

課金されるのは、返された長さを整数秒に切り上げた値で、最低3秒です。

見積もりと、タスク作成時に確保される保留額は、60秒の上限である$1.08です。音声の長さにかかわらず同じです。クリップが完成すると、最終料金は実際の長さで確定し、残りは解放されます。タスクが失敗した場合は保留額が全額解放されます。それまでは保留額が残高と支出上限に計上されるため、残高がほとんどない場合や上限が厳しい場合は、12秒のクリップでも実行できないことがあります。見積もりを取るだけでは何も保留されません。

まずPlaygroundで試す

1. Talking Avatarのモデルページを開き、PlaygroundタブのFormビューのままにします。実行するには、残高のあるアカウントでサインインしてください。サインインすると価格が表示されます。
2. Input imageに、Maraの肖像をドロップするか、Add URLでリンクを貼り付けます。
3. Input audioに、MP3またはWAVを同じ方法で追加します。リンクよりアップロードのほうが確実です。
4. 必要なら、Promptに表情を表す短い言葉（calm and welcoming）を入力し、集合写真ならMaskを追加し、2つの録音を比べるならSeedを設定します。
5. 実行し、実際に表示するサイズで、音を出して結果を再生します。

PlaygroundはAPIと同じリクエストを送るので、ここで動く肖像と録音はコードでも動きます。ここで口の動きが読み取りにくい場合は、コードを書く前に元のファイルを直してください。

次にコードから呼び出す

Python SDKをインストール（pip install spicyapi）し、SPICY_API_KEY を設定して、次を実行します。タスクの作成には課金が発生し、保留額は上で説明した上限の$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")

見積もり、待機、再試行、エラーについては、Python SDKリファレンスと非同期タスクのガイドを参照してください。受け付けられたタスクは取り消せないため、実行前に価格を確認してください。結果のリンクは一時的なものなので、生成したメディアを長期保存する方法で説明しているとおり、自分のコピーを保存してください。

エージェントに実行させる

アシスタントにクリップを作らせたい場合は、CLIまたはMCPサーバーを渡します。どちらも価格を表示し、有料の呼び出しの前に確認を求めます。Skillは、そのどちらの上にも指示を追加します。

• CLI。 spicyapiはターミナルから1つのタスクを実行します（npx @spicyapi/cli ならインストール不要です）。

``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 には、上と同じ input オブジェクトと、2つの spicy:// URIを入れます。

• MCPサーバー。 MCPサーバーをアシスタントに追加し、「Make Mara speak ./mara-intro.mp3 using ./mara.png with Talking Avatar.」と依頼します。spicyapi_upload_file、spicyapi_task_create（価格の確認のために停止します）、spicyapi_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-skill でAgent Skillをインストールすると、コーディングアシスタントが推測せずに最新のスキーマを読み、冪等性キーを再利用するようになります。Skill単体ではタスクを実行できないため、CLIまたはMCPと組み合わせて使ってください。

問題は元データで直す

avatar.mp4 を、実際に表示するサイズで音を出して再生し、目、顔の輪郭、生え際を元の肖像と比べてください。口が動いているだけでは、キャラクターが一貫していることの証明にはなりません。

同一人物かどうかの確認を描いたイラストです。印刷された肖像は作成した図版であり、アバターのフレームではありません。

コンテンツのルールと、別のモデルを選ぶ場合

SpicyAPIはTalking Avatar v1に安全性チェックを追加しておらず、何が返るかはモデル自身が決めます。検出できない顔や拒否された画像は、タスクの失敗になります。使えるのは、架空の肖像か、同意した成人の肖像だけです。

Kling Avatar 2.0も肖像と音声を受け付け、720p（1秒あたり$0.0512）または1080p（1秒あたり$0.1024）で、最長約5分のクリップを作れます。こちらはフィルター付きのモデルで、露骨な肖像は拒否されるため、成人向けのキャラクターではなく、プレゼンターやブランドのクリップに向いています。カードサイズの短くて安いクリップにはTalking Avatar v1を、フルサイズで鮮明に見せたい場合や1分を超える場合にはKling Avatar 2.0を選んでください。