背景ぼかし

概要

背景ぼかし API では、写真の背景をぼかします。

背景ぼかし API で、被写体を自動的に切り出し、背景をぼかします。

主な利用シーン:

ポートレート強化ボケ効果を適用して被写体を際立たせます。
Before:
After:
プロフェッショナルな証明写真標準的な写真からスタジオ風の背景ぼかし効果を作成します。
Before:
After:

統合ガイド

入力要件と処理基準:

明確で目立つ前景の被写体を含む画像をアップロードします。
画像の長辺は 4,096 px を超えてはいけません。
ソースファイルサイズは 10 MB 未満である必要があります。
少なくとも 1 つの明確に視認できる前景の被写体が必要です。
単一被写体の分析のみサポートされています。複数の人物が存在する場合、API は可視面積が最大の被写体を自動的に選択します。

ワークフロー:

File API を呼び出します。
レスポンスから署名付きアップロード URL を取得します。
返された URL に実際の画像をアップロードします。
AI タスクを作成します。
Webhook を設定するか、完了するまでタスクステータスをポーリングします。
処理が成功したら、生成された結果画像をダウンロードします。

ステップ 1 — File API を使用してファイルメタデータをアップロードする

POST /s2s/v2.0/file を使用してファイルレコードを作成し、ソース画像のアップロード詳細を取得します。

curl --request POST \
  --url https://yce-api-01.makeupar.com/s2s/v2.0/file \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --data '{
    "files": [
      {
        "content_type": "image/jpg",
        "file_name": "full_body_photo_01_3dbd1b6683.jpg",
        "file_size": 547541
      }
    ]
  }'

File API レスポンス例:

{
  "status": 200,
  "data": {
    "files": [
      {
        "content_type": "image/jpg",
        "file_name": "full_body_photo_01_3dbd1b6683.jpg",
        "file_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud",
        "requests": [
          {
            "method": "PUT",
            "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...",
            "headers": {
              "Content-Length": "547541",
              "Content-Type": "image/jpg"
            }
          }
        ]
      }
    ]
  }
}

ステップ 2 — File API レスポンスの詳細を取得する

レスポンスには以下が含まれます:

フィールド	説明
`file_id`	AI タスクの作成に使用される識別子。
`requests.url`	実際の画像ファイルをアップロードするための署名付き URL。
`requests.method`	アップロードメソッド。通常は `PUT`。
`requests.headers`	アップロードリクエストに必要なヘッダー。

ステップ 3 — 提供された URL に画像をアップロードする

File API レスポンスの requests.url を使用して、ソース画像をアップロードします。

curl --location --request PUT 'https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...' \
  --header 'Content-Type: image/jpg' \
  --header 'Content-Length: 547541' \
  --data-binary @'./full_body_photo_01_3dbd1b6683.jpg'

ステップ 4 — AI タスクを作成する

POST /s2s/v2.0/task/bg-blur を使用して AI タスクを作成します。

パラメータ	説明	例
`src_file_id`	File API アップロードフローから返されるファイル ID。アップロードファイルワークフローを使用する場合に必須。	`"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud"`
`src_file_url`	ソース画像の直接 URL。`src_file_id` の代替として使用します。	`"https://example.com/selfie.jpg"`
`intensity`	ぼかしの強度。0 はぼかしなし、100 は最大ぼかしを意味します。	50

リクエスト例:

const resp = await fetch(
  'https://yce-api-01.makeupar.com/s2s/v2.0/task/bg-blur',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: 'Bearer <YOUR_TOKEN_HERE>'
    },
    body: JSON.stringify({
      src_file_url: 'https://example.com/selfie.jpg',
      intensity: 50
    })
  }
);

const data = await resp.json();
console.log(data);

AI タスク API レスポンス:

{
  "status": 200,
  "data": {
    "task_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT"
  }
}

ステップ 5 — Webhook の設定またはタスク結果のポーリング

設定および検証の詳細については、Webhook 統合ガイドを参照してください。

ポーリングの場合は、返された task_id を使用してタスクステータスを確認します。

curl --request GET \
  --url https://yce-api-01.makeupar.com/s2s/v2.0/task/bg-blur/<YOUR_TASK_ID> \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json'

ステップ 6 — 結果画像を取得する

処理が成功すると、レスポンスの data.results.url にダウンロード URL が含まれます。

{
  "status": 200,
  "data": {
    "error": null,
    "results": {
      "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature..."
    },
    "task_status": "success"
  }
}

無効な API キーのレスポンス:

アクセストークンが無効な場合、API は 401 レスポンスを返します。

{
  "status": 401,
  "error": "Unauthorized",
  "error_code": "InvalidAccessToken"
}

ファイル仕様とエラー

ファイル仕様:

仕様	要件
画像タイプ	画像には、1 つの明確で目立つ前景の被写体または人物が含まれている必要があります。
長辺の最大解像度	長辺は 4096 px を超えてはいけません。
ファイルサイズ制限	10 MB 未満である必要があります。
サポート形式	`jpg`, `png`。

エラーコード:

エラーコード	説明
`exceed_max_filesize`	ソース画像が許容される最大寸法またはファイルサイズを超えています。長辺は 4096 px を超えてはならず、ファイルサイズは 10 MB 未満である必要があります。
`error_nsfw_content_detected`	ソース画像または生成された結果画像に潜在的な NSFW コンテンツが検出されました。
`invalid_parameter`	ソースキー、宛先キー、アクション、モード値、強度レベル、またはタスク設定に対して無効なパラメータが提供されました。
`error_download_image`	ソース画像を正常にダウンロードできませんでした。
`error_decode_image`	ソース画像を正常にデコードできませんでした。

環境と依存関係:

ツール / 言語	推奨ランタイムバージョン
cURL	Bash ≥ 3.2; curl ≥ 7.58 (モダンな TLS/HTTP サポート付き); jq ≥ 1.6 (堅牢な JSON 解析用)。
Node.js	グローバル `fetch` サポートのため Node ≥ 18。
JavaScript ブラウザサポート	Chrome / Edge ≥ 80, Firefox ≥ 74, Safari ≥ 13.1。
PHP	モダンな TLS 互換性のため PHP ≥ 7.4; ext-curl を推奨、または OpenSSL および JSON サポート付きで `allow_url_fopen=On`。
Python	f-strings のため Python ≥ 3.10; requests ≥ 2.20.0。
Java	HttpClient のため Java 11+; Jackson Databind ≥ 2.12.0。

ユニット消費量

AI 機能	消費ユニット
背景ぼかし V2.0	1

OpenAPI記述をダウンロード

ai_photo_background_blur.json

ai_photo_background_blur.yaml

概要

メール

YouCamOnlineEditor_API@perfectcorp.com

ライセンス

利用規約

言語

サーバー

https://yce-api-01.makeupar.com