Pro API: Multi-Ref Video用キャラクター作成

キャラクターとは、1枚の写真から作成された同一人物(またはクリーチャー)の7つのビューをまとめたシートで、character_idに紐付けて保存されます。Multi-Ref Videoがクリップ内で人物を認識するために使用するもので、それらのビューがトレーニング不要で本人の特徴を保持します。 Face swapでも使用され、あなた自身の動画内の人物をキャラクターと差し替えることができます。

アプリで作成したキャラクターはすでに利用可能です。同じライセンス、同じ一覧で管理されます(アプリからのキャラクターを参照)。ロケーション、オブジェクト、動物も同様の方法で保存され、あなたが提供した画像をもとに同じクリップで使用できます(ロケーション、オブジェクト、動物を参照)。

7つのビュー

ロールビュー
1バスト、正面、ニュートラルな表情
4全身、正面
5全身、背面
6全身、横向き(キャラクターが画像の左方向を向く)
7顔のクローズアップ、正面
8衣装のクローズアップ(胸から膝まで)
9足のクローズアップ(衣装に合わせて靴を履いた状態または素足)

各ビューは個別に生成されます。他のビューを反転して作成するものは一切ありません。ロール2と3(斜めのバスト)は2026年10月21日以降作成されなくなりました。それ以前に作成したキャラクターには残り、読み取り(ビューのファイル、views一覧)はできますが、やり直しはできません(400 invalid_role)。

キャラクターを作成する

POST /characters(権限: images)。処理は非同期で行われます。

json
{ "name": "Lea", "kind": "woman", "image_b64": "<the photo>", "photo_role": "bust" }
フィールド型内容
name文字列、1〜40文字キャラクターのファーストネーム
kind文字列woman、man、または英語で記述したクリーチャー(baby dragonなど)。指示文の代名詞を設定するもので、「they」にはなりません。
image_b64base64写真: 鮮明で1人のみ写っていること、長辺1024px以上、12MB以内、JPEG・PNG・WebP形式
photo_rolebust(デフォルト)またはfull_bodyバストショット(ビュー1になる)または全身ショット(ビュー4になる)
outfit英語テキスト、任意写真がバストの場合、全身ビューの衣装(a red leather jacket and black jeansなど)。バストに写らない下半身の衣装です。写真が全身の場合は写真が優先され、衣装は適用されません

レスポンス202は、statusがpendingでcost_estimateを含むキャラクターオブジェクトです。写真はそのロールのビューになり、そのまま保持されます(衣装を着せ替えることはありません)。サーバーが残り6つを2〜5分で、アプリと同じ方法で生成します。体(背面、横向き、衣装、足)は全身ビューから、顔のクローズアップはバストから作られます。バストの写真は全身ビューに拡張され(outfitがあればその衣装で)、全身の写真からはトリミングでバストが作られます。

料金: 生成されたビュー1つにつき1クレジット、つまり6クレジットで、outfitの有無は関係ありません。失敗したビューは課金されません。POST /characters/quoteで事前に料金を確認できます。

同じ作成リクエストの再送。 応答前に接続が切れた場合や、エージェントの待機が中断された場合も、サーバーはキャラクターの作成を続けます。同じリクエスト(同じ写真、name、kind、photo_role、outfit)を再送すると、すでに作成されたキャラクターが existing: true、cost_estimate 0 で返され、二重に課金されることはありません。新しいキャラクターが作成されるのは、最初のキャラクターの生成ビューがすべて失敗した場合だけです。一部のビューが失敗した場合は、1つずつやり直せます(redo)。同一のリクエストが同時に2つ届いた場合、2つ目は 409 character_busy を受け取ります。数秒後に再送してください。

進捗確認、ビュー確認、やり直し

GET /characters/{id}で現在の状態を確認できます。

status意味
pendingビューを生成中
ready7つのビューがすべて揃っている
partial一部のビューが欠けているか失敗している
failed、empty使用可能なビューがない
json
{
  "character_id": "chr_8f3a...",
  "name": "Lea",
  "kind": "woman",
  "origin": "api",
  "status": "ready",
  "progress": { "ready": 7, "total": 7 },
  "views": [
    { "role": 1, "name": "bust_front", "status": "ready", "file_url": "https://api.tendre.ai/pro/v1/characters/chr_8f3a.../views/1/file" }
  ],
  "expires_at": "2026-10-19T18:02:11.000Z"
}
  • 最初のレンダリング前にビューを確認してください。 GET /characters/{id}/views/{role}/fileで画像を取得できます。全身ビュー(4、5、6)は2Kの1024 x 2048、バストとクローズアップは832 x 1216(足は1216 x 832)で生成され、PNG形式(2.9 MBを超える場合はJPEG形式)です。写真から作られたビューは元のサイズのまま(最大2048 px)です。作成済みのビューはそのままのサイズで残り、やり直したビューはこのサイズで生成されます。失敗したビューや向きがおかしい横向きビューがあると、すべての動画で本人らしさが損なわれます。
  • ビューのやり直し: POST /characters/{id}/views/{role}/redo、1クレジット。その出発点(全身ビューまたはバスト)から新たに生成します。元の写真から作成されたビュー(photo_view)は、outfitの有無にかかわらずやり直しできません。アプリで1枚の画像として取り込んだシート(シート全体をそのまま保持)は、ビューごとに作り直せません(409 single_image_sheet)。
  • やり直すビューへのガイド指定: APIで作成したキャラクター、またはAPIで追加したシートの場合、やり直しのリクエストボディにinstruction(200文字以内、英語)を追加できます(アプリ作成のキャラクターには409 app_characterが返ります)。このフィールドは、義肢の向きや特定のディテールの有無など、そのビューでキャラクターのどの部分をどのように見せるかを指定するものです。衣装、髪型、ポーズ、背景、表情を変えるためのものではありません。命令形で記述してください(状態の説明はエンジンに無視されます): "Put the robotic arm on her left side only, remove any second robotic arm." 背面ビュー(5)では、両方の言い方で向きを示してください: "her left arm, which appears on the left side of the image when seen from behind" 料金は同じく1クレジットです。
  • ビューへの独自画像のアップロード: APIで作成したキャラクター、またはAPIで追加したシート(?sheet=)に対して、PUT /characters/{id}/views/{role}にimage_b64(作成時の写真と同じルール: 長辺1024px以上、12MB以内、JPEG・PNG・WebP)を送信します。無料で、何も生成されません。その画像はそのまま保持され、実際の写真として扱われます。その後やり直すビューは、作成時と同じルールでこの画像から作られます(背面、横向き、衣装と足のクローズアップは全身ビューから、顔のクローズアップはバストから)。
  • 一覧取得: GET /charactersでアプリのキャラクターを含むすべてのキャラクターと上限値maxを返します。
  • 削除: DELETE /characters/{id}でキャラクターとそのビューをすべて削除します。

アプリ内(バージョン0.8.6以降): APIまたはMCPで作成したキャラクターは、アプリのMy characters画面に同じライセンスで表示され、名前とビューがアプリで作成したものと同様に確認できます。アプリでビューをやり直すと、オンラインのビュー(Multi-Ref Videoが読み込むビュー)が置き換えられます。アプリで削除すると、こちらでも完全に削除されます(アプリは事前に確認を求めます)。character_idを保持するパイプラインでは、アプリでキャラクターを削除した後に404 unknown_characterが返ることを想定してください。

アプリからのキャラクター

アプリのMy characters画面で作成したキャラクターは、GET /charactersにoriginがappとして表示され、他のキャラクターと同様にMulti-Ref Videoで使用できます。アプリでは、キャラクターに複数のシート(衣装やムードなど)を持たせることができます。sheet_idで使用するシートが決まり(デフォルトは最新のもの)、sheetsで一覧を取得できます。また、ビューのファイル取得やビューのやり直し時に?sheet=<id>で別のシートを指定できます。Multi-Ref Videoクリップでは、characters[].sheet_idでシートを選択します。アプリがキャラクターのnameとkindを送信すると(アプリ0.9.1以降)、アプリのプロフィールの値が入ります。それ以前は両方ともnullです。kindがまだnullのアプリのキャラクターのビューをやり直す場合は、リクエストボディにkindを指定してください。

ボイス: has_voiceは、キャラクターのプロフィールのボイスがオンラインにあるかどうかを示します。アプリがキャラクターと一緒に送信し、Face swapとMulti-Ref Videoはデフォルトでそれを使います。

キャラクターに衣装を追加する

POST /characters/{id}/sheetsは、既存のキャラクターに新しいシート(衣装やルック)を追加します。APIで作成したキャラクターにも、アプリで作成したキャラクター(アプリのプリセットを含む)にも使えます。キャラクターの他のシートはそのまま残ります。レスポンス202は新しいシートを含むキャラクターで、そのsheet_id(api-で始まります)、sheet_name、sheet_outfit、sheet_origin: "api"、cost_estimateが含まれます。

json
{ "name": "steampunk", "outfit": "brass aviator goggles, long black leather coat", "kind": "woman",
  "views": { "1": "<base64>", "4": "<base64>" } }
フィールド型内容
name文字列、1〜40文字シートの名前
outfit英語テキスト、最大700文字着せる衣装。viewsがない場合は必須
viewsオブジェクト、ロール"1"、"4"〜"9": base64の画像用意済みのビュー。ビューのアップロードと同じルールです
generatetrue(デフォルト)またはfalse足りないロールを生成するか、生成しないか
from_sheet_id文字列、任意viewsがない場合に元にするシート
kind文字列アプリで作成し、GET /charactersのkindがまだnullのキャラクターの場合のみ。作成時と同じです
  • viewsありの場合: 送ったビューはそのまま保存され、無料です。足りないロールは作成時と同じルールで、送った全身ビューとバストをもとに生成され、1ビューにつき1クレジットです。どちらもない場合はviewsなしと同じです。generate: falseでは何も生成しません。
  • viewsなしの場合: キャラクターの全身ビュー(ない場合はバスト。from_sheet_idで別のシートから始められます)に衣装を着せます。その結果が新しいシートの全身ビューになり、残り6つのビューはそこから作られます。生成は7ビューで7クレジットです。料金はcost_estimateで確認できます。元のシート(from_sheet_id、または既定のシート)がこのような1枚の画像の場合は、viewsでビュー4(全身)または1(バスト)を送ってください(409 single_image_sheet)。
  • シートの使い方: 他のシートと同じく?sheet=<sheet_id>で指定します。GET /characters/{id}、ビューのファイル、redo(instructionを含む)、ビューのPUTで使えます。Multi-Refクリップではcharacters[].sheet_idで選びます。
  • アプリのキャラクターではsheet_idを指定してください: デフォルトで使われるのは引き続き最後に変更したシート、つまり追加したばかりのシートです。
  • 追加したシートの削除: DELETE /characters/{id}/sheets/{sheet_id}はそのシートのビューだけを削除します。アプリで作ったシートはこの方法では削除できません(404 unknown_sheet)。
  • アプリでは: 同じライセンスのアプリが、新しいシートをキャラクターのプロフィールに取り込みます。
  • エラー: 400 outfit_or_views_required(衣装もビューもない)、400 views_required(ビューなしでgenerate: false)、409 source_sheet_empty(出発点となる全身ビューもバストもない)、409 character_busy。

ロケーション、オブジェクト、動物、スタイル、衣装

サブジェクトとは、ロケーション(location)、オブジェクト(object: 乗り物、小道具、家具など)、動物(animal)、スタイル(style: 動画がそのルックを取り入れる雰囲気の画像)または衣装(outfit: キャラクターが着る服)のことで、あなたが提供した1〜6枚の画像(複数アングルがあるほど忠実になります)から保存されます。これにより、Multi-Ref Videoで毎ショット説明することなく再利用できます。画像は生成されないので、無料です。

画像がなくても、サーバーが生成することもできます。画像なしでサブジェクトを生成するを参照してください。

POST /subjects(権限: images):

json
{ "type": "animal", "name": "Rex", "description": "a small brown dog with a red collar", "images_b64": ["<image 1>", "<image 2>"] }
フィールド型内容
typelocation、object、animal、styleまたはoutfitサブジェクトの種類
name1語、1〜40文字(英数字または_)プロンプト内で@の後に記述する単語
description英語テキスト、300文字以内、任意a glossy white futuristic tram with round windowsなど
images_b64base64の画像1〜6枚JPEG・PNG・WebP形式、長辺512px以上、1枚12MB以内(ボディ全体で28MBまで。それを超える場合は1枚ずつ追加してください)

レスポンス201はサブジェクトオブジェクトです: subject_id、type、name、description、origin、そのimages(各file_url付き)、complete、expires_atが含まれます。

  • 画像の追加: POST /subjects/{id}/imagesにimage_b64を送信(最大6枚)。
  • 一覧取得: GET /subjects(?type=locationでフィルタリング可能)で、アプリのLibraryのサブジェクト(originがapp)を含むすべてのサブジェクトと上限値maxを返します。画像がまだすべて同期されていないアプリのサブジェクトはcomplete: falseとなりますが、既存の画像で動作します。
  • 提供エレメント:Tendre.AIは固定idを持つすぐに使えるエレメントを提供します(例:officiel-red-beetle、オブジェクト)。各エレメントは一覧を初めて取得したとき(GET /subjects、MCPのtendre_subject_list)に一度だけリストに追加され、上限maxには数えられません。その後は他のサブジェクトと同じで、Multi-Refで使え(subject_id)、変更も削除もできます。一度削除すると二度と戻りません。
  • 取得: GET /subjects/{id}; 個別の画像: GET /subjects/{id}/images/{n}/file。
  • 変更: PUT /subjects/{id}にtype、name、description、images_b64(画像を置き換える完全なリスト)を指定。
  • 削除: DELETE /subjects/{id}で、アプリからも削除されます。

スタイルはクリップにルックを与えます。そのdescriptionには、画像に写っている内容ではなく技法を英語で書きます(loose watercolor painting on textured paper)。衣装はキャラクターが着る服です。スタイルと衣装は、UltraのMulti-Ref Videoでのみ使われます。

クリップにサブジェクトをキャストするにはMulti-Ref Video、画像に入れるにはCreate an imageを参照してください。

画像なしでサブジェクトを生成する

手元に画像がない場合は、POST /subjects/generate(権限 images)がアプリのElementsにある「Generate」ウィンドウと同じようにサブジェクトを作成します。説明文から作る(またはインポートした)開始画像のあと、そこから派生するビュー(別アングル、クローズアップ、夜など)を作り、どのビューも同じ形を保つよう開始画像からレタッチされます。できあがるのは通常のサブジェクトで、Multi-Ref VideoとCreate an imageで使え、アプリのライブラリにも表示されます。

フィールド型役割
typeobject、location、animal、style、outfitサブジェクトの種類(モーションは生成されません)
name1語、1〜40文字の英数字または _プロンプトで @ の後に書く語
description英語のテキスト、最大300文字要素だけ:形、素材、色、細部。背景やキャラクターは含めません(a glossy white futuristic tram with round windows)。prompt または start_image_b64 がない場合は必須
prompt英語のテキスト、最大2000文字、任意description から作る自動テキストの代わりに使う、開始画像の完全なテキスト
start_image_b64base64画像、任意インポートした開始画像(512 px以上)。そのまま保存され、無料です
viewsキーのリスト、任意欲しいビューを順に指定(下の表)
count1〜6、任意views の代わりに、開始画像を含む画像の総数(表の最初のビューから)
seed整数、任意開始画像のseed
quote_onlytrue価格だけを返し、何も作成しません

種類ごとのビュー(固定キー)と、その種類の出力サイズ:

typeサイズviews
object1024 × 1024three_quarter, side, back, top, detail (クローズアップ)
location1216 × 832reverse_shot, side, high_angle, night, detail (クローズアップ)
animal1216 × 832front, three_quarter, back, sitting, lying
style1024 × 1024portrait, landscape, interior, object, animal
outfit832 × 1216three_quarter, side, back, detail (クローズアップ)

料金:レンダリングされた画像(開始画像と各ビュー)はそれぞれ画像1枚分(1 クレジット)です。インポートした開始画像は無料で、失敗した画像は課金されません。開始画像を含め、1サブジェクトにつき最大6枚です。レスポンス 202 は、cost_estimate と generation を含むサブジェクトです:

json
"generation": {
  "status": "pending",
  "start": { "status": "ready", "origin": "generated", "n": 1 },
  "views": [{ "key": "three_quarter", "status": "ready", "n": 2 }, { "key": "detail", "status": "pending" }],
  "available_views": ["three_quarter", "side", "back", "top", "detail"]
}

generation.status が pending でなくなる(ready、partial、failed)まで GET /subjects/{id} で追跡してください。n は images 内の画像番号です。画像は1枚ずつ作られます。開始画像、次にビューを順番に作ります。失敗するとシリーズは止まり、以降のビューは課金なしで failed になります。

  • ビューを追加:POST /subjects/{id}/views に views(まだ作っていないキー)を指定します。ビューが1つのとき、instructions(英語、最大1000文字)がその指示を置き換えます。ビューに何を映すかを書いてください。
  • ビューをやり直す:POST /subjects/{id}/views/{key}/redo、必要なら instructions も指定します。ビューは開始画像から作り直され、前のビューを置き換えます(同じ n)。
  • 開始画像をやり直す:POST /subjects/{id}/views/start/redo。そこから派生したビューがない間だけ可能です(それ以外は views_exist)。インポートした開始画像はやり直せません。開始画像の失敗で止まったビューは、そのあとに再開されます。
  • quote_only: true は3つのルートすべてで価格を返します。1サブジェクトにつき同時に1シリーズまでです(subject_busy)。

最初から最後まで、ビュー2つのオブジェクトの例:

http
POST /pro/v1/subjects/generate

{ "type": "object", "name": "Tram", "description": "a glossy white futuristic tram with round windows", "views": ["three_quarter", "detail"] }

レスポンス 202 で、generation.status が pending の subject_id が返ります。ready になるまで数秒ごとに GET /subjects/{id} を確認し、その subject_id で @Tram をキャストしてください。画像は3枚(開始画像とビュー2つ)なので、料金は画像3枚分です。

ストレージ

キャラクターのビューとサブジェクトの画像は暗号化(ファイルごとに1つのキー)され、あなたのライセンスに紐付けられます。サブジェクトの画像は送信した状態のまま保存され、アプリのLibraryと共有されます。Proライセンスの上限: キャラクター50件(アプリのものを含む)、サブジェクト50件(ロケーション、オブジェクト、動物、スタイル、衣装の合計)(別カウント)(個人ライセンスはアプリ内で10件)。1年間使用されなかったキャラクターまたはサブジェクトは削除されます(expires_at)。Multi-Ref Videoのレンダリング、Face swapの実行、ビューや画像の読み込みのたびに有効期限が延長されます。キャラクター作成時に送信した写真は、生成されたビューと同様に暗号化されてそのロールのビューとして保存されます。いつでも任意のビューを削除できます。

エージェント経由での使用(MCP)

MCPサーバーを使えば、「この写真からキャラクターを作って」と伝えるだけです。エージェントがtendre_character_createを使用し(写真はアップロードリンク、ChatGPTに添付したファイル、会話内でレンダリングした画像、または公開URLから取得されます)、7つのビューを表示します。失敗したビューはtendre_character_redo_viewでやり直し、必要に応じてinstructionでガイドを追加するか、tendre_character_set_viewであなた自身の画像に置き換えます。tendre_character_get、tendre_character_list、tendre_character_deleteでその他の操作をカバーし、tendre_quoteで事前に料金を確認できます。

ロケーション、オブジェクト、動物の場合は、画像をエージェントに渡して何であるかを伝えてください。エージェントがtendre_subject_createを使用し、その後tendre_subject_list、tendre_subject_get、tendre_subject_deleteで管理できます。画像がない場合はtendre_subject_generateを使い、続いてtendre_subject_add_viewsとtendre_subject_redo_viewでビューを追加またはやり直します。

キャラクターのキャストについては、Multi-Ref Videoを参照してください。

Windows・Mac・クラウドまたはローカル

プライベートに生成しましょう。今夜から。

tendre.AIを無料でダウンロードして、自分のGPUでプライベートに無制限生成。

OS Windows 10/11GPU NVIDIA 8GB以上VRAM 12GB推奨ディスク容量 20GB

Appleチップ搭載のMac(M1以降):macOS 13以降が必要です。Intel Mac:macOS 12以降なら、すべてオンラインで動きます。

Mac上でのローカル画像生成には、24GBメモリ搭載のM4、または24GB搭載のM2・M3 Pro、Max、Ultraが必要です。それ未満のスペックの場合は、すべてクレジットを使ってオンラインで処理されます。現時点では、レタッチと動画生成はMacでもオンラインで実行されます。

tendre.AI for Macのすべて

NVIDIA GPUをお持ちでない場合は、100%クラウドで始められます。毎日無料で画像5枚と動画1本を利用可能です。NVIDIAカード(8GB以上)があれば、無制限のローカル生成が解放されます。