APIドキュメント

クイックスタート

最初のリクエストに必要なのはinput.image_base64だけです。input.outputを省略すると、従来のクライアントと互換性のある元サイズの透過結果を返します。

curl --request POST   --url https://removezero.com/api/v1/remove-background   --header "Authorization: Bearer ${REMOVEZERO_API_KEY}"   --header "Content-Type: application/json"   --header "Idempotency-Key: image-2026-08-28-0001"   --data '{"input":{"image_base64":"BASE64_IMAGE_DATA"}}'

Bearer Keyによる認証

アカウントでAPI Keyを作成し、各リクエストのAuthorizationヘッダーで送信します。

Authorization: Bearer rz_live_your_api_key

• Keyはサーバーの環境変数またはシークレット管理ツールに保存します。
• Keyをブラウザコード、モバイルアプリのパッケージ、拡張機能、URL、公開コードリポジトリ、ログに含めないでください。
• 可能であれば、サービスや環境ごとに異なるKeyを使用します。
• Keyが漏えいした可能性がある場合は、直ちに無効化して交換します。

サーバーからのみ呼び出す

推奨経路は、ブラウザまたはクライアント → ご自身のサーバー → RemoveZero APIです。Bearer Keyは有料処理を許可するため、公開クライアントでは安全に保存できません。サーバーサイドの有料リクエストではOriginヘッダーを省略する必要があります。

背景削除リクエストを送信

サーバーから厳密に検証されるJSONリクエストを送信します。必須ヘッダーは、クレジットの確保と画像処理の前に検証されます。

POST https://removezero.com/api/v1/remove-background
Authorization: Bearer rz_live_your_api_key
Content-Type: application/json
Idempotency-Key: order-2026-08-25-0001

{
  "input": {
    "image_base64": "BASE64_IMAGE_DATA"
  }
}

• Content-Typeはapplication/jsonである必要があり、charsetパラメーターを付けられます。
• Content-Encodingは省略するかidentityにしてください。圧縮されたリクエスト本文は受け付けません。
• Originヘッダーを送信しないでください。
• Idempotency-Keyは1～128文字で、英字、数字、ピリオド、アンダースコア、コロン、ハイフンのみ使用できます。
• image_base64は標準Base64の画像バイト列とし、data:image/...プレフィックスを付けないでください。

出力のカスタマイズ

outputオブジェクトは省略できます。1回の背景削除推論後にキャンバスだけを調整するため、リクエスト全体で消費するのは1クレジットのままです。

{
  "input": {
    "image_base64": "BASE64_IMAGE_DATA",
    "output": {
      "format": "webp",
      "background": "#ffffff",
      "width": 1600,
      "height": 1600,
      "padding_ratio": 0.08
    }
  }
}

固定のcontain + centerルール

fitはリクエストフィールドではありません。RemoveZeroは常に被写体の縦横比を維持し、使用可能なキャンバス内に被写体全体を収めます。

• 被写体全体を表示し、中央に配置します。
• 切り抜きや引き伸ばしは行いません。
• 残りのキャンバスは透過または指定色で塗りつぶします。
• cover、スマートクロップ、gravityによる配置、任意座標には対応していません。

後方互換性

既存のクライアントはinput.outputを省略し、input.image_base64だけを送信できます。形式、背景、キャンバス、余白をカスタマイズする場合にのみoutputを追加してください。

成功レスポンス

処理に成功するとHTTP 200が返され、1クレジットを消費します。出力には正確なコンテンツタイプ、キャンバスサイズ、サーバーでデコード可能なBase64データが含まれます。

HTTP/1.1 200 OK
Content-Type: application/json

{
  "ok": true,
  "id": "REQUEST_ID",
  "status": "COMPLETED",
  "output": {
    "ok": true,
    "content_type": "image/webp",
    "width": 1600,
    "height": 1600,
    "output_base64": "BASE64_IMAGE_RESULT"
  },
  "usage": {
    "units": 1,
    "credits_used": 1
  }
}

結果のデコード

1. HTTP 200、ok: true、status: COMPLETEDを確認します。
2. output.content_typeを読み取り、image/pngまたはimage/webpのみ受け入れます。
3. output.output_base64を1回デコードし、コンテンツタイプに従って保存します。
4. サイズを指定した場合は、output.widthとoutput.heightを照合します。

結果はインラインデータとして返され、永続URLは提供されません。長期保存や納品が必要な場合は、デコードしたバイト列をアプリケーション側で保存してください。

import { writeFile } from "node:fs/promises";

const payload = await response.json();

if (!response.ok || payload.ok !== true || payload.status !== "COMPLETED") {
  throw new Error(payload.error?.code ?? "REMOVEZERO_REQUEST_FAILED");
}

const { content_type: type, output_base64: base64 } = payload.output ?? {};
const extension = type === "image/png" ? "png" : type === "image/webp" ? "webp" : null;

if (!extension || typeof base64 !== "string") {
  throw new Error("REMOVEZERO_OUTPUT_INVALID");
}

await writeFile(`removezero-result.${extension}`, Buffer.from(base64, "base64"));

課金とクレジット返還

各リクエストで1枚の画像を処理します。RemoveZeroはリクエストを検証し、1クレジットをアトミックに確保して、背景削除と指定出力の両方が成功した場合にのみ確定します。出力のカスタマイズによって推論回数やクレジット消費が増えることはありません。

クレジット利用フロー

リクエストまたは返還を一時的に確認できない場合、APIはREFUND_PENDING、リクエストID、Retry-After: 30を返します。同じIdempotency-Keyを保持し、新しいKeyで同じ画像を再送信しないでください。

HTTP/1.1 503 Service Unavailable
Retry-After: 30
Content-Type: application/json

{
  "ok": false,
  "error": {
    "code": "REFUND_PENDING"
  },
  "request_id": "REQUEST_ID"
}

冪等性と再試行

Idempotency-Keyは、画像および送信されたすべてのoutputフィールドを含む、シリアライズ済みJSONリクエスト本文全体に紐づきます。元のリクエストバイト列とKeyの両方を保持してください。

• 同じKey + 完全に同じリクエスト本文：安全に再試行でき、クレジットの再確保や重複処理は発生しません。
• 同じKey + 変更されたリクエスト本文：409 IDEMPOTENCY_CONFLICTを返します。
• 終端状態のリクエストに同じKeyを再使用：409 IDEMPOTENCY_REPLAY_UNAVAILABLEを返し、Base64結果は再送しません。
• 新しいKey：新規リクエストとして扱われ、再度1クレジットを確保する場合があります。
• JSONの意味が同じでも、空白、フィールド順、デフォルトフィールドの記述方法が異なると、別のリクエストとみなされる場合があります。

Retry-Afterのルール

429 RATE_LIMITED

60秒待ってから、まったく同じリクエスト本文とKeyで再試行してください。

503 REFUND_PENDING

30秒待ってから、まったく同じリクエスト本文とKeyで再試行してください。

503 UPSTREAM_BUSY

10秒待ってください。実際に新しい試行を開始する場合にのみ新しいKeyを使用します。

ネットワークタイムアウトまたはAPI_UNAVAILABLE

結果を不明として扱い、解決するまで元のリクエスト本文とKeyを保持してください。

例

サーバー上でプレースホルダーを置き換えてください。API Keyを公開ブラウザーコードに含めてはいけません。

curl --request POST \
  --url https://removezero.com/api/v1/remove-background \
  --header 'Authorization: Bearer rz_live_your_api_key' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: order-2026-08-25-0001' \
  --data '{"input":{"image_base64":"BASE64_IMAGE_DATA","output":{"format":"webp","background":"#ffffff","width":1600,"height":1600,"padding_ratio":0.08}}}'

一般的な出力の出発点

以下のレシピは出発点にすぎず、いかなるプラットフォームやカテゴリーについても恒久的な準拠を保証するものではありません。プラットフォーム名はラベルであり、APIの列挙値ではありません。

{"format":"png","background":"transparent","width":1600,"height":1600,"padding_ratio":0.08}

{"format":"png","background":"transparent","width":1600,"height":2000,"padding_ratio":0.08}

{"format":"png","background":"transparent","width":1500,"height":2000,"padding_ratio":0.08}

{"format":"webp","background":"#ffffff","width":1920,"height":1080,"padding_ratio":0.08}

{"format":"webp","background":"#ffffff","width":2000,"height":2000,"padding_ratio":0.075}

{"format":"webp","background":"#ffffff","width":2048,"height":2048,"padding_ratio":0.08}

エラーとトラブルシューティング

エラーレスポンスには、安定したHTTPステータスコードと短いJSONエラーコードが含まれます。

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "ok": false,
  "error": {
    "code": "ERROR_CODE"
  }
}

安全なトラブルシューティング

1. HTTPステータスコード、エラーコード、存在する場合はrequest_id、時刻、Idempotency-Keyを記録します。
2. Bearer Key、完全なimage_base64、画像データを含む完全なレスポンスは記録または送信しないでください。
3. まず、4xxに対応するリクエスト、認証情報、残高、リクエストヘッダーの問題を修正します。
4. Retry-Afterに従い、未解決のリクエストには元のリクエスト本文とKeyを引き続き使用します。
5. 状態が解決しない場合は、機密性のない識別情報のみをサポートに提供してください。

リクエスト制限

各リクエストでは、JPG、PNG、WebP画像1枚の標準Base64を送信します。デコード後の入力は最大5 MiB、JSONリクエスト本文全体は最大7,500,000バイトです。カスタム出力は各辺最大4,096ピクセル、総画素数4,194,304以下です。正確なサイズや形式をインラインレスポンスに収められない場合、リクエストは失敗し、確保されたクレジットが返還されます。APIがサイズや形式を暗黙に変更することはありません。