API と MCP ドキュメント

無料APIは、ブラウザツールとは別のクラウド機能です。Googleでログインし、Googleが確認済みの@gmail.comアカウントでTurnstileを通過すると、カードなしでUTCの暦月ごとに500クレジットを利用できます。ただし月額$20の無料計算予算の対象です。

有効化後にアカウント設定ページでAPIキーを作成します。同じアカウントのすべてのキーは、同じクレジットプール、レート制限、未完了ジョブ上限を共有します。無料計算予算が尽きると、新しい無料ジョブは表示されたリセット時刻まで停止します。有料Developerジョブとブラウザ内圧縮は別に継続します。

GIFファイルと、JSONを格納したoptionsフィールドを含むmultipartリクエストを送信します。目標サイズモードではtargetBytesに10進数のバイト数を指定してください。modeやtargetBytesを個別のフォームフィールドとして送信しないでください。

作成リクエストには毎回、アカウント単位のIdempotency-Keyが必要です。同じキー、ファイル、オプションで再送すると、クレジットを再予約せずに元のジョブを返します。

作成レスポンスにはトップレベルのidが含まれます。JOB_IDとして保存し、ステータスURLで使用してください。jobプロパティの内側にはありません。作成レスポンスだけではダウンロードリンクは返りません。すでに完了したジョブが冪等再送で返った場合でも、ステータスエンドポイントを確認してください。例のYOUR_JOB_IDをそのidに置き換え、succeededレスポンスのresult.downloadUrlをDOWNLOAD_URLにコピーしてからダウンロードコマンドを実行します。

ステータスがqueuedまたはprocessingの間、resultはnullです。succeededになるとresult.downloadUrlとresult.expiresInSecondsを取得できます。failedまたはcanceledの場合は、ダウンロードを再試行せず、error.codeとerror.messageを確認してください。

数秒ごとにポーリングし、アカウントの読み取り制限内に収めてください。ファイルにまだアクセスできる間は、新しいステータス取得で期限切れのダウンロードリンクを更新できます。リンクは最長15分で、ファイルアクセス期限の24時間を超えることはありません。ポーリング、ダウンロード、完全に同じ冪等再送ではクレジットを消費しません。

JSON形式の作成リクエストでは、sourceUrlとoptionsを使用します。サーバーはHTTPS URLのみを取得し、リダイレクトごとに検証し、プライベートネットワークへのアクセスを遮断し、アップロード時と同じファイルサイズ上限を適用します。

参照先サイトがブラウザのCORSをブロックしている場合、ローカルURL取り込みは失敗することがあります。RESTのURL取り込みはクラウドジョブであり、APIキー、クレジット、レート制限、保存期間ルールが適用されます。

GET /api/v1/usageは{ usage }を返します。usageオブジェクトには、有効なプール、limit、used、reserved、remaining、resetAt、windowStart、windowEndが含まれます。作成リクエストは無料が10 rpm、Developerが60 rpm、ステータスまたは使用状況の取得はアカウントごとに120 rpmまでです。

無料APIの期間はUTCの暦月ごとにリセットされます。Developerの期間は年払いを含め、サブスクリプションの基準日に合わせて毎月リセットされます。クレジットは繰り越されません。未完了ジョブは無料アカウントが2件、Developerが20件までです。無料キューには100件まで入ります。無料ジョブの待機時間が10分を超えると終了し、予約が解放されます。

MCPエンドポイントは/api/mcpのStreamable HTTPです。compress_gif、get_compression、get_usageを提供し、RESTと同じAPIキーを使用します。

MCPではリモートのHTTPS GIF URLを指定できます。ローカルファイルはRESTでアップロードしてください。サーバー上のローカルパスや大きなBase64ペイロードをMCPツールに渡さないでください。

compress_gifにはsourceUrl、省略可能なoptionsオブジェクト、必須のidempotencyKeyを渡します。その後、返されたidをget_compressionに渡します。アダプターはRESTレスポンスをstructuredContent.dataに包みます。ツールの通信が成功しても、圧縮ジョブが完了したとは限りません。残高確認には空のオブジェクトでget_usageを呼び出します。

5MB以下の入力は、qualityまたはsizeモードで1クレジット、targetモードで2クレジットを消費します。5MBを超え20MB以下の入力は2クレジット、targetモードでは4クレジットを消費します。1回の処理試行には60秒の予算があり、エンコード候補は最大8つです。

検証失敗、システム障害、タイムアウトではユーザーのクレジットを消費しません。有効な結果が得られたものの要求した目標サイズに届かなかった場合は、計算処理が完了しているため、提示済みの見積もりを消費します。そのジョブにはtargetMet: falseと表示されます。

ジョブのcreditsおよびcost.creditsフィールドは見積もり費用を示すもので、決済済みの証明ではありません。クレジットはジョブ受付時に予約され、成功時に確定し、失敗時に解放されます。現在のused、reserved、remainingは/api/v1/usageで確認してください。

一般的なエラーコードには、API_KEY_REQUIRED、API_KEY_INVALID、INSUFFICIENT_CREDITS、FREE_API_NOT_ACTIVE、IDEMPOTENCY_CONFLICT、INPUT_TOO_LARGE、INVALID_GIF、RATE_LIMITED、TOO_MANY_OUTSTANDING_TASKS、FREE_COMPUTE_BUDGET_EXHAUSTEDがあります。

401はAPIキーがない、または無効な場合です。402はユーザーのクレジットが尽きた場合にのみ使われます。403は無料APIが有効化されていない場合、409は冪等性の競合、413はクラウド入力サイズ上限超過、422はGIFデータまたはオプションが無効な場合です。429は作成・読み取りのレート制限または未完了ジョブ数の上限を示します。503は一時的なキュー混雑またはFREE_COMPUTE_BUDGET_EXHAUSTEDです。Retry-Afterがある場合はそれに従ってください。

ブラウザでのローカル圧縮とクラウドAPIジョブでは、データの流れが異なります。GIFを端末内に留めたい場合はブラウザツールを使い、リモートワークフローで処理する必要がある場合はRESTまたはMCPを使ってください。

ブラウザツールはGIFをアップロードしません。URLからの取り込みでは画像の配信元サイトに直接アクセスします。APIとMCPではファイルをアップロードするか、サービスが公開HTTPS URLから取得します。アプリ、データベース、ファイルストレージはCloudflare上でホストされます。APIの入力・出力ファイルへのアクセスは24時間後に失効し、ダウンロードリンクは最長15分です。バックグラウンドのクリーンアップで期限切れファイルを削除するため、物理的な削除は後になる場合があります。信頼性と利用状況を測るため、圧縮の成功・失敗、入力・出力サイズ、目標達成状況、ダウンロードなどの技術イベントをCloudflareのサービスログに記録します。これらのイベントにはファイル名、取得元URL、ファイル内容は含まれません。Cloudflareはサービスの配信と保護に必要なリクエストデータも処理します。製品イベントログは最長7日間保存します。

作成、ステータス、使用状況の各リクエストではAuthorization: Bearer YOUR_API_KEYを送信してください。APIはx-api-keyヘッダーにも対応しています。アカウントのサインインCookieはAPIキーの代わりにはなりません。同じアカウントに属するすべてのキーは、利用枠と制限を共有します。

キーはサーバー側の環境変数、またはAIクライアントの保護された設定に保存してください。公開Webページ、リポジトリ、画像URLに置かないでください。キーが漏えいした場合は、APIキー設定で取り消して新しいキーを作成してください。無料のブラウザツールにはAPIキーは不要です。

modeはquality、size、targetを受け付け、初期値はqualityです。targetでは、10進バイトで測った正の整数targetBytesが必要です。100KBは100000、1MBは1000000です。multipartアップロードでは、これらのフィールドをJSONエンコードしたoptionsフィールド内に入れてください。

任意のcolorsはauto、64、128、256を受け付けます。lossyLevelは0から200までの整数です。widthは1から4096までの整数で、リサイズを要求します。元のサイズを維持する場合は省略してください。フレーム削除や形式変換のオプションはありません。

1リクエストで処理できるGIFは1つです。Free APIの入力は5MBまで、Developerの入力は20MBまでです。どちらも各辺は最大4096ピクセル、最大1,000フレーム、width × height × frame countは最大50,000,000です。短くても非常に大きいアニメーションでは、バイト数の上限より先にこれらの安全制限に達することがあります。

新しいファイルとオプションの組み合わせごとに新しいIdempotency-Keyを選び、ネットワーク応答が不確かな場合の再試行では同じキーを使い続けてください。キーは1〜128文字の印字可能な、空白を含まないASCII文字です。同一の再送は既存タスクを返します。同じキーで入力またはオプションを変えると409 IDEMPOTENCY_CONFLICTが返ります。

429または一時的な503レスポンスでは、Retry-Afterがあれば従い、間隔を空けてください。402のクレジット不足は利用枠のリセットまたはプラン変更が必要で、繰り返しリクエストしても解決しません。503 FREE_COMPUTE_BUDGET_EXHAUSTEDは、表示されたリセット時刻まで新しい無料ジョブを停止します。有料ジョブとローカルのブラウザツールは別です。

失敗したジョブは、同じキーを再送しても同じ失敗ジョブのままです。まず原因を確認し、意図的に新しく試す場合は新しいキーを使ってください。タイムアウトのたびに新しいキーを作らないでください。最初のリクエストがすでに受け付けられている可能性があります。