> ## 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.

# クリエイティブトランスフォーマーへの移行（3.1）

> ビルドケイパビリティのディスカバリーとクリエイティブ価格を Format フィールドからトランスフォーマー（list_transformers）へ移す。3.1 では加算的、非推奨の Format フィールドは 4.0 で削除。

# クリエイティブトランスフォーマーへの移行（3.1）

AdCP 3.1 は **トランスフォーマー** を導入します — メディアバイプロダクトのクリエイティブ版: エージェントが提供する、アカウントスコープの、選択可能なビルドケイパビリティの単位（ボイス、モデル、スタイル、ディレクター）で、型付き設定サーフェスとアカウントごとの価格を持ち、[`list_transformers`](/docs/creative/task-reference/list_transformers) 経由で発見され、[`build_creative`](/docs/creative/task-reference/build_creative) の `transformer_id` で選択されます。

トランスフォーマーは **独自の入力/出力フォーマットと独自の価格** を運ぶため、3.0 が *フォーマット* にぶら下げていた 3 つのものが今や冗長になり、非推奨です:

* `Format.input_format_ids` / `Format.output_format_ids`
* `Format.pricing_options`
* `list_creative_formats` の `input_format_ids` / `output_format_ids` ディスカバリー **フィルター**

**3.1 で何もしなくても何も壊れません。** 4 つすべてが `deprecated: true` ですが、依然として検証を通過し 3.1–3.x ラインを通じて機能します。4.0 より前に対応してください。下記の危険は、ハードな破壊ではなく、ウィンドウにわたる *静かな劣化* についてです。

## 何が変わったか

| Surface                                                                  | 3.0                                                                                                                           | 3.1                                                                                            | Removed |
| ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ------- |
| ビルドケイパビリティのディスカバリー                                                       | `input_format_ids` / `output_format_ids` で `list_creative_formats` をフィルター。`Format.input_format_ids` / `output_format_ids` を読む | `list_transformers` 経由で発見（各トランスフォーマーが独自の I/O シグネチャを宣言）                                         | 4.0     |
| クリエイティブ/変換の価格                                                            | `Format.pricing_options`（フォーマットごと）                                                                                            | `transformer.pricing_options`（トランスフォーマーごと。`list_transformers` の `include_pricing` + `account`） | 4.0     |
| `list_creative_formats` の `input_format_ids` / `output_format_ids` フィルター | サポート                                                                                                                          | `deprecated: true` — `list_transformers` フィルター + `brief` を使う                                   | 4.0     |

## 移行する

### Format I/O シグネチャ → トランスフォーマー

トランスフォーマーは、それが受け入れ生成するフォーマットを直接宣言するため、ビルドケイパビリティは *選択可能な単位* のプロパティであり、フォーマットにぶら下がる関係ではありません。

**Before（3.0）** — 変換フォーマットが消費/生成するものを宣言:

```json test=false theme={null}
{
  "format_id": { "agent_url": "https://creative.example", "id": "resize_to_meta" },
  "input_format_ids":  [{ "agent_url": "https://creative.example", "id": "display_master" }],
  "output_format_ids": [{ "agent_url": "https://creative.example", "id": "meta_reels_9x16" }]
}
```

**After（3.1）** — トランスフォーマーを宣言（`list_transformers` 経由で発見）:

```json test=false theme={null}
{
  "transformer_id": "resize_to_meta",
  "name": "Resize to Meta Reels",
  "input_format_ids":  [{ "agent_url": "https://creative.example", "id": "display_master" }],
  "output_format_ids": [{ "agent_url": "https://creative.example", "id": "meta_reels_9x16" }],
  "params": [],
  "pricing_options": [ { "pricing_option_id": "per_format", "model": "per_unit", "unit": "format", "unit_price": 0.10, "currency": "USD" } ]
}
```

### Format 価格 → トランスフォーマー価格

`Format.pricing_options` は `transformer.pricing_options` に移動します（同じ `vendor-pricing-option` 形状。`per_unit` が典型的）。適用されたオプションは `build_creative` レスポンスでリーフごとにエコーされ、`report_usage` 経由で再照合されます、変更なし。

複数出力のトランスフォーマーでは、価格オプションが `applies_to_output_format_ids` を運んでそのレートを特定の出力にスコープできます。スコープされていない価格オプションは任意の出力のデフォルトです。ビルドが、どのスコープオプションにも一致しない出力をターゲットにし、トランスフォーマーにスコープされていないデフォルトがない場合、エージェントは価格を推測するのではなく `UNPRICEABLE_OUTPUT` でビルドを拒否します。

### `list_creative_formats` ディスカバリーフィルター → `list_transformers`

「X をビルドできるもの」を見つけるために `input_format_ids` / `output_format_ids` で `list_creative_formats` をフィルターするのをやめてください。`list_transformers` を使ってください — その `input_format_ids` / `output_format_ids` でフィルターし、`brief` で絞り込み、`expand_params` でアカウントスコープのオプション値を展開します。

## 何もしないと何が静かに壊れるか

これらは throw しません — それがまさにこのガイドが存在する理由です。

1. **ディスカバリー読み取りの劣化（バイヤー）。** バイヤー/ストーリーボードが、`Format.input_format_ids` / `output_format_ids` を読むか、それらで `list_creative_formats` をフィルターすることによって *のみ* ビルドケイパビリティを学ぶ場合、3.1 セラーに対して動作し続けますが、セラーが非推奨フィールドを発するのをやめてケイパビリティをトランスフォーマーに移すにつれ **次第に空になる結果** を見ます。エラーなし — ただオプションがどんどん減るだけ。**フィールドがそのデータより長生きする。** ディスカバリーを `list_transformers` に移してください。

2. **出力ごとの価格ギャップ（複数パブリッシャーのテンプレートセラー）。** 出力を異なる価格にしていたテンプレートは、`applies_to_output_format_ids` でその形状を保てますが、すべての出力にスコープされた価格オプションかスコープされていないデフォルトのいずれかが必要です。そうでなければ、価格のない出力のビルドは `UNPRICEABLE_OUTPUT` で拒否されます。

3. **ファンアウト / best-of-N の支出過少カウント（課金パイプライン）。** `max_variants` / `max_creatives` では、生成されたすべてのバリアントが課金されますが、**トラフィックされた** リーフのみが遅延的に `creative_id` を得ます。破棄された best-of-N のリーフは、`build_creative` レスポンスの **インラインのリーフごとの `vendor_cost`** 経由で *のみ* 課金されます — それらは決して `creative_id` を得ず、したがって決して `report_usage` に現れません。`report_usage` のみから支出を再照合するパイプライン（3.0 の不変条件「すべての課金単位は `creative_id` 経由で再照合される」）は、破棄されたすべてのバリアントの分だけ **過少カウント** します。トラフィックされていないリーフの権威あるレコードとして、インラインのリーフごとの領収書を取り込んでください。その領収書が唯一のレコードなので、スキーマがそれを強制します: ビルドがコストをレポートするとき（集計 `vendor_cost` が存在するとき）、生成されたすべてのリーフは独自の `vendor_cost` + `currency` を運ばなければならず（MUST）、支払いビルドが機械可読なコストのないリーフを返せません。境界に注意: スキーマはレポートされたコストの *内部的な完全性と一貫性* を強制します — 真に無料のビルド（または正当に `0` の CPM 遅延リーフ）を、過少レポートするために集計を省略する支払いビルドと区別できません。「集計が欠如」は、ゼロコストの証明ではなく、再照合すべき信頼アサーション（セラー請求書対 `report_usage` + インライン領収書、`pricing_option_id` 基準で区別）です — スキーマ有効性を課金の正直さと取り違えないでください。

## SDK の動作とタイムライン

| Version | Deprecated fields                                              |
| ------- | -------------------------------------------------------------- |
| 3.1     | `deprecated: true`。依然として発せられ尊重される。SDK はそれらを読み続けなければならない（MUST）。 |
| 3.1–3.x | 全期間尊重される。新しいコードはそれらを発すべきではない（SHOULD NOT）。                      |
| 4.0+    | SDK は拒否してもよい（MAY）。削除。                                          |

## 関連項目

* [`list_transformers`](/docs/creative/task-reference/list_transformers) — トランスフォーマー、そのパラメーター、オプション値、価格を発見
* [`build_creative`](/docs/creative/task-reference/build_creative) — トランスフォーマーを選択、設定、乗算、絞り込み
* [3.1 の新機能](/docs/reference/whats-new-in-3-1)