背景の削除 API ドキュメント

説明

このクラウド API は、インテリジェントな顕著物体検出 (SOD) を使用して、自動化された高精度の背景除去を行います。最適な速度を実現するには、ソース画像を 5 MB 未満に保ちます。

🥥 重要な注意事項

データ保持: 出力画像 URL とアルファマット (マスク) は 1 日のみ有効です。すぐにダウンロードして保存してください。
レート制限: デフォルトの制限は 2 QPS です。同時実行性を高めるには、営業またはビジネス開発にお問い合わせください。

バージョン履歴

4.0 | 発売日: 2025-03-20
4.0.1 | 発売日: 2026-07-01 (複数の結果出力のサポートを追加しました)

入力画像の要件

画像フォーマット	解像度	ファイルサイズ
jpg, jpeg, bmp, png, webp, bitmap, avif, tiff, heic, heif	Integer between [4096~4096]	最大 10MB (両端を含む)

🥥 重要な注意事項

出力 URL は 24 時間後に期限切れになります。
デフォルトのレート制限は 2 QPS です。同時実行制限をアップグレードするには、お問い合わせください。

リクエスト

🥥 https://coco-openapi.yezisheji.com/api/v1/segment/submit
https://coco-openapi.yezisheji.com/api/v1/segment/task_info

リクエスト方法と例

# タスクの作成

Plain Text|

curl -k 'https://coco-openapi.yezisheji.com/api/v1/segment/submit' \
-H 'X-API-KEY: YOUR_API_KEY' \
-F 'sync=1' \
-F 'image_file=@/path/of/image.jpg'

# フェッチタスク

Plain Text|

curl -k 'https://coco-openapi.yezisheji.com/api/v1/segment/task_info' \
-H 'X-API-KEY: YOUR_API_KEY' \
-F 'task_id={YOUR_TASK_ID}'

認証と権限

これらのサービスを使用する前に、API Key をリクエストしてください。詳細については、事業開発または営業にお問い合わせください。
API 認証: HTTP Header 経由でシークレットトークンを渡し、API Key を安全に保存します。

リクエストの構築

1、画像の背景の削除

POST /api/v1/segment/submit

リクエストパラメータ:

パラメータ名	種類	デフォルト値	オプションの値	説明
image_url	String	None	-	背景を削除する画像の URL (image_file と相互に排他的)。
image_file	String($binary)	None	-	ローカル画像ファイル (image_url と相互に排他的)。
rsz_w	int	None	Integer between [0~4096]	0 より大きい場合、返されたイメージを rsz_w に比例してスケールします。
rsz_h	int	None	Integer between [0~4096]	0 より大きい場合、返されたイメージを rsz_h に比例してスケールします。
crop_object	int	None	0、1	1 に設定すると、主要な主題領域がトリミングされます。
multi_result	int	None	0、1	複数のマット結果を返すかどうか。請求は返された結果の数に基づいて行われ、通常は 5 つを超えません。
sync	int	0	0、1	0 は、後の task_info ポーリングのためにすぐに task_id を返します。 1 は完了を待ち、結果を返します。
output_type	int	1	1、2、3	画像とマスクの結果を返します。 1 画像のみ。 2 画像とマスク。 3 マスクのみ。
output_format	String	png	jpeg、png	返された画像形式。 png: 背景が透明です。 jpeg: デフォルトでは白い背景。別の色には bg_color を使用してください。
bg_color	String	None	Hexadecimal color string starting with "#"	単色の背景色。output_format が jpeg の場合にのみ有効です。例：「#FFFFFF」、「#000000」。
output_mask_format	String	jpeg	jpeg、png	返されたマスク画像形式。
timeout	int	10	1-60	API 処理待機タイムアウト (秒単位)。sync=1 の場合にのみ有効です。

注: rsz_w と rsz_h の両方を設定すると、アスペクト比を維持せずにそれらの寸法にスケールされます。 crop_object も元のアスペクト比を保持しません。

# Async モードの応答例 (sync=0)

JSON|

{
    "data": {
        "task_id": "67fcadf7b3b99f4447f9ddce"
    },
    "status": 200,
    "timestamp": 1744512855,
    "trace_id": "ae173819-6fb5-4e88-a587-ff654f2de9bf",
    "message": "ok"
}

# 同期モードの応答例 (sync=1)

JSON|

{
    "data": {
        "created_at": 1744513021,
        "completed_at": 1744513022,
        "image": "{image oss url}",
        "mask": "{mask oss url}"
    },
    "status": 200,
    "timestamp": 1744513022,
    "trace_id": "3a2a0b4a-8b4a-4034-865a-8a5ebcc7e93c",
    "message": "ok"
}

2、画像の背景の削除

POST /api/v1/segment/submit

リクエストパラメータ:

# Async モードの応答例 (sync=0)

JSON|

{
    "data": {
        "task_id": "67fcaec66b4a4af9c824fcd2",
        "created_at": 1744513062,
        "completed_at": 1744513063,
        "status": 2,
        "mask": "{mask oss url}",
        "image": "{image oss url}",
        "result_cnt": 2,
        "results": [
            {
                "task_id": "{task_id_1}",
                "created_at": 1744513062,
                "completed_at": 1744513063,
                "status": 2,
                "mask": "{mask oss url}",
                "image": "{image oss url}"
            },
            {
                "task_id": "{task_id_2}",
                "created_at": 1744513062,
                "completed_at": 1744513063,
                "status": 2,
                "mask": "{mask oss url}",
                "image": "{image oss url}"
            }
        ]
    },
    "status": 200,
    "timestamp": 1744513180,
    "trace_id": "952a636e-3a9d-4e72-b470-681c61fcd763",
    "message": "ok"
}

パラメータ名	種類	説明
result_cnt	Number	multi_result=1 の場合に返される結果の数

パラメータ名	種類	デフォルト値	オプションの値	説明
task_id	String	None	Valid Task ID	task_id は、sync=0 の async モードの場合、背景除去 API によって返されます。

3、使用量割り当て照会

GET /api/v1/segment/quota

リクエストパラメータ: なし

# 応答例

Plain Text|

{
    "data": {
        "used_tasks": 888,
        "remaining_tasks": 88888
    },
    "status": 200,
    "timestamp": 1778555905,
    "trace_id": "b9d83cd6-f220-436f-ac30-52fcd8d5b30a",
    "message": "ok"
}

応答パラメータ

パラメータ名	種類	説明
image	String	背景除去後の画像のURL
mask	String($binary)	マスク画像のURL
results	Array	multi_result=1の場合の結果配列
result_cnt	Number	multi_result=1 の場合に返される結果の数
status	String	data.status タスクのステータス: 2 完了 1 加工 -1 失敗しました -2 タイムアウト
used_tasks	Number	使用されたマットタスクの数
remaining_tasks	Number	残りの利用可能なマッティングタスクの数

ステータスコード

HTTP 応答ステータスコード

HTTPレスポンスステータスコード	説明
200	リクエストは成功しました。
400	クライアントパラメータエラー。欠落値または無効な値を確認します。
401	認証に失敗しました。 X-API-KEY とサービスのアクティブ化を確認します。
404	要求された URL またはリソースが存在しません。
412	アップロードされた画像 URL またはファイルの検証に失敗しました。
413	アップロードされたファイルがサイズ制限を超えています。
429	リクエスト頻度が QPS 制限を超えています。速度を下げるか、ビジネスサポートに連絡してください。
500	サーバー例外。ビジネスサポートまたはテクニカルサポートにお問い合わせください。