Imagen API でポストプロダクションのワークフローを自動化する

  • 更新

Imagen の概要

Imagen は AI を活用したソリューションであり、プロの写真家は何時間もかかる煩雑な作業をポストプロダクションから省くことができます。 

使い方 

写真家は AI プロファイルを作成するか、タレントまたは Imagen AI プロファイルを選択します。次に、写真を Imagen にアップロードします。 Imagen は、手作業による処理にかかる時間より短いわずかな時間で、AI プロファイルを使用して写真を編集します。最後に、写真をエクスポートして顧客に配信します。

Imagen API は、Imagen アプリと同様に、写真家のポストプロダクション編集ワークフローを合理化し、自動化します。このドキュメントでは、呼び出す必要のあるフローとエンドポイントについて説明します。Imagen アプリの機能で、まだ API に無いものもあります。このドキュメントでは、Imagen API でサポートされているエンドポイントについて説明します。

 

1. ご利用いただく前に

開始する前に、ご利用の環境を設定してください。Imagen にサインアップして、API キーを取得する必要があります。Postman コレクションと Python コードサンプルを含めて、API の使用方法を例示します。このセクションの情報を確認して、ご利用の環境の準備ができていること、および API の操作の基本を理解していることを確認してください。

サインアップ

Imagen API を使用する前に、Imagen にサインアップする必要があります。次に、Imagen カスタマーサクセスチームにメールを送信して、API キーを要求します。メールには、Imagen への登録に使用したメールアドレスを記載してください。

Imagen のベース URL

Imagen API のベース URL は https://api-beta.imagen-ai.com/v1/ です。

リファレンス API ドキュメント

Imagen API のリファレンス API ドキュメントはこちらです。

Postmanコレクション

Imagen API の使用に役立つPostman コレクションをご利用ください。

  1. Postman コレクションをコンピューターにダウンロードします。
  2. Postman を開きます。
  3. [ファイル] > [インポート] に移動して、Postman でコレクションを開きます。

Python コードサンプル

Python コードサンプルでは、Imagen API エンドポイントを呼び出して写真を編集する方法を示します。また、スレッディングのデモも行います。スレッディングを使用すると、各バッチが完了するのを待つ代わりに、複数のバッチの写真を同時に処理できます。

認証

Imagen API は、認証に API キーを使用します。テキスト形式でリクエストにヘッダーとして追加します。ヘッダー名は x-api-key です。 

たとえば、次のようになります。

curl --location ‘https://api-beta.imagen-ai.com/v1/profiles/’ \

--header ‘x-api-key: ’ \

--header ‘Content-Type: application/json’

写真編集用にサポートされているファイル形式

Imagen API は、写真編集用に次のファイル形式をサポートしています。

  • RAW：NEF、CR2、CR3、ARW、NRW、CRW、SRF、SR2、ORF、RW2、RAF、PTX、PEF、RWL、SRW、3FR、FFF
  • DNG
  • JPEG 

2. AI プロファイルを選択

AI プロファイルは写真家の編集スタイルを予測し、それに応じて写真を編集します。Imagen は多くの AI プロファイルを無料で提供しています。または、写真から AI プロファイルを作成することもできます。 

編集する写真と互換性のある AI プロファイルを選択します。写真のファイル形式と編集スタイルが一致していることを確認してください。次に、/profiles/ エンドポイントを呼び出して、使用可能なすべてのプロファイルのリストを取得します。応答には、使用するプロファイルのプロファイルキーが表示されます。

  1. オンラインで写真を編集して、お好きな AI プロファイルを選択します。最大 10 枚の RAW 写真をアップロードして、すぐに結果を得ることができます。満足のいくプロファイルが見つからない場合は、Imagen アプリを使用して個人用 AI プロファイルを作成します。
  2. AI プロファイルとそのキーのリストを取得します。GET https://api-beta.imagen-ai.com/v1/profiles/ をコールし、写真の編集に使用できる AI プロファイルのリストを取得します。 

応答には、Imagen アプリで作成した個人 AI プロファイルと、利用可能なすべてのタレントおよび Imagen AI プロファイルが含まれます。各 AI プロファイルには、それを識別する profile_key があります。プロジェクト内の写真を編集するには、この profile_key が必要です。

利用可能な AI プロファイルを使用した応答例

{

    "data": {

        "profiles": [

            {

                "profile_key": <個人 AI プロファイルのプロファイルキー>,

                "profile_name": "wedding",

                "profile_type": "Personal",

                "image_type": "RAW"

            },

            {

                "profile_key": 14715,

                "profile_name": "LOVE & LIGHT",

                "profile_type": "Talent",

                "image_type": "RAW"

            },

            {

                "profile_key": 163322,

                "profile_name": "ELEGANT HOME",

                "profile_type": "Talent",

                "image_type": "RAW"

            }

        ]

    }

}



3. APIを使用せずに写真をカリングする

写真をカリングしてからアップロードして編集してください。カリングは Imagen API の一部ではありません。

 

4. 編集を改善する AI ツールを選択する

AI ツールでは、プロジェクトでの写真の編集を改善する追加の AI による写真処理を提供します。自分のニーズに合わせて AI ツールを組み合わせることができます。相互に排他的な AI ツールもあり、その場合はどちらかを選択する必要があります。その他は、不動産やスポーツなどの特定の写真タイプに対応しています。 

このセクションでは、AI ツールの選択方法について説明します。後工程で、編集リクエストに AI ツールを追加します。

Imagen AI ツール

crop_aspect_ratio と sky_replacement_template_id を除いて、 AIツールの値はブール型であり、真または偽です。

AIツールパラメーター 説明
切り抜き 2x3 のアスペクト比に切り抜いて、さまざまな種類の写真に最適な構成を実現します。 headshot_cropまたはportrait_cropと一緒に使用することはできません。
crop_aspect_ratio

デフォルトのアスペクト比から、crop、headshot_crop、portrait_cropのアスペクト比を変更 します。

例： “crop_aspect_ratio”： “2X3”
headshot_crop

すべての顔写真を一貫して整列し、サイズを揃えることで、イヤーブックやプロフェッショナルな顔写真に最適です。 被写体を中央に配置し、写真全体で同じように水平に目を合わせます。 cropまたは portrait_crop と一緒に使用することはできません。

crop_aspect_ratioを使用 して、縦横比を2x3または5x7に変更します。
hdr_merge 屋外と屋内の両方の露出が正しくなるように、異なる露出の複数の写真を 1 枚の写真にまとめます。主に不動産写真に使用されます。要件については、HDR マージを参照してください。
perspective_correction 広角レンズや不完全な撮影角度によって引き起こされる不動産写真の歪みを修正し、垂直線と水平線がまっすぐになるようにします。角度補正との併用はできません。
portrait_crop

各写真のメインの被写体を中央に配置し、4x5 のアスペクト比で切り抜きます。ヘッドやその他の重要なディテールの上に最適な間隔を保ちます。学校やスポーツだけでなく、ポートレートやスタジオでの撮影にもおすすめです。cropまたはheadshot_cropと一緒に使用することはできません。

crop_aspect_ratioを使用して、縦横比を5x7に変更します。
straighten 各写真を地平線に合わせて回転します。perspective_correction と一緒に使用することはできません。
subject_mask 写真内の主な被写体を Lightroom と同じ方法で選択し、ブラシを使用してマスクを適用し、そのマスクにローカル AI 編集を適用します。
smooth_skin 小じわやシミなど肌の欠点を目立たなくして、よりなめらかな見た目の魅力的な肌を実現します。
sky_replacement

写真の空をいろいろなものから選択します。sky_replacement_template_id と一緒に使用して空を選択します。

空の変更はXMPメタデータに保存されます。写真を確認するときに、Adobe 編集ソフトウェアで空を調整できます。詳細については、「Adobe ソフトウェアで編集した写真をダウンロードしてレビューする」を参照してください。
sky_replacement_template_id

空の識別子。新しい空の選択肢を表示するには、アプリを開いてプロジェクトを作成し、[空の置換 AI] ツールを選択する必要があります。

以下は、その内容です。

1：ライトブルー - 低い雲

2：明るいブルー - 低い雲

3：ライトブルー - 曇り

例：“sky_replacement_template_id”: ”1”
window_pull 屋内と屋外の照明のバランスをとるために露出を最適化します。HDR ブラケット撮影や HDR 合成後の写真に対応し、手動でウィンドウをマスキングする手間を省くことができます。不動産の撮影におすすめです。

 

相互に排他的な AI ツール

相互に排他的な類似の AI ツールもあります。 次のいずれかを選択します。

  • 切り取り、 headshot_crop、 またはportrait_crop
  • perspective_correction または角度補正

さまざまな写真撮影タイプ向けの AI ツール

不動産

不動産の写真にはhdr_merge、perspective_correction、sky_replacement、window_pullを使います。角度補正 AI ツールは使わないでください。

学校やスポーツ

学校やスポーツの写真には、portrait_crop または headshot_crop を使います。

すべてのタイプに使える一般的なツール

これらの AI ツールはほとんどの写真タイプに適しています。

  • 切り抜き
  • 角度補正
  • subject_mask
  • smooth_skin

 

5. 写真を編集

1. プロジェクトを作成

プロジェクトを作成するには、POST https://api-beta.imagen-ai.com/v1/projects/ をコールします。

撮影ごとにプロジェクトを作成することをお勧めします。プロジェクトは、これらの写真を編集するために選択した AI プロファイルで写真を整理します。応答は、このプロジェクトを識別するために使用される project_uuid です。写真を JPEG にエクスポートするまで、この project_uuid を使用します。

応答例

{

    "data": {

        "project_uuid": ""

    }

}

 

2. 写真をアップロードするための一時的なアップロードリンクを取得する

POST https://api-beta.imagen-ai.com/v1/projects//get_temporary_upload_links をコールします。

リクエストの files_list パラメーターに、アップロードする写真のファイル名を含めます。リスト形式を使用します。

応答には、AWS 上の Imagen の S3 バケットへの各写真の一時的なリンクが含まれています。このリンクは AWS の署名付き URL です。

リクエストの例

curl --location ‘https://api.dev.imagen-ai.com/v1/projects//get_temporary_upload_links’ \

--header ‘x-api-key: ’ \

--header ‘Content-Type: application/json’ \

--data ‘{

    “files_list”: [

        {“file_name”: “922A4846.CR2”},

        {“file_name”: “922A4832.CR2”},

        {“file_name”: “922A4818.CR2”},

        {“file_name”: “922A4809.CR2”}

    ]

}’

 

応答例

{

    "data": {

        "files_list": [

            {

                "file_name": "922A4846.raw",

                "upload_link": ""

            },

            {

                "file_name": "922A4832.raw",

                "upload_link": ""

            },

            {

                "file_name": "922A4818.raw",

                "upload_link": ""

            },

            {

                "file_name": "922A4809.raw",

                "upload_link": ""

            }

        ]

    }

}



3. 各写真を一時アップロードリンクにアップロードする

前のステップの応答からの一時的なアップロードリンクを使用して、AWS 上の Imagen の S3 バケットに写真をアップロードします。PUT リクエストのみを使用します。

署名付き URL を使用したファイルのアップロードの詳細については、AWS ドキュメントのこのガイドを参照してください。

Postman でのテスト

ヘッダーで Content-Type を無効にします。

コードでの要求ヘッダーの要件

  • 一時的なアップロードリンクのリクエストの files_list パラメーターに md5 を含める場合は、写真をアップロードするためのリクエストヘッダーに必ず MD5 を含めてください。Python のサンプルコードについては、Github のImagen API プロジェクトの api_client.py を参照してください。

  • 空の文字列（""）を値としてヘッダーに Content-Type を追加します。

4. 編集を開始する

POST https://api-beta.imagen-ai.com/v1/projects//edit をコールして、選択した AI プロファイルで編集を開始します。 

リクエスト本文には以下を含めます。

リクエスト本文の例

{

  "profile_key": ,

  "hdr_merge": true,

  "photography_type": "REAL_ESTATE",

  "callback_url": "string",

  "perspective_correction": true,

  "sky_replacement": true,

  "sky_replacement_template_id": “2”

}

この応答はプロジェクトが正常に編集されたことを示すメッセージです。エラーが発生した場合は、カスタマーサクセスチームにメールしてください。

プロファイルキー

profile_key は、プロジェクトを編集するために使用する AI プロファイルの識別子です。整数形式を使用します。AI プロファイルを選択の応答を確認し、 profile_key を取得してください。

AI ツール

AI ツールは、プロジェクトでの写真の編集時に追加できる AI による写真処理ツールです。 

写真の種類

photography_type は、プロジェクトでの写真撮影の種類を示します。このパラメーターはオプションです。 

photography_type の値は次のとおりです。

  • WEDDING
  • REAL_ESTATE
  • SCHOOL
  • SPORTS
  • EVENTS
  • PORTRAITS
  • NO_TYPE
  • OTHER
  • LANDSCAPE_NATURE
  • FAMILY_NEWBORN
  • BOUDOIR

コールバック URL

callback_url は、Imagen がステータスメッセージを API に送信するために使用できる POST エンドポイントです。このパラメーターはオプションです。 使用する場合、編集ステータスを確認する必要はありません。このエンドポイントは Imagen に開放されている必要があります。 

リクエストで送信される可能性のあるステータスは次のとおりです。

応答例

{“project_uuid”: “”, “status”: “Failed/Completed”, “action”: “edit/export”“}



5. 編集ステータスを確認する

GET https://api-beta.imagen-ai.com/v1/projects//edit/status をコールし、編集処理の最新のステータスを取得します。ステータスがCompleted（完了）になるまで、このエンドポイントを長いポーリングで呼び出し続けます。

このステータスチェックをバイパスする場合は、callback_url を /projects//edit/ リクエストに含めます。詳細については、コールバック URL を参照してください。

応答のステータスは次のとおりです。

 

6. 一時的なダウンロードリンクを取得して、編集した写真をダウンロードする

完了ステータスを受け取ったら、GET https://api-beta.imagen-ai.com/v1/projects//edit/get_temporary_download_link をコールします。 

リクエストの files_list パラメーターに、ダウンロードする写真を含めます。リスト形式を使用します。

応答には、AWS 上の Imagen の S3 バケットへの各写真の一時的なリンクが含まれています。このリンクは AWS の署名付き URL です。

応答例

{

    "data": {

        "files_list": [

            {

                "file_name": "922A4846.DNG",

                "upload_link": ""

            },

            {

                "file_name": "922A4832.DNG",

                "upload_link": ""

            },

            {

                "file_name": "922A4818.DNG",

                "upload_link": ""

            },

            {

                "file_name": "922A4809.DNG",

                "upload_link": ""

            }

        ]

    }

}

 

7. 写真をローカルにダウンロードする

編集されたファイルが Imagen から返される場合、それぞれの形式は次のとおりです。

編集前のファイル形式 編集後に返されるファイル形式
RAW XMP
注：HDR マージで写真を編集する場合、編集前のファイル形式が RAW であっても、返される形式は常に DNG です。
DNG 埋め込み XMP を使用した DNG
JPEG 埋め込み XMP を使用した JPEG


前のステップの応答からの一時的なダウンロードリンクを使用して、AWS 上の Imagen の S3 バケットから写真をダウンロードします。お好きな方法を使用してください。Python のサンプルコードについては、Github のImagen API プロジェクトの api_client.py を参照してください。

AWS からのファイルのダウンロードの詳細については、AWS ドキュメントのこのガイドを参照してください。

Adobe 編集ソフトウェアで編集内容を確認します。ご利用の PC で初期設定の画像ビューアを使用して写真を開いた場合、編集内容は表示されません。サポートが必要な場合は、次を参照してください。

6. 写真を配信用にエクスポートする

Imagen API はプロジェクトのすべての写真を JPEG 形式にエクスポートします。このステップはオプションです。これは、編集ソフトウェアを使用して編集内容を微調整し、エクスポートする写真家向けです。写真をエクスポートした後、写真を配信するか、ギャラリーにアップロードします。

1. プロジェクトで写真をエクスポートする

POST https://api-beta.imagen-ai.com/v1/projects//export をコールします。応答には project_uuid と、エクスポートが成功したことを示すメッセージが含まれます。エラーが発生した場合は、カスタマーサクセスチームにメールでご連絡ください。

2. エクスポートステータスを確認する

GET https://api-beta.imagen-ai.com/v1/projects//export/status をコールします。応答にはエクスポートのステータスが含まれます。可能性のあるステータスは次のとおりです。

  • IN PROGRESS（進行中）：Imagen API が写真を編集中です。
  • FAILED（失敗）：カスタマーサクセスチームにメールします。
  • COMPLETED（完了）： Imagen API が JPEG への写真のエクスポートを完了しました。 

3. エクスポートした JPEG 写真をダウンロードする

エクスポートされた JPEG 写真をダウンロードするための一時的なダウンロードリンクを取得する

エクスポートステータスが COMPLETED（完了）と返ってきた後に、GET https://api-beta.imagen-ai.com/v1/projects//export/get_temporary_download_links をコールします。 

リクエストでは、ダウンロードするエクスポートされた写真を files_list パラメーターに含めます。リスト形式を使用します。

応答には、AWS 上の Imagen の S3 バケットへの各写真の一時的なリンクが含まれています。このリンクは AWS の署名付き URL です。

応答例

{

    "data": {

        "files_list": [

            {

                "file_name": "922A4846.JPG",

                "upload_link": ""

            },

            {

                "file_name": "922A4832.JPG",

                "upload_link": ""

            },

            {

                "file_name": "922A4818.JPG",

                "upload_link": ""

            },

            {

                "file_name": "922A4809.JPG",

                "upload_link": ""

            }

        ]

    }

}

 

エクスポートした JPEG 写真をローカルにダウンロードする

前のステップの応答からの一時的なダウンロードリンクを使用して、AWS 上の Imagen の S3 バケットから写真をダウンロードします。お好きな方法を使用してください。Python のサンプルコードについては、Github の Imagen API プロジェクトの api_client.py を参照してください。

AWS からのファイルのダウンロードの詳細については、AWS ドキュメントのこのガイドを参照してください。

この記事は役に立ちましたか？

他にご質問がございましたら、リクエストを送信してください