acedatacloud

AceDataCloud プラットフォーム管理

AceDataCloud アカウントをプログラムから管理できます。残高、利用記録、API キー、サービス、注文、プラットフォームトークン、モデル、お知らせ、紹介による 収益に加え、記事や動画の下書き、レビューのスレッド、査読を経たブログの公開も、 MCP / REST を通じて管理できます。また、トークンなしで公開カタログとドキュメント （サービスの料金、API 仕様、データセット、インテグレーション、 ドキュメント検索、モデルカタログ）を閲覧できます。

これは https://platform.acedata.cloud/api/v1 にある管理／コンソール API です。Web コンソールが使用しているものと同じ API です。画像／動画／音楽／検索の生成を行う api.acedata.cloud のデータ生成 API とは異なります。

セットアップ — サービストークンではなく、プラットフォームトークンを使用

管理 API の認証には、api.acedata.cloud で使用するサービスごとの API トークン ではなく、プラットフォームトークン（またはログイン済みユーザートークン）を使用します。

1. platform.acedata.cloud/console/platform-tokens で作成します（または POST /api/v1/platform-tokens/ を実行します）。トークンは platform- で始まり、有効期限はありません。
2. 次のいずれかの方法で指定します。
   • コネクター（スタジオ／チャットでの使用を推奨）： studio.acedata.cloud/console/connectors で AceDataCloud コネクターをインストールし、トークンを一度貼り付けます。実行環境が自動的に ACEDATACLOUD_PLATFORM_TOKEN をサンドボックスに注入します（このスキルでは connections: [acedatacloud] を宣言しています）。
   • ローカルの .env：

ACEDATACLOUD_PLATFORM_TOKEN=platform-v1-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

curl -H "authorization: Bearer $ACEDATACLOUD_PLATFORM_TOKEN" \
  https://platform.acedata.cloud/api/v1/applications/

通常のトークンから参照できるのは、自身のアカウントデータのみです。管理者操作 （お知らせの管理）には、すべてのユーザーのデータを参照できるスーパーユーザートークンが必要です。

OAuth アカウントアクセス

OAuth アクセストークンはアカウントリソースへのアクセスを認証するもので、モデル API キーではありません。OAuth の同意によってキーが作成されたり、サービスが契約されたり、残高が追加されたりすることはありません。サードパーティのアカウントを接続するには、次の手順に従います。

1. https://auth.acedata.cloud/user/oauth-apps でアプリを登録します。より広範な Discovery の scopes_supported リストではなく、認証済みの GET https://auth.acedata.cloud/api/v1/oauth2/applications/ から available_scopes を読み取ります。ユーザーが保有する登録済み権限のみを要求します。たとえば、profile:read credentials:read を要求し、確認済みの Key 変更がある場合のみ credentials:write を追加し、リフレッシュが必要な場合のみ offline_access を追加します。旧式の profile、email、phone、platform スコープは別名として受け付けられません。profile:read や email:read などの現在の明示的なスコープを使用してください。account セレクターは、指定された公式アカウント MCP 用に予約されており、サードパーティー向けの全権限スコープではありません。
2. response_type=code、client_id、登録済みの正確な redirect_uri、スペース区切りの scope、新しいランダムな state、S256 PKCE を指定して https://auth.acedata.cloud/oauth2/authorize を開きます。パブリッククライアントは plain ではなく S256 を使用する必要があります。verifier はアプリケーション独自のセッション内に保持します。コールバックの state を検証してから、単回使用のコード（有効期間は10分）を交換します。フォームフィールド grant_type=authorization_code、client_id、redirect_uri、code、code_verifier を指定して POST https://auth.acedata.cloud/oauth2/token を使用します。コンフィデンシャルクライアントは、サーバー側の client_secret も送信します（HTTP Basic ではなく client_secret_post）。ブラウザーページにシークレットを決して配置しないでください。実際に付与された scope と expires_in を読み取ります。id_token は返されません。
3. OAuth Bearer トークンを使って GET https://auth.acedata.cloud/api/v1/users/me を読み取り、credentials:read が付与されている場合は、その実際の id を使って GET https://platform.acedata.cloud/api/v1/credentials/?user_id=<id>&limit=100&offset=0 を呼び出します。items[*].token を読み取り、offset／limit でページを切り替え、最初の項目をそのまま選ぶのではなく、目的のアプリケーション／サービスに適した有効な Key を選択します。user_id=me は無効です。リストが空でも、認可エラーとは限りません。Key、コード、トークン、PKCE verifier を表示またはログに記録しないでください。
4. 現在の Studio アカウントを使う Studio ウェブサイトコンポーネントでは、Settings → Home → Website でアプリ ID とコールバックを設定します。ウェブサイトとコールバックは、Studio とは異なる同一の HTTPS オリジンを共有する必要があります。クライアントシークレットは決して設定しないでください。ページは acedatacloud:oauth:ready、acedatacloud:oauth:init、acedatacloud:oauth:authorize、acedatacloud:oauth:result を実装し、正確な親オリジン、親ウィンドウ、state を検証する必要があります。verifier はローカルに保持し、返されたコードを交換します。このコンポーネントが要求するのは profile:read credentials:read であり、offline_access やブログ権限は要求しません。訪問者ごとに個別の同意が必要です。Studio のログイントークンや Key が注入されることはありません。標準的な OAuth リダイレクトでは、このメッセージプロトコルや embed=studio／embed_origin は不要です。通常の iframe では初回ログイン後の継続に既知の問題があるため、ログアウト済み／期限切れのセッションを確認するか、独立したページを使用してください。拒否または login_required の場合は、認可を繰り返し続けず、再試行可能な接続状態に戻してください。
5. offline_access が付与されている場合のみ、保存済みのリフレッシュトークンを使い、grant_type=refresh_token を指定してトークンエンドポイントでリフレッシュします。最新のレスポンスを保持してください。リフレッシュしても、古いリフレッシュトークンが直ちに無効になるとは限りません。フォームフィールド token を指定した POST https://auth.acedata.cloud/oauth2/revoke は、現在、発行済み JWT を直ちに無効化せずに HTTP 200 を返します。独自に保存した接続状態は消去しますが、すべてのトークンが失効したと報告しないでください。コピーされた API Key は、認証情報管理で個別に失効またはローテーションする必要があります。

同梱の CLI は OAuth アプリの登録やブラウザー／PKCE での交換を行いません。invalid_scope が発生した場合は、アクセス範囲を広げるのではなく、アプリに登録されたスコープ、委任の制限、ユーザー権限を確認してください。接続に依存する前に、拒否、state の不一致、コードの期限切れ／使用済み、不足しているスコープ、Key がない場合、ネットワーク障害、トークンの期限切れ、iframe 内でのアカウント変更を検証してください。

CLI（推奨）

このスキルには、一般的な操作に対応する自己完結型の CLI（標準ライブラリのみ）である scripts/acedatacloud.py が含まれています。

# $SKILL_DIR can point at another skill loaded this turn — anchor on our own
# script (re-run this at the top of every fresh-shell Bash block).
ADC="$SKILL_DIR/scripts/acedatacloud.py"; [ -f "$ADC" ] || ADC=$(find /tmp -maxdepth 8 -path '*/skills/*/scripts/acedatacloud.py' 2>/dev/null | head -1)
[ -f "$ADC" ] || { echo "acedatacloud script not found (SKILL_DIR=$SKILL_DIR)" >&2; exit 1; }

# Read
python3 $ADC balance                         # remaining credits per subscription
python3 $ADC services --search suno          # list/search subscribed services
python3 $ADC usage --days 7                   # recent API call records
python3 $ADC usage-summary --days 30          # spend aggregated by day + API
python3 $ADC keys                             # list API keys (credentials)
python3 $ADC orders --state Finished          # recharge orders
python3 $ADC tokens                           # platform tokens
python3 $ADC models                           # available chat models
python3 $ADC distributions                    # referral status + commission history

# Catalog & docs (PUBLIC — work without a token)
python3 $ADC get-service --service suno       # one service's detail
python3 $ADC pricing --service suno           # unit, free_amount and cost (dataset reference quotes when present)
python3 $ADC apis --service suno              # API endpoints for a service
python3 $ADC spec --path /suno/audios         # one API's OpenAPI definition + cost
python3 $ADC datasets                         # downloadable datasets
python3 $ADC integrations                     # third-party integrations
python3 $ADC docs-search --query "suno lyrics" --lang en   # full-text doc search
python3 $ADC docs-list                        # browse documentation pages
python3 $ADC doc --id <document-uuid>         # one doc's full content
python3 $ADC model-catalog --modality chat    # rich model catalog + credit pricing
python3 $ADC model --model claude             # look up a model by id/name

# Safe write (require --yes to actually execute)
python3 $ADC create-key  --application <app-id> --name "ci" --yes
python3 $ADC delete-key  --id <credential-id> --yes
python3 $ADC create-order --application <app-id> --package <package-id> --yes
python3 $ADC pay-order   --id <order-id> --pay-way Stripe --yes
python3 $ADC create-token --yes
python3 $ADC delete-token --id <token-id> --yes

# Admin (superuser token only)
python3 $ADC send-announcement --title "..." --content "..." --yes

すべてのコマンドで、機械可読な出力を得るための --json と、環境変数のトークンを上書きする --token を指定できます。--yes を指定しない場合、書き込みコマンドはドライランのプレビューを表示し、API を呼び出さずに終了します。

ページネーション

一覧エンドポイントは { "count": <total>, "items": [ ... ] } を返し、?limit= と ?offset= を受け付けます。（注：一部の古いドキュメントには results と記載されていますが、現在のフィールドは items です。）

エンドポイントのリファレンス

残高／サブスクリプション — GET /applications/

Application は、1 つの Service に対するサブスクリプションです。その remaining_amount は、そのサービスで利用できる残高（Credits）です。

curl -H "authorization: Bearer $ACEDATACLOUD_PLATFORM_TOKEN" \
  "https://platform.acedata.cloud/api/v1/applications/?limit=1"

{
  "count": 3,
  "items": [
    {
      "id": "e9f625f2-cbd5-4254-8264-cfadbd180428",
      "service_id": "f2b646d8-3cfd-46ef-969a-1ea9eebde329",
      "remaining_amount": 100.9,
      "used_amount": 1.1,
      "paid": false,
      "scope": "Global",
      "allow_consume_global": true,
      "expired_at": null,
      "type": "Usage"
    }
  ]
}

フィルター：service_id、scope（Individual／Global）、user_id（スーパーユーザーのみ）。

使用記録 — GET /usage/apis/

リクエストごとの呼び出し記録（ステータスコード、レイテンシ、差し引かれたクレジット）。

フィルター：api_id、application_id、status_code、created_at_from、 created_at_to、user_id（スーパーユーザーのみ）。

{
  "count": 128,
  "items": [
    {
      "id": "c124684b-7188-4c3e-ad53-3fba5150b944",
      "api": { "title": "Suno Audios Generation API" },
      "status_code": 200,
      "original_amount": 0.55,
      "deducted_amount": 0.55,
      "trace_id": "…",
      "elapsed": 12.3,
      "created_at": "2026-06-28T09:15:44Z"
    }
  ]
}

• 使用額の集計 — GET /usage/apis/aggregate/?created_at_from=&created_at_to= → { "items": [{ "date", "api_id", "amount" }], "total": <credits>, "apis": { "<id>": { "title" } } }
• ステータスコードのフィルター値 — GET /usage/apis/status-codes/ → { "items": [200, 400, 502] }
• CSV エクスポート — GET /usage/apis/export/?created_at_from=&created_at_to=（usages.csv をダウンロードします）

サービス — GET /services/

{ "count": 215, "items": [ { "id": "…", "alias": "suno", "title": "Suno 音乐生成",
  "unit": "Credit", "free_amount": 0.0, "applied_count": 121733,
  "packages": [ { "id": "…", "type": "Usage", "price": 13.0, "amount": 100.0 } ] } ] }

API キー／認証情報 — GET /credentials/

{ "count": 2, "items": [ { "id": "dae4899f-…", "name": "ci", "type": "Token",
  "token": "<secret>", "limited_amount": null, "used_amount": 1.1,
  "host": null, "created_at": "2026-06-28T09:15:44Z" } ] }

• 作成 — POST /credentials/ { "application_id": "<app>", "name": "ci", "limited_amount": 100, "expired_at": "2026-12-31T00:00:00Z" } → 新しい token を含む認証情報が返されます。保存してください。完全なトークンが表示されるのは作成時のみです。
• 削除 — DELETE /credentials/{id} → 204 No Content
• フィルター：application_id、host、granted（true／false）、user_id（スーパーユーザー）。
• キーを「ローテーション」するには、削除して新しいキーを作成してください。

注文（チャージ） — GET /orders/

{ "count": 12, "items": [ { "id": "17c10c9d-…", "application_id": "…",
  "package_id": "…", "description": "100 Credits", "price": 13.0,
  "state": "Finished", "pay_way": "Stripe", "pay_url": "<url>",
  "created_at": "2026-06-28T09:17:25Z" } ] }

• state ∈ Pending Paid Finished Expired Failed Refunded
• pay_way には WechatPay、AliPay、Stripe、X402、PayPal、Reward、BankTransfer が含まれます。利用可否は注文と決済設定によって異なります。
• 作成 — POST /orders/ { "application_id": "<app>", "package_id": "<package>" }
• 支払い — POST /orders/{id}/pay/ { "pay_way": "Stripe" } → 開くための pay_url を含む注文が返されます
• ステータスを更新 — POST /orders/{id}/refresh/（PSP を再確認し、state を更新します）
• フィルター：state、pay_way、created_at_from、created_at_to、user_id（スーパーユーザー）。

銀行振込

1. 注文者として認証します。個人アカウントと法人アカウントは、エンタープライズ認証なしで BankTransfer を利用できます。匿名リクエストでは利用できません。国内の CNY 振込と国際的な USD 振込はどちらも、決済チャネルの設定とパッケージの適格性に応じて、USD 300 以上の注文が必要です。
2. 管理ホストで GET /api/v1/orders/{order_id}/payment-options/ を読み込み、現在の振込方法と最低金額を確認します。CLI に決済オプション用のコマンドはありません。存在しないフラグを指定せず、認証済みの REST を使用してください。内部のルート／プロバイダー識別子を公開しないでください。
3. pay-order --id <order-id> --pay-way BankTransfer --yes を実行する前に、注文 ID、金額、利用可能な振込方法をユーザーに確認してください。その注文について返された支払い手順のみを使用してください。表示された CNY 金額が正しい金額であり、ローカルで推定した換算額ではありません。支払いレスポンスは入金の証明にはなりません。注文を再取得し、最終状態を確認してから完了を報告してください。

請求書の取り消しと再申請

1. 認証済みの GET /api/v1/orders/{order_id}/invoice/ で現在の請求書を読み取ります。CLI に請求書コマンドはありません。
2. 自動の赤伝票取り消し申請後も、請求書は Issued のままです。進捗は red_state で確認してください。申請は完了を意味しません。確認、赤伝票の発行、またはアーカイブが保留中の間は、再申請しないでください。
3. 元の請求書が赤伝票の発行とアーカイブの完了によって Voided になり、注文の請求制限が解除された後にのみ再申請してください。取り消しに失敗した場合や状態が不明な場合は、財務部門の確認が必要です。制限を回避しないでください。元の請求書は請求書履歴に残ります。手動で発行した請求書は、まず税務／請求システムで無効化または取り消し、その後、プラットフォーム上で財務部門の確認を受ける必要があります。

X402 ネットワークの選択

1. ネットワークを選択する前に、現在の注文または API の支払いチャレンジにある accepts を読み取ります。Arbitrum One（公式の TypeScript／Python X402 クライアントでは arbitrum、通信上の CAIP-2 では eip155:42161）は、オプトインによるコードサポートであり、本番環境で利用できる保証はありません。accepts にない場合、そのチェーンで支払いを試みないでください。ページの機能フラグを有効にしても、未設定のサーバーネットワークは有効になりません。
2. Arbitrum が対応するのは、ネイティブ USDC（小数点以下 6 桁）による exact 支払いのみであり、ブリッジされた USDC や upto には対応していません。返されたアセット、宛先、accepts[].maxAmountRequired を使用してください。金額をハードコードしたり、支払いパラメーターを推測で作成したりしないでください。
3. ウォレットが対象チェーンに対応しており、そのチェーン上に USDC があることを確認します。同じ EVM アドレスでも、ネットワークによって残高が異なる場合があります。Solana アドレスは EVM の USDC アドレスではありません。署名または支払いの前に確認を得てください。ネットワークへの対応は、課金の許可を意味するものではありません。

X402 の失敗からの復旧

1. PAYMENT-SIGNATURE を含まない最初の HTTP 402 は支払いチャレンジであり、支払いの失敗ではありません。署名済み支払いが失敗した場合は、extensions.acedatacloud.paymentError を読み取ってください。推測に基づいてウォレット署名や宛先／アセットのアドレスを作成しないでください。
2. 認証済みの注文一覧（orders --json）または GET /api/v1/orders/{order_id}/ を再読み込みします。metadata.x402.last_error と metadata.x402.errors には公開される code、stage、retryable、charged、params が保持され、説明は reason、時刻は timestamp に記録されています。具体的なコードをそのまま保持してください。insufficient_token_balance は選択したネットワーク上の USDC 不足を意味し、invalid_signature は無効な支払い署名を意味します。再読み込み後に、どちらも汎用的な payment_failed に置き換えないでください。
3. 明示的に charged=false の場合のみ、決済前の拒否を意味します。charged がない場合は、未請求ではなく不明です。再度支払う前に、支払いの証跡を確認してください。retryable=true であっても、Failed の注文はその場で再試行できません。ウォレットの問題を解決し、新しい注文を作成して支払う前に確認を得てください。
4. サポートには注文 ID と公開エラーコードのみを共有してください。注文のメタデータ全体、PAYMENT-SIGNATURE、ウォレット署名、認可ペイロード、生の支払い／RPC 診断情報は、記録も共有もしないでください。

X402 ACE 買い戻しとバーンの証明

買い戻しポリシーが有効な場合、対象となる Base メインネットの Circle USDC と Solana メインネットの USDC による支払いでは、実際に受け取った金額の 3% が ACE の買い戻しとバーンに割り当てられ、ウォレットへの追加請求はありません。チャージは 1 回のみ計上されます。これらのクレジットを API で使用しても、再度計上されることはありません。過去の割引注文や旧ポリシーの注文は、自動的に遡って処理されません。操作ごと、または 1 日あたりの USDC 買い戻し上限は固定されていませんが、利用可能な資金、市場価格、チェーンの承認によって完了が遅れる場合があります。

1. 管理ホスト上で、注文の所有者として認証済みの GET /api/v1/orders/{order_id}/ を読み取り、ace_burn を確認します。CLI で確認できるのは注文一覧のみで、注文詳細やバーンのコマンドはありません。注文一覧と匿名の支払いリンクのレスポンスには ace_burn が含まれていません。項目が存在しない、または null の場合、対象条件を満たすと判断したり、証明を捏造したりしないでください。
2. 支払いレシート（settlement_network、settlement_transaction）と、非同期の ACE 実行（execution_network）を区別してください。Base での支払いには Base のレシートが保持されます。ACE の買い戻しとバーンは Solana で行われます。Base のレシートは Solana のバーントランザクションではありません。運営者の設定や内部の資金調達に関する詳細は公開しないでください。
3. 実際に返された swap_signature と burn_signature を使い、ace_burn.state=Completed の場合にのみ、バーンの完了が確認されたと報告してください。Pending、Processing、または Review はバーンの証明ではなく、注文の Finished 状態もバーンが完了した証明にはなりません。Base ソースのファイナリティによってバーンが遅れる場合がありますが、クレジット付与には影響しません。同じ注文を再読み込みして進捗を確認してください。バーンを実行させるために、再度支払ったり別の注文を作成したりしないでください。

プラットフォームトークン — GET /platform-tokens/

{ "count": 2, "items": [ { "id": "efdccba4-…", "token": "<secret>",
  "expiration": null, "used_at": null, "created_at": "2026-06-28T06:29:02Z" } ] }

• 作成 — POST /platform-tokens/ → 新しいトークンを返します（platform- で始まります）
• 削除 — DELETE /platform-tokens/{id}/ → 204 No Content

モデル — GET /models/

OpenAI 形式（ページネーションなし）：{ "object": "list", "data": [ { "id": "gpt-4.1", "label": "GPT-4.1", "owned_by": "openai", "type": "chat", "capabilities": ["vision"] } ] }

カタログとドキュメント（公開 — トークン不要）

認証なしで利用できます（トークンがある場合は送信できますが、必須ではありません）。

• サービス詳細／料金 — GET /services/?id=<uuid> → items[0]（全項目：cost、unit、 free_amount、title）。services/?alias= フィルターはサーバー側で無視されるため、services/ のページを順に取得し、 クライアント側で alias を照合してエイリアスを解決してください。services/{id}/ の詳細ルートは機能せず、500 を返します。
• API — GET /apis/?path=<path> → OpenAPI の definition と cost を含む項目を 1 つだけ返します。 apis/?service_id= はサーバー側で無視されるため、クライアント側で service_id を使って絞り込んでください。apis/{id}/ は機能せず、500 を返します。
• データセット／連携機能 — GET /datasets/、GET /integrations/。
• ドキュメント検索 — GET /search/?query=<text>&lang=<code> → { results: [ { id, alias, title, type, snippet, url } ] }。 パラメーターは keyword ではなく query です。
• ドキュメントの内容 — GET /documents/?id=<uuid> → items[0].content。documents/{id}/（id または slug）は機能せず、404 を返します。
• モデルカタログ — GET /models/catalog/ → { rates, modalities, count, items:[{ id, name, provider, modality, unit, capabilities, pricing:{ input_credits, output_credits, official_* } }] }。クライアント側で絞り込んでください。

地域別カタログの確認

1. 呼び出し元の環境から、現在の公開カタログを読み込みます。get-service --service <alias-or-uuid> --json を使って、available_regions、unavailable_regions、サービスのチャット専用項目である chat_unavailable_regions、画像専用項目である image_unavailable_regions を確認します。API／ドキュメントの地域フィールドを確認するには、apis --service <alias-or-uuid> --json、docs-list --json、または doc --id <document-uuid> --json を使います。pricing と spec の概要にはこれらのフィールドは含まれません。地域リストが空でも、明示的な地域ルールがないという意味であり、アクセスが許可されているわけではありません。
2. 表示内容は、表示言語や ?country= による指定ではなく、リクエストを行うユーザーの IP アドレスに基づきます。中国本土向けのカタログ表示では、対象となる Claude サービスとチャット API／ドキュメントは非表示になります。OpenAI、Gemini、Grok が混在するサービスではチャット項目が非表示になりますが、メディアの表示可否は個別に確認してください。OpenAI の画像生成／編集と関連ガイドも中国本土では非表示になります。chat_unavailable_regions または image_unavailable_regions に基づいてサービス全体を非表示にしないでください。無関係なメディア項目には、それぞれ独自のルールが適用されます。生の REST／CLI の結果には対象の行が含まれる場合があります。表示する選択肢を提示する際は、存在していることを表示可能の根拠とせず、地域メタデータを適用してください。
3. カタログの選択肢を提示する際は、現在の公開結果に従ってください。キャッシュされたグローバルリストを使って、地域制限で非表示のチャットや画像を案内しないでください。また、項目がないことや 404 を、提供終了や API アクセスの取り消しの証拠とみなさないでください。この表示上のフィルタリングによって、API のルーティングや課金が変わることはありません。サービスを呼び出す前に、実際のアカウントアクセス、キーの制限、現在の料金を別途確認してください。

データセットの参考価格

1. get-service --service <alias-or-uuid> で、指定されたデータセットの公開サービスを特定し、現在のメタデータを確認します。問い合わせが必要なデータセットはカタログ項目であり、自動的にダウンロード可能な購入対象になるわけではありません。価格が表示されていなくても、データが無料という意味ではありません。
2. pricing --service <alias-or-uuid> --json を実行します。Dataset の場合、値が設定されていれば CLI は pricing_mode と reference_quote を含めます。元のフィールドは Service の metadata.pricing_mode と metadata.reference_quote であり、Dataset の price や API の cost ではありません。
3. pricing_mode="contact_only" で、見積もりの status="reference" の場合は、指定された currency と見積もりの unit とともに min_amount～max_amount を提示します。CNY の金額は人民元であり、Credits や USD ではありません。full_package はパッケージ全体、tb は 1 TB あたりを意味します。上下限が等しい場合は、参考価格が単一の金額であることを示します。Credits から USD への換算を適用したり、返されていない見積もりを作り出したりしないでください。
4. 参考価格はあくまで目安として扱ってください。購入用 Package が作成されたり、納品が保証されたり、ダウンロード権や使用権が付与されたりするものではありません。手続きを進める前に、必要なバージョン、範囲、形式、ライセンス、最終価格をサポートに確認してください。参考価格に基づいて create-order または pay-order を呼び出さないでください。

お知らせ — GET /announcements/

公開読み取り：{ "count": 20, "items": [ { "id", "title", "content", "translation_key", "published", "publish_at", "rank", "tags", "is_read" } ] }

管理者のみ（スーパーユーザートークン）：

• 公開 — POST /announcements/admin/ { "title": "...", "content": "...", "rank": 5, "tags": ["product"], "published": true } （content は Markdown です。zh-cn の Translation 行が作成され、その他のロケールは CronJob によって自動翻訳されます）
• 編集／削除 — PUT／DELETE /announcements/admin/{id}
• AI による文章の調整 — POST /announcements/admin/polish/ { "title", "content" }
• AI 翻訳 — POST /announcements/admin/translate/ { "translation_key" }

ブログの下書き、レビュー申請、公開（MCP／REST）

プラットフォームトークンまたは Studio OAuth 接続を使って mcp-acedatacloud を利用します。同梱の CLI はブログ用コマンドを実装していません。CLI フラグを独自に作らず、MCP ツールを使用し、現在の入力スキーマを確認してください。ブログの権限は管理者以外のアカウントにも委任できます。書き込みを行う前に、利用可能なツールとスコープを確認してください。

権限	操作
blog:read	下書きの一覧表示と、編集用ソースコンテンツ全体の読み取り
blog:write	未公開の下書きの作成、編集、削除、保留中のレビューの申請または取り下げ
blog:read + blog:publish	申請されたバージョンの承認または却下、または公開前の承認取り消し
blog:write + blog:publish	承認済みの下書きの公開または公開予約、公開停止、または公開済み記事の削除

1. 対象の記事とソース言語（zh-cn または en）を確認します。現在の編集カテゴリ（product-updates、tech-sharing、product-recommendations、industry-insights）を使用します（デフォルトは tech-sharing）。カスタムカテゴリが必要な場合は、現在のカテゴリ一覧を読み取り、スラッグを推測しないでください。
2. acedatacloud_create_blog_draft で未公開の下書きを保存するか、acedatacloud_update_blog_post で編集します。タイトル、概要、本文、カテゴリ、カバー、content_type、video_url を含むソース全体を acedatacloud_get_blog_draft で読み取り、現在の review_version と review_status を保持します。デフォルトの content_type="article" では空でない本文が必要で、video_url はクリアされます。content_type="video" の場合は、先に対象の動画をアップロードし、実際の HTTPS video_url を使用します。本文は空でも構いませんが、タイトルと概要は必須です。メディア URL を捏造しないでください。カバーには HTTPS の cover_url と空でない cover_alt が必要です。取得した MCP スキーマに動画フィールドがない場合は、確認後に POST /api/v1/blogs/admin/ で未公開の下書きを作成するか、PATCH /api/v1/blogs/admin/{id}/ で編集します。MCP の引数や CLI フラグを捏造しないでください。
3. 承認を求める前に、draft または rejected の記事をレビューに申請します。blog:write 権限がある場合、管理ホストで {"expected_version": CURRENT_REVIEW_VERSION} を指定して POST /api/v1/blogs/admin/{id}/submit/ を送信し、review_status="pending" であることを確認します。作成者が設定されていない旧形式の下書きは、まず編集者が保存する必要があります。保留中の記事は編集できません。現在の expected_version を指定して同じ /submit/ ルートに DELETE を送信し、レビュー申請を取り下げます。draft であることを確認してから編集し、再申請します。保留中のレビューの取り下げは、承認の取り消しとは異なります。
4. 別の認可済みアカウントで保留中の下書き全体を読み取り（動画記事の場合は実際の動画も視聴し）、その正確なバージョンを acedatacloud_approve_blog_post で承認する必要があります。作成者は自分の下書きを承認できません。REST で承認する場合、POST /api/v1/blogs/admin/{id}/approval/ の expected_version は、読み取った review_version と一致している必要があります。レビュアーは代わりに、その expected_version と空でない comment（最大 2,000 文字）を指定して POST /api/v1/blogs/admin/{id}/reject/ を送信することもできます。現在のバージョンに未解決のルートレビュースレッドがすでにある場合は、comment を省略できます。review_status="rejected" であることを確認します。review_comment を読み取り、修正して再申請します。次のレビューに進む前に、以下のレビュースレッドを確認してください。申請、取り下げ、承認、却下で 409 が返された場合は、下書きが変更されています。再試行する前に更新し、下書き全体を再度読み取ってください。この役割分担を回避するために、レビュアーになりすましたり、認証情報を切り替えたりしないでください。
5. review_status="approved" になった後に限り、認可済みアカウントから acedatacloud_publish_blog_post を使用します。公開者はレビュアーと異なる必要があります（作成者はピアレビュー後に公開できます）。公開予約の場合は、タイムゾーン付きの publish_at を指定します。今すぐ公開する場合は省略します。記事が一般公開されたと報告する前に、返された状態と時刻を確認してください。
6. レビュー済みの公開コンテンツ（タイトル、本文、カテゴリ、タグ、スラッグ、カバー、content_type、video_url を含む）を変更すると、承認は無効になり、review_version が進みます。公開済みの記事を編集する前に acedatacloud_unpublish_blog_post で公開を停止し、再公開する前に再度申請して新たにピア承認を得ます。未公開の状態で承認を取り消すには acedatacloud_withdraw_blog_approval を使用します。承認済みの記事は draft に戻ります。

レビュースレッド（認証済み REST）

レビューコメントは非公開の編集フィードバックであり、公開ブログのコメントではありません。管理ホストとプラットフォームの Bearer トークンを使用してください。一覧表示には blog:read が必要です。追加、返信、解決には blog:read と、blog:write または blog:publish のいずれかが必要です。

1. 保存済みの下書きと GET /api/v1/blogs/admin/{id}/comments/ を読み込みます。レスポンスは、ネストされた replies、アンカー、review_version、解決フィールドを含むルートスレッドの配列です。各スレッドのバージョンを現在の下書きと比較してください。過去のフィードバックだけでは、選択範囲が現在のテキストと一致しているとは限りません。
2. プレビューを確認し、明示的な確認を得た後、POST /api/v1/blogs/admin/{id}/comments/ でルートコメントを追加します。現在の expected_version、2,000文字以内の空でない body、オフセットや引用文を指定しない field="overall" を送信します。テキスト範囲を指定する場合は、field="title"、"summary"、または "content" を使い、start_offset、end_offset、保存済みテキストと完全に一致する quote を指定します。オフセットは Python の文字数や UTF-8 のバイト数ではなく、UTF-16 コード単位で数えます。開始位置は含み、終了位置は含みません。選択範囲は最大 2,000 コード単位です。未保存のテキストにはアンカーを設定しないでください。409 が返された場合は、下書きを再読み込みして選択範囲を計算し直してください。引用文が一致しない場合は、オフセットを推測せず、保存済みのソースを読み直してください。
3. POST /api/v1/blogs/admin/{id}/comments/{comment_id}/replies/ と {"body":"REVIEW_REPLY"} を使って、ルートスレッドに返信します（空でない 1～2,000 文字）。返信にはルートのレビュー バージョンが引き継がれます。解決済みのスレッドに返信すると、再び未解決になります。返信 ID ではなく、ルート ID を使用してください。
4. PATCH /api/v1/blogs/admin/{id}/comments/{comment_id}/ と {"resolved":true} または {"resolved":false} を使って、ルートスレッドを解決または再び未解決にします。返信と解決には expected_version は不要です。送信前にスレッドを再読み込みし、ID と実行する操作を確認してください。フィードバックを解決しても、下書きが承認または公開されるわけではありません。上記のピアレビューワークフローを続けてください。

ブログへのすべての書き込みには、プレビューとユーザーによる明示的な確認が必要です。confirm=true がない場合、MCP ツールはドライランのプレビューのみを返します。上記の REST レビュールートはすぐに実行され、ドライランフラグはありません。メソッド、記事 ID、本文をローカルでプレビューし、プラットフォームの Bearer トークンを使って送信する前に確認を得てください。検出されたスキーマがその操作に対応している場合は、対応する MCP ツールを優先してください。送信または却下のためのツール名や CLI フラグを作り出してはいけません。実行前に記事、バージョン、公開時刻を確認してください。プレビューが成功しても、投稿が保存、送信、承認、公開された証拠にはなりません。必要な操作または権限を利用できない場合は、作業を中止して適切な認可を求めてください。

書き込み操作の安全性

キーの作成や削除、注文の作成や支払い、プラットフォームトークンの削除、および告知やブログの公開は、取り消し不能、金銭関連、または一般公開される操作です。必ず次のことを守ってください。

1. 実行前に、対象（application_id、order_id、credential_id）をユーザーに確認します。
2. CLI を使う場合、--yes を渡さない限り、書き込みはドライランになります。
3. アカウントへのアクセス権を与える token の値全体を、共有ログに出力しないでください。

注意点

• api.acedata.cloud サービスのトークンではなく、プラットフォームトークン（ACEDATACLOUD_PLATFORM_TOKEN）を使用してください。後者ではここで 401 が返されます。
• remaining_amount / used_amount / amount の単位は USD ではなく、Credits です。サービスのパッケージを使って換算してください：USD = Credits × (package.price / package.amount)。
• 新しく作成した認証情報／プラットフォームトークンは、完全な値が返されるのは一度だけです。すぐに保存してください。
• 認証情報の「ローテーション」は削除して再作成する操作です。既存の認証情報をそのままローテーションするエンドポイントはありません。
• /admin/ 配下のアナウンスメントエンドポイントには、スーパーユーザートークンが必要です。通常のトークンでは 403 が返されます。

MCP： pip install mcp-acedatacloud | ホステッド版：https://mcp.acedata.cloud/mcp | すべての MCP サーバーを参照してください。MCP はこれらをツール（acedatacloud_get_balance、acedatacloud_list_usage、acedatacloud_get_pricing、acedatacloud_search_docs、acedatacloud_get_api_spec、acedatacloud_create_credential、…）として公開し、同じ書き込み確認ガードを適用します。