# キャラクター

> AI アシスタントからキャラクターを作成し、ポートレートを生成して承認します。表情、ポーズ、アングル、モーションクリップを追加し、リファレンスとして再利用できます。

Source: https://nodaro.ai/ja/docs/mcp/tools/characters

**キャラクターのツール**を使うと、アシスタントは、キャラクタースタジオのライブラリにあるキャラクターを作成して使えます。対象は、見た目が固定された人物やキャラクターで、どの画像や動画でも同じ姿を保ちます。アシスタントは、キャラクターを作成し、ポートレートを生成して承認し、表情、ポーズ、アングル、ライティングなどのバリエーションを追加します。さらに、キャラクターをアニメーション化してモーションクリップを作り、その画像をリファレンスとしてほかの生成に渡します。アプリで同じ作業をする方法は、[キャラクタースタジオ](https://nodaro.ai/docs/guides/character-studio)を参照してください。

## キャラクターのライフサイクル
### キャラクターを作成する
`create_character` は、名前と基本情報（説明、性別、スタイル、衣装）を保存します。この時点では、キャラクターにはまだポートレートがありません。

### ポートレートを生成して承認する
`kind: "main"` を指定した `generate_character` で、ポートレートを作ります。気に入るものができるまで実行し、そのジョブを `approve_portrait` に渡します。承認したポートレートがキャラクターの基準になり、ビジョンモデルがその基準となる説明を書きます。

### バリエーションを追加する
`kind: "asset"` と `attach_to_character_id` を指定した `generate_character` は、承認したポートレートから、表情、ポーズ、頭部と全身のアングル、ライティングのバリエーションを作り、それぞれをキャラクターに保存します。

### アニメーション化して再利用する
`generate_character_motion` は、キャラクターからモーションクリップを作ります。`get_character` はすべての画像とクリップを返すので、そのまま [`generate_image`](https://nodaro.ai/docs/mcp/tools/image#generate_image) や [`generate_video`](https://nodaro.ai/docs/mcp/tools/video#generate_video) にリファレンスとして渡せます。

## `list_characters`
自分のキャラクターを、更新日時の新しい順に一覧表示します。各キャラクターの名前、説明、ポートレート、種類ごとのバリエーションの数、基本情報のテキストが含まれます。アーカイブしたキャラクターは含まれません。`search` を指定しないと最初のページしか返さないので、ユーザーがキャラクターの名前を挙げた場合は、名前で検索します。

**権限**：`assets:read`。**クレジット**：無料。

| パラメーター | 型 | 説明 |
| --- | --- | --- |
| `search` | string | キャラクター名の一部で、大文字と小文字は区別されません。最大 100 文字です。 |
| `limit` | integer | 1〜100 です。デフォルトは `50` です。 |

**戻り値**：キャラクターの一覧です。画像の URL を取得するには、`get_character` を呼び出します。

## `get_character`
1 つのキャラクターのすべての情報を返します。内容は、すべての表情、ポーズ、モーション、頭部のアングル、全身のアングル、ライティングのバリエーション（それぞれの名前と URL 付き）、リファレンス写真、そしてバリエーションにある場合は実写リファレンスの URL です。

**権限**：`assets:read`。**クレジット**：無料。

| パラメーター | 型 | 説明 |
| --- | --- | --- |
| `id` | string | **必須**。`list_characters` で取得したキャラクター ID です。 |

**戻り値**：キャラクターです。`update_character` で使う `updatedAt` も含まれます。キャラクターが存在しない場合や自分のものでない場合は、エラーが返されます。

## `create_character`
基本情報を指定してキャラクターを作成します。作成した時点ではポートレートがないので、次に `generate_character` でポートレートを生成します。

**権限**：`assets:write`。**クレジット**：無料。

| パラメーター | 型 | 説明 |
| --- | --- | --- |
| `name` | string | **必須**。`Kira` のような表示名で、最大 200 文字です。有効なキャラクターの中で一意である必要があり、重複すると `name_taken` が返されます。 |
| `description` | string | キャラクターがどんな人物かの説明で、最大 2,000 文字です。 |
| `gender` | string | 最大 50 文字です。 |
| `style` | string | ビジュアルスタイルです。たとえば `realistic`、`anime`、`3d-pixar`、`illustration` です。 |
| `base_outfit` | string | 普段の服装で、最大 1,000 文字です。 |
| `seed_prompt` | string | 最初のポートレートの方向性を決める短いプロンプトで、最大 4,000 文字です。 |
| `identity_lock` | string | キャラクタースタジオが、生成するバリエーションで顔をどれだけ厳密に保つかです。`off`（デフォルト）、`soft`、`strict` のいずれかです。 |

**戻り値**：新しいキャラクターの ID です。

## `update_character`
キャラクターの基本情報を変更します。書き込まれるのは、指定したフィールドだけです。

**権限**：`assets:write`。**クレジット**：無料。

| パラメーター | 型 | 説明 |
| --- | --- | --- |
| `id` | string | **必須**。キャラクター ID です。 |
| `name`、`description`、`gender`、`style`、`base_outfit`、`seed_prompt`、`identity_lock` | | `create_character` と同じです。 |
| `expected_updated_at` | string | `get_character` で取得した `updatedAt` です。読み取った後にキャラクターが変更されていた場合、変更は拒否されます。 |

**戻り値**：確認メッセージです。`expected_updated_at` が古い場合は、競合エラーが返されます。

## `approve_portrait`
完了した `generate_character` の結果をキャラクターのポートレートにし、ビジョンモデルにその画像を説明させて、キャラクターの基準となる説明を埋めます。

**権限**：`assets:write`。**クレジット**：説明を書くための、短い LLM の実行 1 回分です。

| パラメーター | 型 | 説明 |
| --- | --- | --- |
| `character_id` | string | **必須**。対象のキャラクターです。 |
| `candidate_job_id` | string | **必須**。完了した自分の `generate_character` ジョブです。 |

**戻り値**：ポートレートの URL と説明です。説明の生成に失敗した場合でもポートレートは設定され、説明は空になります。その場合は `recaption_character` を実行します。

## `recaption_character`
ビジョンモデルに現在のポートレートをもう一度説明させ、新しい基準となる説明を保存します。ポートレートを変更した後や、説明が正しくない場合に使います。

**権限**：`assets:write`。**クレジット**：短い LLM の実行 1 回分です。

| パラメーター | 型 | 説明 |
| --- | --- | --- |
| `id` | string | **必須**。対象のキャラクターです。 |

**戻り値**：新しい説明です。キャラクターにポートレートがない場合は、`400 no_portrait` が返されます。

## `generate_character`
キャラクターのポートレート（`kind: "main"`）、またはキャラクターのバリエーション（`kind: "asset"`）を生成します。

**権限**：`workflows:execute`。**クレジット**：画像モデルの料金です。

| パラメーター | 型 | 説明 |
| --- | --- | --- |
| `name` | string | **必須**。キャラクターの名前です。 |
| `kind` | string | ポートレートなら `main`（デフォルト）、バリエーションなら `asset` です。 |
| `description`、`gender`、`style`、`base_outfit` | string | ポートレート用の基本情報です。 |
| `model` | string | 画像モデルです。デフォルトは `nano-banana` です。 |
| `asset_type` | string | `asset` の場合は必須です。`expressions`、`poses`、`lighting`、`headAngles`、`bodyAngles`、`custom` のいずれかです。`angles` は `headAngles` の古い名前です。 |
| `variant` | string | `asset` の場合は必須です。バリエーションで、たとえば、表情なら `smile` や `angry`、アングルなら `front`、`3/4 left`、`left profile`、`right profile`、`3/4 right`、`back`、ポーズなら `standing` や `walking`、ライティングなら `daylight`、`night`、`dramatic` です。 |
| `attach_to_character_id` | string | 結果をこのキャラクターに保存し、その承認済みのポートレートを元画像として使います。承認済みのポートレートがない場合、呼び出しは `portrait_required` を返します。 |
| `attach_to_column` | string | `custom` のバリエーションで `attach_to_character_id` を指定する場合は必須です。保存先で、たとえば `expressions`、`poses`、`angles`、`body_angles`、`lighting_variations`、`sheets`、`detail_closeups`、`outfit_variations`、`boards` です。 |
| `attach_name` | string | 保存するバリエーションの名前です。デフォルトは `variant` の値です。 |
| `source_image_url` | string | キャラクターに保存しない場合の元画像です。 |

**戻り値**：ジョブ ID です。ポートレートの場合は、結果が気に入ったら、そのジョブを `approve_portrait` に渡します。

## `generate_character_motion`
キャラクターの画像の 1 枚から、キャラクターが動く短いモーションクリップを作ります。

**権限**：`workflows:execute`。**クレジット**：動画モデルの料金です。

| パラメーター | 型 | 説明 |
| --- | --- | --- |
| `motion_prompt` | string | **必須**。何がどのように動くかで、最大 2,000 文字です。たとえば「slow head turn left, eyes track the camera, soft smile」です。 |
| `name` | string | **必須**。キャラクターの名前です。 |
| `attach_to_character_id` | string | キャラクターから元画像を選び、クリップをキャラクターのモーションに保存します。 |
| `source_image_url` | string | 自分で選んだ元画像です。`attach_to_character_id` を指定しない場合は必須です。 |
| `provider` | string | `kling`（デフォルト）、`kling-turbo`、`kling-3.0`、`wan-i2v`、`wan-2.7-i2v` のいずれかです。 |
| `attach_name` | string | 保存するモーションの名前です。たとえば `walking` です。 |
| `description`、`motion_description`、`gender`、`style`、`base_outfit` | string | 任意で指定する、基本情報と動きの詳細です。 |

`attach_to_character_id` を指定した場合、元画像は次の順で選ばれます。指定した `source_image_url`、キャラクターの正面の全身のアングル、そのほかの全身のアングル、ポートレートの順です。全身の画像は、頭部のポートレートよりもはるかにうまく動くので、先に全身のアングルを生成してください。

**戻り値**：ジョブ ID です。クリップの準備ができると、カードで再生されます。

## Frequently asked questions

### アシスタントは、Nodaro で一貫したキャラクターをどのように作りますか？

名前と説明を指定して create_character を呼び出し、generate_character でポートレートを生成して、いちばん良いものを approve_portrait で承認します。承認したポートレートが、そのキャラクターのすべてのバリエーションとモーションクリップの基準になります。

### 保存したキャラクターを画像や動画で使うにはどうすればよいですか？

list_characters でキャラクターを探し、get_character でその画像を読み取ります。そして、適切なポートレート、表情、ポーズの URL を、generate_image、image_to_image、generate_video の reference_image_urls に渡します。

### バリエーションが portrait_required で失敗するのはなぜですか？

バリエーションは、承認済みのポートレートを元画像として使うためです。先に kind を main にしてポートレートを生成し、approve_portrait で承認してください。

### モーションクリップは、どの画像から始めるのがよいですか？

全身の画像は、頭部のポートレートよりもはるかにうまく動きます。先にキャラクターの全身のアングルを生成してください。そうすると、generate_character_motion が正面の全身のアングルを自動的に使います。