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)。処理は非同期で行われます。
{ "name": "Lea", "kind": "woman", "image_b64": "<the photo>", "photo_role": "bust" }| フィールド | 型 | 内容 |
|---|---|---|
name | 文字列、1〜40文字 | キャラクターのファーストネーム |
kind | 文字列 | woman、man、または英語で記述したクリーチャー(baby dragonなど)。指示文の代名詞を設定するもので、「they」にはなりません。 |
image_b64 | base64 | 写真: 鮮明で1人のみ写っていること、長辺1024px以上、12MB以内、JPEG・PNG・WebP形式 |
photo_role | bust(デフォルト)または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 | ビューを生成中 |
ready | 7つのビューがすべて揃っている |
partial | 一部のビューが欠けているか失敗している |
failed、empty | 使用可能なビューがない |
{
"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が含まれます。
{ "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の画像 | 用意済みのビュー。ビューのアップロードと同じルールです |
generate | true(デフォルト)または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):
{ "type": "animal", "name": "Rex", "description": "a small brown dog with a red collar", "images_b64": ["<image 1>", "<image 2>"] }| フィールド | 型 | 内容 |
|---|---|---|
type | location、object、animal、styleまたはoutfit | サブジェクトの種類 |
name | 1語、1〜40文字(英数字または_) | プロンプト内で@の後に記述する単語 |
description | 英語テキスト、300文字以内、任意 | a glossy white futuristic tram with round windowsなど |
images_b64 | base64の画像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で使え、アプリのライブラリにも表示されます。
| フィールド | 型 | 役割 |
|---|---|---|
type | object、location、animal、style、outfit | サブジェクトの種類(モーションは生成されません) |
name | 1語、1〜40文字の英数字または _ | プロンプトで @ の後に書く語 |
description | 英語のテキスト、最大300文字 | 要素だけ:形、素材、色、細部。背景やキャラクターは含めません(a glossy white futuristic tram with round windows)。prompt または start_image_b64 がない場合は必須 |
prompt | 英語のテキスト、最大2000文字、任意 | description から作る自動テキストの代わりに使う、開始画像の完全なテキスト |
start_image_b64 | base64画像、任意 | インポートした開始画像(512 px以上)。そのまま保存され、無料です |
views | キーのリスト、任意 | 欲しいビューを順に指定(下の表) |
count | 1〜6、任意 | views の代わりに、開始画像を含む画像の総数(表の最初のビューから) |
seed | 整数、任意 | 開始画像のseed |
quote_only | true | 価格だけを返し、何も作成しません |
種類ごとのビュー(固定キー)と、その種類の出力サイズ:
type | サイズ | views |
|---|---|---|
object | 1024 × 1024 | three_quarter, side, back, top, detail (クローズアップ) |
location | 1216 × 832 | reverse_shot, side, high_angle, night, detail (クローズアップ) |
animal | 1216 × 832 | front, three_quarter, back, sitting, lying |
style | 1024 × 1024 | portrait, landscape, interior, object, animal |
outfit | 832 × 1216 | three_quarter, side, back, detail (クローズアップ) |
料金:レンダリングされた画像(開始画像と各ビュー)はそれぞれ画像1枚分(1 クレジット)です。インポートした開始画像は無料で、失敗した画像は課金されません。開始画像を含め、1サブジェクトにつき最大6枚です。レスポンス 202 は、cost_estimate と generation を含むサブジェクトです:
"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つのオブジェクトの例:
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を参照してください。