CMO AI Pro Developers
記事画像ツール
記事URLからの取り込み、テンプレ化、記事LP画像生成を行う5つのツールの仕様です。
最終更新日：2026年9月23日
記事URLからの取り込み、テンプレ化、記事LP画像生成に使う5つのツールです。記事LP動画は専用のMCPツールで作成・編集できます。手順書 article-video を先に読み、動画化の前に利用者の確認を取ります。
記事画像の確定・公開はMCPから実行できません。 生成された候補を比較して採否を決める操作は、 CMO AI Proの画面で人が行います。エージェントができるのは、取り込み・テンプレ化・生成の開始と 結果の取得までです。
preview_article_images
記事URLから取り込み候補を抽出し、ファーストビュー位置を含めて返します。
パラメータ
| パラメータ | 型 | 必須 | 既定値 | 制約 |
|---|---|---|---|---|
source_url | 文字列 | 必須 | — | URL |
応答
| フィールド | 内容 |
|---|---|
candidates[] | 取り込み候補（メディアURL、サイズ、ファーストビュー位置など） |
skipped[] | スキップされた候補と理由 |
diagnostics | 取得経路や候補数などの診断情報 |
応答には candidates[].title について untrusted 申告が付きます。詳しくは 共通仕様を参照してください。
エラー
| code | 発生条件 |
|---|---|
validation_error | URLが無効、または記事として解析できない |
ingest_article_image_templates
選択した記事画像候補を取り込み、テンプレ化ジョブを起動します。
パラメータ
| パラメータ | 型 | 必須 | 既定値 | 制約 |
|---|---|---|---|---|
source_url | 文字列 | 必須 | — | URL |
candidates | 配列 | 必須 | — | 1〜20件。各要素は media_url（URL）、media_origin（image または video_last_frame）、title（任意・200文字以内）、source_index（任意・正の整数）、is_first_main_image（任意・真偽値） |
idempotency_key | 文字列 | 必須 | — | 1〜128文字 |
応答
| フィールド | 内容 |
|---|---|
savedIds | 保存された記事画像ID |
savedCount | 保存件数 |
skippedCount | スキップ件数 |
failedCount | 取り込み失敗件数 |
failedMediaUrls | 取り込みに失敗したメディアURL |
templateJobIds | 起動したテンプレ化ジョブID |
scheduledTemplateCount | テンプレ化を開始した件数 |
motionAnalysis | 動画由来の候補で始めた動き解析。startedImageIds、jobIds（開始したジョブID）、skipped[]（imageId・reason: "payment_required" / "frame_extract_failed" / "start_failed"）を含む |
エラー
| code | 発生条件 |
|---|---|
validation_error | 候補数が範囲外、URLや候補の形式が不正 |
payment_required | クレジット不足、または日次上限 |
消費
1件あたり15クレジットです。消費量は candidates の件数で決まります。動画由来の候補（media_origin: "video_last_frame"）は、記事LP参考動画の動き解析が自動で始まり、その単価分（article_video.template、1本50クレジット）を消費します。実際に開始した解析分は応答の creditAmount に加算され、MCPの1日の生成クレジットにも数えます。残高不足、コマ取り出し失敗、開始失敗は取り込みを成功させたまま motionAnalysis.skipped に理由を返します。
list_article_images
組織の記事画像と公式プリセットを絞り込み一覧します。
パラメータ
| パラメータ | 型 | 必須 | 既定値 | 制約 |
|---|---|---|---|---|
status | 文字列 | 任意 | templated | collected / templating / templated / failed |
category | 文字列 | 任意 | — | 60文字以内 |
query | 文字列 | 任意 | — | 200文字以内。タイトルの部分一致 |
limit | 整数 | 任意 | 50 | 1〜100 |
応答
| フィールド | 内容 |
|---|---|
articleImages[].id | 記事画像ID |
articleImages[].title | タイトル |
articleImages[].category | カテゴリ |
articleImages[].productName | 商品名 |
articleImages[].genreName | ジャンル名 |
articleImages[].imageWidth | 画像の幅（ピクセル） |
articleImages[].imageHeight | 画像の高さ（ピクセル） |
articleImages[].mediaOrigin | メディアの由来。image は画像候補、video_last_frame は動画の最終フレームを保存した候補 |
articleImages[].status | 状態。templated が利用可能 |
articleImages[].isPreset | 公式プリセットか |
articleImages[].createdAt | 作成日時 |
articleImages[].motionStatus | 動き解析の状態。none / analyzing / analyzed / failed。古い analyzing は failed として返る |
articleImages[].motionErrorMessage | 動き解析の失敗理由 |
取り込みで始まった動き解析は、応答の motionAnalysis.jobIds とこの一覧の motionStatus で追跡します。スキップされた候補は、CMO AI Proの参考記事素材DBで「分析する」を押して再開してください。
start_article_creative_generation
既存の生成処理を使って案件の記事LP画像生成ジョブを開始します。完了は待ちません。記事LPを指定した場合（official_article_id 指定時）は、案件に属するofficial_article_idと正規化済み生成入力を冪等性キーへ結び付けます。同じキーを別の記事へ切り替えると、キャッシュを返さず入力不一致になります。冪等性キーは128文字まで受け付け、内部サービス要求IDはAPIキー、ツール名、キー全体を名前空間付きハッシュにして120文字以内へ変換します。
パラメータ
| パラメータ | 型 | 必須 | 既定値 | 制約 |
|---|---|---|---|---|
project_id | 文字列 | 必須 | — | UUID |
official_article_id | 文字列 | 任意 | — | UUID。指定記事の所属projectがproject_idと一致 |
initial_placement_intent | オブジェクト | 任意 | — | official_article_id 指定時のみ |
strategy_id | 文字列 | 任意 | — | UUID。案件に属していること |
article_image_ids | 文字列の配列 | 任意 | 空配列 | UUID |
reference_image_ids | 文字列の配列 | 任意 | 空配列 | UUID |
request_text | 文字列 | 任意 | 空文字 | — |
size_instruction | 文字列 | 任意 | — | — |
idempotency_key | 文字列 | 必須 | — | 1〜128文字 |
応答
| フィールド | 内容 |
|---|---|
jobId | ジョブID |
status | queued |
generationBatchId | このバッチのID |
reused | すでに同じバッチのジョブがある場合に true（新規消費なし） |
記事LPを指定した場合の応答にはofficialArticleId、generationRequestId、generationBatchId、acceptance、jobStatus、resultCreativeId、creditReservationState、creditRefundState、chargeFinalが含まれます。acceptance: recovery_pendingまたはjobStatus: unknownは状態未確定を表し、同じ記事とgenerationRequestIdの組で再取得します。応答が失われても新しいキーで再実行せず、元のキーで回収します。継承済み予約の台帳がまだ読めない場合も、要求IDを保持したunknownとして返し、再予約・再ディスパッチは行いません。
エラー
| code | 発生条件 |
|---|---|
not_found | 案件・戦略仮説・記事画像・参考画像が存在しない、または組織外 |
payment_required | クレジット不足、または日次上限 |
conflict | 同じ対象の処理が実行中 |
消費
1回あたり60クレジットです。article_image_ids の件数では増えません。
get_article_creative_results
案件の記事LP画像生成結果を作成日時の新しい順で取得します。
パラメータ
| パラメータ | 型 | 必須 | 既定値 | 制約 |
|---|---|---|---|---|
project_id | 文字列 | 必須 | — | UUID |
official_article_id | 文字列 | 任意 | — | UUID。generation_request_idと組で指定 |
generation_request_id | 文字列 | 任意 | — | UUID。official_article_idと組で指定 |
limit | 整数 | 任意 | 20 | 1〜50 |
応答
| フィールド | 内容 |
|---|---|
creatives[].id | 生成結果ID |
creatives[].status | queued / prompting / generating / succeeded / failed |
creatives[].errorMessage | 失敗時のメッセージ |
creatives[].size | 画像サイズ |
creatives[].strategyId | 使用した戦略仮説ID |
creatives[].articleImageIds | 使用した記事画像ID |
creatives[].createdAt | 作成日時 |
creatives[].signedUrl | 表示用の署名付きURL（1時間有効） |
creatives[].downloadUrl | ダウンロード用の署名付きURL（1時間有効） |
長時間更新がない生成中の結果は、failed として返ります。
署名URLの取り扱い
signedUrl と downloadUrl は1時間有効です。詳しくはセキュリティを 参照してください。
生成後の流れ
get_job_statusでジョブの完了を確認するget_article_creative_resultsで結果を取得する- CMO AI Proの画面で候補を比較し、確定して公開する
3の操作はMCPからは実行できません。