Photoshop APIの紹介 #AdobeIO #Photoshop

この投稿について

Adobe I/O デベロッパーブログを読んで頂き有り難うございます。今回は、 Photoshop API (ベータ版)に関する記事です。本投稿では、Photoshop APIの概要、導入方法、認証、使用方法など、導入から基本的なAPIの使用例まで紹介します。

コンテンツ

Photoshop APIの概要
導入方法
認証と認証トークン
APIコールの基本的な処理の流れ
最後に

Photoshop APIの概要

Photoshop APIは、Photoshop / Lightroom 画像処理サービスへのアクセスを提供するREST APIです。このAPIをユーザーのアプリケーション、ワークフローに統合すると、Adobe Photoshop / Lightroomの機能をユーザーのスクリプトやプログラムから呼び出すことが出来ます。Photoshop APIは、組織・チーム内のDecision Makers (意思決定者), Creatives (クリエイター), Developers (開発者)に対し、以下の価値を提供する事を目的として設計されました。

コストの削減とリソースの節約 [ Decision Makers ]
Photoshop APIは、業界で最もスマートで拡張性・再現性の高い写真編集のワークフローを実現する画像処理機能を低コストで提供します。意思決定者は、一連の画像処理タスクを自動化する事で、作業時間を短縮し予算の最適化を図れます。
クリエイティブな時間の創出 [ Creatives ]
数十個の画像の切り取りや加工、数十種類の異なるサイズと異なるフォーマットで配置された広告コピーの作成、これまで長時間費やしていたこれらの作業を短時間で処理する事で、クリエイターは、よりクリエイティブなタスクに専念することが出来ます。
Adobe Sensei テクノロジーを活用した拡張性あるソリューションの構築 [ Developers ]
PhotoshopとLightroomの機械学習ツールとサービスは、Adobe Senseiプラットフォームを活用しています。開発者は、Photoshop APIへアクセスする事で、新しい写真編集のアイデア、ワークフローを大規模に実装・展開することが出来ます。

導入方法

このセクションでは、Adobe Photoshop APIの導入方法を説明します。

クライアントIDとクライアントシークレットの取得

Photoshop APIは、HTTPSリクエストを介してサービスへアクセスするRest APIです。そのため、ユーザーのクライアント、または、サービスから、Photoshop APIを呼び出すためには、Adobeから発行された、クライアントIDとクライアントシークレットが必要です。本投稿の執筆時点でPhotoshop API (ベータ版)は、テスタープログラムを実施しています。テスタープログラムへ参加する事で、クライアントIDとクライアントシークレットを取得出来ます。まず、Adobe I/O Photoshop API公式サイトからテスタープログラムへの参加を申請をします。

1. “Sign Up”から参加登録フォームへ移動します

2. 必要な情報を記入の上、Submitします。参加登録は、以上となります。

3. プログラムへの参加が承認されると、参加申請フォームに登録したEメールアドレスへAdobeより _“Welcome to Photoshop API Private Beta!” _という件名で、クライアントIDとクライアントシークレットが記載されているEメールが届きます

※ 承認には、3週間程かかります。ご了承ください。

“Hi —-,
Thank you for joining our Photoshop API prerelease program and requesting access to our documentation. We look forward to gaining feedback from you as we build out this product.
The Photoshop API will allow you to perform a select set of tasks (see current features below) via the service in full Photoshop fidelity that were previously only available on the desktop.
In order to gain access to the API, you will need to use the Client ID (API Key) and Client Secret below. This key/secret is specific to you and should not be shared.

Client ID (API Key): ———————
Client Secret: ———————“

これで、Photoshop APIをプログラムから呼び出す準備は整いました。

認証と認証トークン

このセクションでは、Photoshop APIの認証と認証トークンについて説明します。Photoshop APIは、導入方法で説明したクライアントIDと認証トークンを使用して、呼び出されます。2種類のユーザー / 認証タイプに対応した認証トークンが利用できます。

ユーザーと認証の種類

個人ユーザー: OAuth 2.0 アクセストークン認証
Adobe ETLA ユーザー: JSON Web Token (JWT)を使用したサービストークン認証

下記は、Photoshop APIがサポートしている認証フローの例です。

個人ユーザーのAdobe Creative Cloudアカウントでのログイン認証
Adobe エンタープライズのETLA アカウントでのサービス認証
サーバーでの認証 (Service To Service認証)
Webブラウザーでの認証

OAuth 2.0 アクセストークン認証 (個人ユーザー)

PhotoshopサービスへのAPIを使用するには、HTTPSリクエストヘッダーにアクセストークンの追加が必須となります。アクセストークンは、AdobeのIMSサービスのAPIを使用すると取得できます。本投稿では、Adobe IMSサービスを介してのOAuth 2.0 アクセストークンの生成と使用方法については、詳しく触れませんので、詳細は、OAuth 2.0 Authentication and Authorizationをご覧ください。本投稿では、Photoshop API開発チームが提供しているテストツールを利用してアクセストークンを生成します。

https://ps-prerelease-us-east-1.cloud.adobe.io/ へ任意のブラウザーからアクセスします
招待メールに記載されているクライアントIDとクライアントシークレットを入力し”Sign and Get Token”ボタンを押します
Adobe Creative Cloudのログイン画面が表示された場合、Adobe Creative Cloudのアカウント (Adobe ID) でログインします ※Adobe IDを持っていない場合は、Adobe IDの作成方法を参照してください
ログインが成功すると、アクセストークンが表示されます
※ テストツールで生成したアクセストークンは、24時間有効です。

サービストークン認証 (Adobe ETLA ユーザー)

サービストークン認証を実装する場合、ユーザー、もしくは、ユーザーの所属する組織は、Adobe ETLA アカウントの契約が必要がです。皆さまのシステム管理者、または、担当営業にお問い合わせください。

※エンタープライズユーザーは、Photoshop APIで利用するストレージが、Externalに制限されており、Creative Cloudストレージは扱えません。Photoshop APIが扱えるストレージに関しては、”入力ファイルと出力ファイルのストレージ”で後述します。

Adobe Admin Consoleより開発者ロールが付与されたアカウントをシステム管理者へリクエストしてください
Adobe I/O ConsoleでService Integrationを作成し、Photoshop, Lightroom / Camera raw API, Image Cutoutサービスをサブスクライブしてください。サービスのサブスクライブについては、 Service Token InstructionsのSubscribe to an Adobe Serviceセクションを参照してください
JSON Web Token (JWT)を生成し、Photoshop APIを呼び出すためのアクセストークンを生成してください。詳細は、JWT Instructionsを参照してください

JWTのサンプルコードは、JWT sample codeから入手できます。

アクセストークンの検証

それでは、生成したアクセストークンが有効であるか実際にPhotoshop APIを呼び出して検証してみましょう。APIコールが可能なコンソール、ターミナル、または、Postman等のAPIクライアントから下記の形式でAPIコールを試してください。

curl --request GET \
  --url https://image.adobe.io/pie/psdService/hello \
  --header 'Authorization: Bearer <YOUR_SERVICE_TOKEN>' \
  --header 'x-api-key: <YOUR_CLIENT_ID>'

※ “<YOUR_SERVICE_TOKEN>”と”<YOUR_CLIENT_ID>”のヘッダー値を適宜変更してください。Authorizationヘッダーへ渡す値は、”Bearer” + “<YOUR_SERVICE_TOKEN>”になる事に注意してください。

結果に “Welcome to the Photoshop API!“と表示されれば、APIコールの成功です。

APIコールの基本的な処理の流れ

このセクションでは、基本的なPhotoshop APIコールの処理の流れを紹介します。

基本的な処理の流れ

Photoshop APIは、リソースとそのリソースに対するオペレーション(処理操作)を指定して処理を行います。オペレーションは、オペレーションのエンドポイントへAPIコールすることで開始し非同期で動作します。したがって、APIコールに対するレスポンスには、現在の処理状態を確認するための/statusエンドポイントと<jobId> が含まれます。この/status エンドポイントへAPIコールをして処理状態の確認オペレーションをポーリングし、処理が完了したら次のオペレーションを開始します。

任意のオペレーションのエンドポイントへ入力ファイルや入力オプションを指定してAPIコールをする
APIコールから返却された<jobId>を含む /status エンドポイントへ処理状態の確認オペレーションをポーリングする
/statusエンドポイントから返却された処理状態の値が”succeeded”なら次のオペレーションを開始する

これが基本的な処理の流れとなります。

入力ファイルと出力ファイルのストレージ

Photoshop APIは、ファイルの入出力パスとして下記のストレージを扱えます。

Adobe: Creative Cloud FilesのファイルPath
External: AWS S3等のファイルオブジェクトのpresigned Get / PUT URL
Azure: アップロード、ダウンロードのためのSAS (Shared Access Signature) URI
Dropbox: https://dropbox.github.io/dropbox-api-v2-explorer/を使用したテンポラリーのアップロード・ダウンロードリンク

APIコール例

それでは、実際にPhotoshop APIを上記で説明した基本ワークフローに沿って呼び出してみましょう。ここでは、Photoshop API機能の一つであるAuto Tone機能(自動補正機能)を使用します。Adobeの人工知能・機械学習プラットフォームであるAdobe Senseiの先進的なニューラルネットワークを駆使し、新しいAuto Tone機能は、数万のプロフェッショナルに画像編集された高品質な写真を学習させることによって強化されました。

1. /autoToneエンドポイントへAPIコールしてAuto Tone オペレーションを開始する

Auto Toneオペレーションのリクエスト

POST /autoTone HTTP/1.1
Host: image.adobe.io/lrService
Content-Type: application/json
authorization: Bearer <YOUR_SERVICE_TOKEN>
x-api-key: <YOUR_CLIENT_ID>
{
     "inputs":{
          "href": "files/some_project/photo.jpg",
          "storage": "adobe" 
},
     "outputs": [
          {
               "href":"files/some_project/OUTPUT/photo.jpg",
               "storage": "adobe",
               "type": "image/jpeg",
               "overwrite":true
          }
     ]
}

2. Auto ToneオペレーションのAPIコールが成功すると、処理が非同期で動作するので、レスポンスに現在の処理状態と以後の処理状態を確認するためのjobIdを含んだ/statusエンドポイントが返却される

Auto Toneオペレーションのレスポンス

HTTP/1.1 202
Content-Type: application/json
{
     "jobId":"f54e0fcb-260b-47c3-b520-de0d17dc2b67",
     "created":"2018-01-04T12:57:15.12345:Z",
     "modified":"2018-01-04T12:58:36.12345:Z",
     "outputs":[
          {
               "input":"files/some_project/photo.jpg",
               "status":"pending"
          }
     ]
     "_links":{
          "self":{
               "href":"https://image.adobe.io/lrService/status/f54e0fcb-260b-47c3-b520-de0d17dc2b67"
          }
     }
}

3. 現在の処理状態を確認するために、/autoToneへのAPIコールで返却されたjobIdを含んだ/statusエンドポイントへAPIコールをしてStatusオペレーションを開始する

Status Checkオペレーションのリクエスト

GET /status/f54e0fcb-260b-47c3-b520-de0d17dc2b67 HTTP/1.1
Host: image.adobe.io/lrService
Content-Type: application/json
authorization: Bearer <YOUR_SERVICE_TOKEN>
x-api-key: <YOUR_CLIENT_ID>

4. StatusのAPIコールから返却された”status”の値を確認する。”status”の値が”pending” または、”running”の場合は、処理が終了していないので、再び同じ/statusエンドポイントへAPIコールをしてStatusオペレーションを再開する

Status Checkオペレーションのレスポンス

HTTP/1.1 202
Content-Type: application/json
{
     "jobId":"f54e0fcb-260b-47c3-b520-de0d17dc2b67",
     "created":"2018-01-04T12:57:15.12345:Z",
     "modified":"2018-01-04T12:58:36.12345:Z",
     "outputs":[
          {
               "input":"files/some_project/photo.jpg",
               "status":"pending"
          }
     ]
     "_links":{
          "self":{
               "href":"https://image.adobe.io/lrService/status/f54e0fcb-260b-47c3-b520-de0d17dc2b67"
          }
     }
}

5. StatusのAPIコールから返却された”status”の値が”succeeded”なら、処理が問題なく終了しているので自動補正処理後に出力されたファイルの取得、または、別のオペレーションを開始する

Status Checkオペレーションのレスポンス

HTTP/1.1 202
Content-Type: application/json
{
     "jobId":"f54e0fcb-260b-47c3-b520-de0d17dc2b67",
     "created":"2018-01-04T12:57:15.12345:Z",
     "modified":"2018-01-04T12:58:36.12345:Z",
     "outputs":[
          {
               "input":"files/some_project/photo.jpg",
               "status":"succeeded",
               "_links":{
                    "self":
                         {
                              "href":"files/some_project/OUTPUT/photo.jpg",
                              "storage":"adobe"
                    }
               }
          }
     ],
     "_links":{
          "self":{
               "href":"https://image.adobe.io/lrService/status/f54e0fcb-260b-47c3-b520-de0d17dc2b67"
          }
     }
}

Auto Tone機能の適応前と適応後の比較サンプルです。

適応前

適応後

最後に

Photoshop APIの概要、導入方法、認証、使用方法について紹介をしてきましたが、いかがだったでしょうか。今回は割愛させて頂きましたが、Photoshop APIには、Auto Tone機能以外にも、Adobe Senseiプラットフォームを活用した拡張性あるソリューションを構築出来る様々な機能が用意されています。皆さまのワークフロー・ユースケースに応じて利用してください。他の機能に関しては、関連リンクのAPI Docsを参照してください。Photoshopサービスとの連携を検討されている方、初めてPhotoshop APIを導入される方に本投稿が少しでもお役に立てれば幸いです。