> ## Documentation Index
> Fetch the complete documentation index at: https://adcp-docs-ja.pier1.co.jp/llms.txt
> Use this file to discover all available pages before exploring further.

# list_transformers

> list_transformers はアカウントスコープのクリエイティブ transformer — build_creative が使うエージェント提供の選択可能なビルドケイパビリティ単位（ボイス、モデル、スタイル）— を発見する。

クリエイティブエージェントがアカウントに提供する **transformer** を発見します。transformer はメディアバイ製品のクリエイティブ類似物です: エージェント提供、アカウントスコープ、選択可能なビルドケイパビリティ単位（ボイス、モデル、スタイル、ディレクター）で、型付き構成表面とアカウントごとの価格設定を持ちます。ここで transformer を発見し、次に [`build_creative`](/docs/creative/task-reference/build_creative) で `transformer_id` を使って 1 つを選択します。

**Response Time**: 約 1 秒（アカウントスコープルックアップ）

**Authentication**: アカウントスコープ。transformer、その列挙可能なオプション値、価格設定は呼び出し認証情報のために解決されます — あなたのアカウントにのみ存在する構成したカスタム値（例: クローンされたボイス）を含む。

**Request Schema**: [`/schemas/v3/creative/list-transformers-request.json`](https://adcontextprotocol.org/schemas/v3/creative/list-transformers-request.json)
**Response Schema**: [`/schemas/v3/creative/list-transformers-response.json`](https://adcontextprotocol.org/schemas/v3/creative/list-transformers-response.json)

[`get_adcp_capabilities`](/docs/protocol/get_adcp_capabilities) で `creative.supports_transformers: true` を設定するエージェントのみが提供します。

## なぜ transformer か

クリエイティブエージェントが露出するレンダーノブのセット — とその合法な値 — は **アカウント固有で動的** です。あなたの構成したボイスはグローバル enum やあなたが保持するリストではありません。*エージェント* がそれらを知り、追加するとセットが変わります。したがってディスカバリーは、`get_products` がアカウントスコープの在庫を表示するのと同じ方法で、エージェント → バイヤーと流れます。`list_transformers` はクリエイティブビルドケイパビリティのそのディスカバリー表面です。

エージェントは粒度を選びます: 別個のボイスやモデルは自身の transformer になりえ、または単一の transformer が `voice`/`model` を列挙可能な `config` param として露出しえます。どちらの方法でも同じ呼び出しを使います — transformer をリストし、値が欲しければ param を展開します。

## リクエストパラメーター

| Parameter           | Type        | Required    | Description                                                                                                                                                         |
| ------------------- | ----------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `transformer_ids`   | string\[]   | No          | これらの特定の transformer ID のみを返す                                                                                                                                        |
| `input_format_ids`  | FormatID\[] | No          | これらのフォーマットのいずれかを入力として受け入れる transformer にフィルター                                                                                                                       |
| `output_format_ids` | FormatID\[] | No          | これらの出力フォーマットのいずれかを生成できる transformer にフィルター                                                                                                                          |
| `name_search`       | string      | No          | 名前で transformer を検索（大文字小文字を区別しない部分一致）                                                                                                                               |
| `brief`             | string      | No          | transformer とそのオプション値をランク/フィルターする自然言語ブリーフ（例: "warm female Spanish-language voiceover"）。完全なセットを返すのではなく意図にキュレート。                                                      |
| `expand_params`     | string\[]   | No          | アカウントスコープのオプション **値** の **最初のページ** を `params[].options[]` にインラインで返す param `field` 名。リーンなデフォルト（記述子のみ）には省略。                                                           |
| `expand_pagination` | object\[]   | No          | 特定の param のオプションの **次のページ** をフェッチ、`{ transformer_id, field, options_cursor }` でスコープ（先のレスポンスの `params[].options_cursor` からのカーソル）。カーソルを保持したら `expand_params` の代わりに使う。 |
| `include_pricing`   | boolean     | No          | 各 transformer に `pricing_options` を含む。`account` が必要。                                                                                                                |
| `account`           | AccountRef  | Conditional | `include_pricing` が true のとき必須。transformer はいずれにせよアカウントスコープ。                                                                                                        |
| `pagination`        | object      | No          | `max_results` と `cursor`（前のレスポンスからの不透明カーソル）                                                                                                                         |

### `expand` モード

デフォルトでレスポンスは、小さな閉じた enum をインライン化した各 transformer の param **スキーマ** を返します（例: `mastering_preset`）。アカウントスコープの列挙可能な param の **値**（例: あなたのボイス）を得るには、`expand_params` でそれを名指します — それは `params[].options[]` の **最初のページ** を返します。param の値がトランケートされると、その `params[].options_cursor` が設定されます。**`expand_pagination`** に `{ transformer_id, field, options_cursor }` を渡して次のページをフェッチします（各 `(transformer, param)` は独立にページ化）。値はブリーフフィルターされます — "warm Spanish female voice" は 300 ボイスのカタログをすべてダンプするのではなく一握りに絞ります。別のオプションエンドポイントはありません。値列挙（とそのページネーション）はこの 1 つのツールのモードです。

## レスポンス

| Field          | Description                             |
| -------------- | --------------------------------------- |
| `transformers` | transformer 記述子の配列（下記参照）                |
| `errors`       | タスク固有のエラーと警告のオプション配列                    |
| `pagination`   | より多くの transformer が利用可能なときのページネーションカーソル |

各 transformer は以下を運びます:

| Field                                    | Description                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `transformer_id`                         | 安定した id。`build_creative` `transformer_id` に渡す                                                                                                                                                                                                                                                                                                                                                                                    |
| `name`                                   | 人間可読な名前                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `input_format_ids` / `output_format_ids` | 受け入れるものと生成するもの。`build_creative` ターゲットは `output_format_ids` のサブセットでなければならない（MUST）。空の `input_format_ids` はブリーフからビルドすることを意味する（純粋生成）。                                                                                                                                                                                                                                                                                                |
| `params`                                 | Config ノブ（[Transformer Param](https://adcontextprotocol.org/schemas/v3/core/transformer-param.json) を参照）: `field`、`type`、`value_source`（`inline`/`range`/`enumerable`/`free_text`）、`allowed_values`/`minimum`/`maximum`、`options[]`+`options_cursor`（展開時）、`max_length`（`free_text` 用）、`default`。`free_text` はオープンなバイヤー作成文字列（例: `negative_prompt`）。param は生成カウントノブであってはならない（MUST NOT） — カウントは `max_variants`/`max_creatives` に乗る。 |
| `pricing_options`                        | アカウントごとのレートカード（`include_pricing` 時）。`per_unit` モデルを使う（例: $/生成画像、$/秒）。価格オプションは異なる出力を異なる価格設定するため `applies_to_output_format_ids` を運べる（例: パブリッシャーフォーマットごとのマルチパブリッシャーテンプレート）。アンスコープオプションがデフォルトで、どのオプションにも一致しない出力（アンスコープデフォルトなし）は `UNPRICEABLE_OUTPUT` で拒否される（フォールバックなし）。適用されたオプションは `build_creative` レスポンスでリーフごとにエコーされ `report_usage` 経由で照合される。                                                                                       |

完全なオブジェクトについては [Transformer スキーマ](https://adcontextprotocol.org/schemas/v3/core/transformer.json) を参照してください。

## 一般的なシナリオ

### ブリーフのボイスを値とともに発見する

<CodeGroup>
  ```javascript test=false theme={null}
  import { testAgent } from '@adcp/sdk/testing';
  import { ListTransformersResponseSchema } from '@adcp/sdk';

  const result = await testAgent.listTransformers({
    account: { account_id: 'acct_acme' },
    brief: 'warm female Spanish-language voiceover',
    output_format_ids: [{ agent_url: 'https://creative.audiostack.example', id: 'audio_vo' }],
    expand_params: ['voice'],
    include_pricing: true,
  });

  const parsed = ListTransformersResponseSchema.parse(result);
  for (const t of parsed.transformers) {
    console.log(t.transformer_id, t.name);
    const voice = t.params?.find((p) => p.field === 'voice');
    for (const opt of voice?.options ?? []) console.log('  voice:', opt.value, opt.metadata);
  }
  ```

  ```python test=false theme={null}
  import asyncio
  from adcp.testing import test_agent
  from adcp import ListTransformersResponse

  async def main():
      result = await test_agent.list_transformers(
          account={"account_id": "acct_acme"},
          brief="warm female Spanish-language voiceover",
          output_format_ids=[{"agent_url": "https://creative.audiostack.example", "id": "audio_vo"}],
          expand_params=["voice"],
          include_pricing=True,
      )
      parsed = ListTransformersResponse.model_validate(result)
      for t in parsed.transformers:
          print(t.transformer_id, t.name)

  asyncio.run(main())
  ```
</CodeGroup>

### 次に選択した transformer でビルドする

選んだ `transformer_id` と型付き `config`（各 param の `field` でキー）を [`build_creative`](/docs/creative/task-reference/build_creative) に渡します:

```json test=false theme={null}
{
  "transformer_id": "audiostack_voiceover",
  "config": { "voice": "isaac", "speaking_rate": 1.1, "mastering_preset": "podcast" },
  "creative_manifest": { "format_id": { "agent_url": "https://creative.audiostack.example", "id": "script" }, "assets": { "script": { "asset_type": "text", "content": "Discover the new winter collection." } } },
  "target_format_id": { "agent_url": "https://creative.audiostack.example", "id": "audio_vo" },
  "account": { "account_id": "acct_acme" },
  "idempotency_key": "0c1d2e3f-4a5b-6c7d-8e9f-a0b1c2d3e4f5"
}
```

## エラー処理

| Code              | Meaning                                | Recovery           |
| ----------------- | -------------------------------------- | ------------------ |
| `AUTH_MISSING`    | 解決可能なアカウントなしに `include_pricing` が要求された | `account` を供給 / 認証 |
| `INVALID_REQUEST` | 不正な形式のフィルターまたはページネーションカーソル             | リクエストを修正           |

未知の `expand_params`（どの transformer も露出しない `field`）は無視され、エラーではありません — param は単に `options` を返しません。

## さらに学ぶ

* [build\_creative](/docs/creative/task-reference/build_creative) — transformer を選択しクリエイティブを生成（バリアントを含む）
* [get\_adcp\_capabilities](/docs/protocol/get_adcp_capabilities) — `creative.supports_transformers` 判別子
* [Vendor pricing](https://adcontextprotocol.org/schemas/v3/core/vendor-pricing-option.json) — `per_unit` レートモデル