AdCP — list_transformers

クリエイティブエージェントがアカウントに提供する transformer を発見します。transformer はメディアバイ製品のクリエイティブ類似物です: エージェント提供、アカウントスコープ、選択可能なビルドケイパビリティ単位（ボイス、モデル、スタイル、ディレクター）で、型付き構成表面とアカウントごとの価格設定を持ちます。ここで transformer を発見し、次に build_creative で transformer_id を使って 1 つを選択します。 Response Time: 約 1 秒（アカウントスコープルックアップ） Authentication: アカウントスコープ。transformer、その列挙可能なオプション値、価格設定は呼び出し認証情報のために解決されます — あなたのアカウントにのみ存在する構成したカスタム値（例: クローンされたボイス）を含む。 Request Schema: /schemas/v3/creative/list-transformers-request.json Response Schema: /schemas/v3/creative/list-transformers-response.json 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 を参照）: `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 スキーマを参照してください。

一般的なシナリオ

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

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);
}

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())

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

選んだ transformer_id と型付き config（各 param の field でキー）を build_creative に渡します:

test=false

{
  "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 — transformer を選択しクリエイティブを生成（バリアントを含む）
get_adcp_capabilities — creative.supports_transformers 判別子
Vendor pricing — per_unit レートモデル

はじめに

AdCP で構築する

プロトコル

FAQ

トラストとセキュリティ

リファレンス

AAO

認定

list_transformers

なぜ transformer か

リクエストパラメーター

`expand` モード

レスポンス

一般的なシナリオ

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

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

エラー処理

さらに学ぶ

​なぜ transformer か

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

​expand モード

​レスポンス

​一般的なシナリオ

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

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

​エラー処理

​さらに学ぶ

なぜ transformer か

リクエストパラメーター

`expand` モード

レスポンス

一般的なシナリオ

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

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

エラー処理

さらに学ぶ