imgix APIs
マネージメント API
アセット

アセット

注: アセットマネージャーの一部の機能（したがって、一部のアセットマネージャーAPI操作）はプレミアム専用であり、すべてのアカウントで有効になっているとは限りません。サポートに連絡 (opens in a new tab) するか、アカウントマネージャーに連絡して詳細を確認してください。

アセットマネージャーアセット操作は通常、source_id で指定される特定のソースに関連付けられます。

アセット操作

Postman で開く (opens in a new tab)

GET アセット操作には Asset Manager Browse 権限が必要です。その他のアセット操作にはすべて Asset Manager Edit 権限が必要です。

エンドポイントメソッド説明
sources/:source_id/assetsGETソースからアセットのリストを取得します。
sources/:source_id/assets/:origin_pathGETソース source_id の単一のアセットの詳細を取得します。 asset_id で指定します。
sources/:source_id/assets/:origin_pathPATCH単一のアセットを更新します。
sources/:source_id/upload/:origin_pathPOSTorigin_path のソース source_id に単一のアセットをアップロードします。 詳細についてはUploadingを参照してください。
sources/:source_id/assets/add/:origin_pathPOSTオリジンからアセットマネージャーに単一のアセットを追加します。 詳細についてはAdding an Assetを参照してください。
sources/:source_id/assets/refresh/:origin_pathPOST単一のアセットをリフレッシュし、再処理し、パージします。詳細についてはRefreshing an Assetを参照してください。

アセットフィルター

フィルタータイプノート
categoriesString
colorsString16進数コード（# なし、例：8ca091）。
custom:<key>Stringこのフィルターに値を渡さない場合、このキーを任意の値に設定した結果が返されます。値を渡すと、その特定の値に設定されたキーを持つ結果が返されます。
face_countInteger単一の整数は、その数の顔がある結果を返します。範囲でフィルタリングするには、: を使用します（例： 1:3 は 1、2、または 3 の顔がある結果を返します。）
has_framesBoolean
keywordStringorigin_path、name、description などの複数の事前定義フィールド全体で検索します。正確な動作は変更される可能性があります。
media_kindStringアセットのタイプ。可能な値：IMAGE、ANIMATION、DOCUMENT、VECTOR。
origin_pathString
tagsString
warning_adultInteger1 から 5 までの数値で、コンテンツ警告レベルを説明します。 1 は最も低い確率で、 5 は最も高い確率です。 範囲でフィルタリングするには、: を使用します（例： 1:3 は 1、2、または 3 の値を返します。）。
warning_medicalIntegerwarning_adult と同じ動作です。
warning_racyIntegerwarning_adult と同じ動作です。
warning_spoofIntegerwarning_adult と同じ動作です。
warning_violenceIntegerwarning_adult と同じ動作です。

アセットソート

  • date_created
  • date_modified
  • file_size

アセット属性

フィールドタイプ更新可能？説明
analyzed_content_warningsBooleanいいえアセットのコンテンツ警告が解析されているかどうか。
analyzed_facesBooleanいいえ顔の存在が解析されているかどうか。
analyzed_tagsBooleanいいえタグを生成するためにアセットが解析されているかどうか。
categoriesListはいアセットを説明または整理するためのユーザーが追加したカテゴリのリスト（例： "Editorial Images" または "Summer Campaign" または "Profile Pictures"）。
color_modelStringいいえ検出されたカラーモデル（たとえば、 "RGB" または "CMYK"）。
color_profileStringいいえ検出されたカラープロファイル（たとえば、 "Apple Wide Color Sharing Profile"）。
colorsObjectいいえ検出された優勢色。キーは16進数コードで、値はその色の画像内の割合を表す浮動小数点数です。パーセンテージ値は、画像内のすべての色が返されるわけではないため、必ずしも1になるとは限りません。
content_typeStringいいえアセットの検出されたコンテンツタイプ（例： image/jpeg、image/gif）。サポートされていないまたは未知のコンテンツタイプの場合、値は application/octet-stream になる場合があります。
custom_fieldsObjectはいユーザーが追加したカスタムフィールドと値（例： { SKU: 1234 }）
date_createdIntegerいいえこのアセットがアセットマネージャーに最初に追加されたUnixタイムスタンプ（これは、imgixレンダリングサービスで画像が処理された最初の時間とは異なることに注意してください）。
date_modifiedIntegerいいえこのアセットが変更された最後の時間のUnixタイムスタンプ、エンドユーザーによってまたは自動更新によって。
descriptionStringはいアセットのユーザー提供の説明。
dpi_heightIntegerいいえ画像の高さのDPI。
dpi_widthIntegerいいえ画像の幅のDPI。
face_countIntegerいいえ画像内で検出された顔の数。 analyzed_faces が true の場合にのみ関連します。
file_sizeIntegerいいえバイト単位のアセットサイズ。
has_framesBooleanいいえアニメーション（ビデオまたはGIF）の場合は true、それ以外の場合は false。
media_heightIntegerいいえアセットのピクセル高さ。
media_kindStringいいえアセットのタイプ。可能な値： IMAGE、ANIMATION、DOCUMENT、VECTOR。
media_widthIntegerいいえアセットのピクセル幅。
nameStringはいアセットのユーザー提供の名前。 origin-path は変更されません。
origin_pathStringいいえソースのプレフィックスに対するアセットのパス。
source_idStringいいえこのアセットが関連付けられているソースのID。
tagsObjectはい画像を説明する機械学習生成のタグ。キーはタグテキスト（例：「Dog」）、値は信頼レベルを表す浮動小数点数で、 0 が信頼できないことを示し、 1 が100%の信頼を示します。
uploaded_byStringいいえアセットがアセットマネージャーUI経由でアップロードされた場合のユーザーのID。
uploaded_by_apiBooleanいいえアセットがAPIリクエスト経由でアップロードされた場合は true、それ以外の場合は false。
video_aspect_ratioStringいいえビデオのアスペクト比。
video_audio_channel_layoutStringいいえビデオのオーディオチャンネルレイアウト。
video_durationIntegerいいえ秒単位で表されるビデオの再生時間。
video_error_messageStringいいえビデオの処理ができない場合のエラーメッセージ。それ以外の場合は null 。
video_has_audioBooleanいいえビデオにオーディオがある場合は true、それ以外の場合は false 。
video_imgix_statusStringいいえビデオの処理状態。可能な値：
TRANSCODE_STARTED：ビデオファイルが処理中
VIDEO_READY：ビデオが処理され、再生可能
ERRORED：ビデオの処理に問題が発生しました
video_max_stored_frame_rateFloatいいえビデオの最大保存フレームレート
video_max_stored_resolutionStringいいえビデオの最大保存解像度
video_max_stored_resolution_xIntegerいいえビデオの最大保存幅
video_max_stored_resolution_yIntegerいいえビデオの最大保存高さ
video_playback_urlStringいいえビデオ再生URL
warning_adultIntegerいいえコンテンツ警告レベルを説明する 0 から 5 までの数値。 analyzed_content_warnings が true の場合にのみ関連します。 0 は不明であり、 1 は低確率、 5 は高確率を意味します。
warning_medicalIntegerいいえwarning_adult と同じ動作です。
warning_racyIntegerいいえwarning_adult と同じ動作です。
warning_spoofIntegerいいえwarning_adult と同じ動作です。
warning_violenceIntegerいいえwarning_adult と同じ動作です。

アセットリストのページネーション

レスポンスには、以下のような cursor が含まれます：

"cursor": {
  "current": "20",
  "hasMore": true,
  "next": "22",
  "totalRecords": "68",
}

current は現在のページに対応し、 next は hasMore が true の場合に次のページの結果を取得するために渡すべきカーソル値です。 totalRecords は検索クエリによって見つかった合計レコード数を提供します。ただし、実際に一致するレコードの数に関係なく、最大で 1,001 件のカウントを返します。

ソースへのアセットのアップロード

imgix Management API を使用すると、クラウドストレージにバックアップされたソース（Azure、GCS、またはS3）に直接アップロードできます。API は、ソースが読み取りを行うバケットにアップロードします。Web フォルダーまたは Web プロキシソースへのアップロードはサポートされていません。

ソースでのアップロードを有効にするには、imgix がクラウドストレージにアップロードするための資格情報を提供する必要があります。これらをソースの upload_credentials と呼びます。最初にソースを設定する際に提供した資格情報で、imgix レンダリングサービスがオリジンからアセットを取得するために使用されます。レンダリングサービスはアセットを取得するために書き込み権限が必要ないため、upload_credentials と deployment_credentials を同じ資格情報に使用しないことを強くお勧めします。

注意：オリジンに既に存在するパスにアセットをアップロードすることはできません。そのパスにすでにアセットが存在する場合、API はオリジンに既に存在するアセットを示すために 409 Conflict エラーを返します。

アップロード資格情報の属性

フィールド必須？説明
typeYes受け入れられる値は azure、gcs、および s3 です。
azure_sas_stringYesazure タイプのソースにのみ必要です。Azure の資格情報の作成方法については、こちら を参照してください。
gcs_access_keyYesgcs タイプのソースにのみ必要です。
gcs_secret_keyYesgcs タイプのソースにのみ必要です。提供されると、返されません。こちら を参照して GCS の資格情報を作成してください。
s3_access_keyYess3 タイプのソースにのみ必要です。
s3_secret_keyYess3 タイプのソースにのみ必要です。提供されると、返されません。こちら を参照して S3 の資格情報を作成してください。

upload_credentials を提供するには、新しい資格情報とソースの type を upload_credentials オブジェクト内に入れてソースに PATCH リクエストを行います。upload_credentials の type はソースの type と一致している必要があり、提供された資格情報は有効で、ソースのクラウドストレージバケットに書き込み権限を提供する必要があります。

次に、S3 ソースにアップロード資格情報を更新するための例です：

PATCH /api/v1/sources/5ae507164b595f0001e048bc
 
{
  "data": {
    "attributes": {
      "upload_credentials": {
        "s3_access_key": "<s3-access-key>",
        "s3_secret_key": "<s3-secret-key>",
        "type": "s3"
      }
    },
  "id": "5ae507164b595f0001e048bc",
  "type": "sources"
  }
}

適切な upload_credentials がソースに設定されている場合、アセットをアップロードするには、生のアセットデータを含むリクエストボディで api/v1/sources/:source_id/upload/:origin_path に POST リクエストを行います。レスポンスは api/v1/assets/:source_id/:origin_path への GET リクエストと同じになります。

アセットの追加

add エンドポイントは、オリジンからアセットマネージャーに追加されるパスをキューに入れます。アセットが正常に追加されるには、次の条件が必要です。

  • アセットのパスが存在する必要があります
  • アセットのパスがオリジンから 200 のレスポンスを返す必要があります
  • ソースに十分な読み取り権限が必要です

add エンドポイントは、アップロードエンドポイントやアセットマネージャーUI (opens in a new tab)を使用せずにアセットをアップロードし、imgixが定期的に新しいアセットをオリジンからクロールすることを依存している場合に便利です。

アセットを追加するには、空のPOSTボディを使用して sources/:source_id/assets/add/:origin-path に対して POST リクエストを発行します。

以下に例を示します：

POST api/v1/sources/5ae507164b595f0001e048bc/assets/add/marketing/logo.png
{}

これにより、サーバーから 202 の空のレスポンスが返されます。add エンドポイントはアセットを処理するためにキューに入れるだけであり、アセットをキューに入れた後は、アセットの取得エンドポイントをポーリングしてアセットのステータスを取得できます。

アセットの更新

アセットの更新は、オリジンでアセットが更新されたが、imgixが使用する自動更新プロセス（24〜48時間かかる場合がある）がまだその変更を取得していない場合に便利です。 これらの場合、アセットを更新するリクエストを行うと、次のことが行われます。

  1. オリジンからアセットを再取得します。
  2. ETag (opens in a new tab) が最後にアセットが処理されたときから変更されている場合、アセットを再処理します。
    • アセットが以前にアセットマネージャーに取り込まれたことがない場合、リフレッシュエンドポイントはアセットをアセットマネージャーに取り込みます。
  3. すべてのimgixキャッシュからアセットを削除します。 更新されたアセットを表示するには、ブラウザを強制的に更新する必要がある場合があります。

アセットをリフレッシュするには、空の POST ボディを使用して sources/:source_id/assets/refresh/:origin-path に対して POST リクエストを発行します。

以下に例を示します：

POST api/v1/sources/5ae507164b595f0001e048bc/assets/refresh/marketing/logo.png
{}

アセットのETagが前回処理されたときのETagと異なる場合、アセットは再処理されます。その後、アセットは削除され、レスポンスはsources/:source_id/assets/:origin_pathに対してGETリクエストを発行した場合と同様です。

アップロードセッションの使用

ビデオなどの50MBを超えるアセットをアップロードする場合は、アップロードセッションのフローを使用することをお勧めします。これは、セッションを作成し、そのセッションにファイルをアップロードし、最後にセッションを閉じる多部分、順次フローです。 注意：これは現在、Amazon S3とGoogle Cloud Storageソースにのみ対応しており、ファイルサイズが5GBまでサポートされています。

アップロードセッションフロー：

  1. アップロードセッションを作成します。 アップロードされるファイルごとに1つのセッションを作成する必要があります。 セッションと署名付きURLは8時間開いたままになります。
  2. セッションの署名付きURLを使用して、ファイルをアップロードするためのHTTP PUTを実行します。
  3. アップロードが完了したら、セッションを閉じます。 セッションを閉じることは必須ではありませんが、アセットの処理を迅速化し、強く推奨されます。閉じられていないセッションは8時間後に閉じられます。
  4. アップロードのステータスを確認して、処理状態を確認します。有効なアップロードセッションの状態については以下を参照してください。

セッションには、アセットのアップロードステータスを追跡するための次の状態があります。

  • PENDING: セッションは開いています。
  • CLOSED: アップロードされたアセットがシステムによって処理されています。
  • COMPLETE: 処理が完了しました。ビデオアセットの場合、トランスコーディングプロセスの完了には追加の時間が必要です。
  • CANCELED: セッションがキャンセルされました。

Pythonでのフルアップロードセッションフローの例

import os
import requests
 
 
API_KEY = ""
BASE_URL = "https://api.imgix.com/api/v1/"
SOURCE_ID = ""
ORIGIN_PATH = ""
LOCAL_FILE = "/path/to/file"
 
 
session = requests.post(
    f"{BASE_URL}sources/{SOURCE_ID}/upload-sessions/{ORIGIN_PATH}",
    headers={"Authorization": f"Bearer {API_KEY}"},
).json()
 
with open(LOCAL_FILE, "rb") as f:
    requests.put(
        session["data"]["attributes"]["url"],
        f.read(),
        headers={"Content-Type": "image/jpeg"},
    )
 
session_id = session["data"]["id"]
closed_session = requests.post(
    f"{BASE_URL}sources/{SOURCE_ID}/upload-sessions/{session_id}",
    headers={"Authorization": f"Bearer {API_KEY}"},
).json()

アセットの例

単一のアセットの詳細を取得

GET /api/v1/assets/5b81e81539ddc50001a5d955/luke.jpg
{
  "data": {
    "attributes": {
      "analyzed_content_warnings": true,
      "analyzed_faces": false,
      "analyzed_tags": true,
      "categories": [
        "Summer Photos"
      ],
      "color_model": "RGB",
      "color_profile": null,
      "colors": {
        "dominant_colors": {
          "#353237": 0.11076190322637558,
          "#545355": 0.07571428269147873,
          "#65a6fa": 0.08052381128072739,
          "#90c4f8": 0.06638095527887344,
          "#927942": 0.002190476283431053,
          "#a39173": 0.0018095237901434302,
          "#b1e7fe": 0.09242857247591019,
          "#e77abc": 0.005857143085449934,
          "#eebbc0": 0.0033333334140479565,
          "#f8f78e": 0.011857142671942711
        }
      },
      "content_type": "image/jpeg",
      "custom_fields": {
        "Dog name": "Luke"
      },
      "date_created": 1569633867,
      "date_modified": 1596825719,
      "description": null,
      "dpi_height": 300,
      "dpi_width": 300,
      "face_count": 0,
      "file_size": 357679,
      "has_frames": false,
      "media_height": 1825,
      "media_kind": "IMAGE",
      "media_width": 1704,
      "name": null,
      "origin_path": "/luke.jpg",
      "source_id": "5b81e81539ddc50001a5d955",
      "tags": {
        "Canidae": 0.9813780188560486,
        "Carnivore": 0.8667572736740112,
        "Dog": 0.9953705072402954,
        "Dog breed": 0.9838448762893677,
        "Havanese": 1,
        "Mammal": 0.975814163684845,
        "Puppy": 0.8966773748397827,
        "Schnoodle": 0,
        "Sporting Group": 0.8070302605628967,
        "Vertebrate": 0.9851104021072388
      },
      "uploaded_by": null,
      "uploaded_by_api": false,
      "warning_adult": 1,
      "warning_medical": 1,
      "warning_racy": 1,
      "warning_spoof": 2,
      "warning_violence": 1
    },
    "id": "5b81e81539ddc50001a5d955/luke.jpg",
    "type": "assets"
  },
  "included": [],
  "jsonapi": {
    "version": "1.0"
  },
  "meta": {
    "authentication": {
      "authorized": true,
      "clientId": null,
      "mode": "PUBLIC_APIKEY",
      "modeTitle": "Public API Key",
      "tag": "cindy@ymail.com",
      "user": null
    },
    "server": {
      "commit": "8835d05b",
      "status": {
        "healthy": true,
        "read_only": false,
        "tombstone": false
      },
      "version": "3.120.0"
    }
  }
}

アセットのカテゴリとカスタムフィールドを更新

PATCH /api/v1/assets/5b81e81539ddc50001a5d955/luke.jpg
 
{
  "data": {
    "attributes": {
      "categories": [
        "Summer Photos",
        "Pet Photos"
       ],
       "custom_fields": {
         "Date taken": "August 2020",
         "Photographer": "Molly"
       }
    },
    "type": "assets",
     "id": "5b81e81539ddc50001a5d955/luke.jpg"
    }
}
{
  "data": {
    "attributes": {
      "categories": [
        "Summer Photos",
        "Pet Photos"
       ],
       ...
       "custom_fields": {
         "Date taken": "August 2020",
         "Photographer": "Molly"
       },
       ...
    }
    ...
 }

ソース内のアセットの2ページ目を取得

GET /api/v1/assets/5b81e81539ddc50001a5d955?page[cursor]=40&page[limit]=20
{
  "data": [
     ...
   ],
   ...
   "cursor": {
     "current": "40",
     "estimatedRecords": null,
     "hasMore": true,
     "next": "60",
     "totalRecords": null
    }
    ...
}

色でフィルタリングされ、作成日時でソートされたアセットを取得します。最新のものが最初に来ます

GET /api/v1/assets/5b81e81539ddc50001a5d955?filter[colors]=8ca091&sort=-date_created
{
  "data": [
    {
      "attributes": {
      ...
        "colors": {
          "dominant_colors": {
            "#1b181a": 0.08416759222745895,
            "#343235": 0.09766407310962677,
            "#535153": 0.059176862239837646,
            "#a32438": 0.00037078236346133053,
            "#a49d97": 0.039377085864543915,
            "#b19f89": 0.05094549432396889,
            "#c8c1ba": 0.06518353521823883,
            "#d0bfa9": 0.10700778663158417,
            "#efe2cf": 0.06436781585216522,
            "#f7f3ee": 0.2693363130092621
          }
        },
        "content_type": "image/png",
        "custom_fields": null,
        "date_created": 1589337592,
	...
      },
      "id": "5b81e81539ddc50001a5d955/images/frances.jpg",
      "type": "assets"
    },
    {
      "attributes": {
      ...
        "colors": {
          "dominant_colors": {
            "#160802": 0.11790844798088074,
            "#230a03": 0.009009009227156639,
            "#2f1104": 0.04248843342065811,
            "#6a5340": 0.04790601506829262,
            "#6e4a36": 0.07487216591835022,
            "#8b6c5a": 0.010409058071672916,
            "#907864": 0.11200389266014099,
            "#a4958c": 0.011626491323113441,
            "#af967f": 0.1546749472618103,
            "#c4ae97": 0.0022522523067891598
          }
        },
        "content_type": "image/jpeg",
        "custom_fields": null,
        "date_created": 1587358372,
    	...
      },
      "id": "5b81e81539ddc50001a5d955/images/luke.jpg",
      "type": "assets"
    },
    ...
  ],
  ...
}

アセットをソースにアップロードする

POST /api/v1/sources/5b81e81539ddc50001a5d955/upload/marketing/logo.png
 
<raw binary image file>
{
  "data": {
    "attributes": {
      ...
      "origin_path": "/marketing/logo.png",
      "tags": {
        "Brand": 0.772368848323822,
        "Clip art": 0.5367497801780701,
        "Font": 0.9227379560470581,
        "Graphics": 0.7015061974525452,
        "Line": 0.7984547019004822,
        "Logo": 0.9082068800926208,
        "Text": 0.9606743454933167,
        "Trademark": 0.7562870383262634
      },
      ...
    },
    "id": "5b81e81539ddc50001a5d955/marketing/logo.png",
    "type": "assets"
  },
  "included": [],
  "jsonapi": {
    "version": "1.0"
  },
  "meta": {
   ...
  }
}

アップロードセッションを作成する

POST /api/v1/sources/5b81e81539ddc50001a5d955/upload-sessions/create/marketing/logo.png
{
  "data": {
    "attributes": {
      "date_created": 1653506429,
      "date_expires": 1653535229,
      "date_modified": 1653506429,
      "id": "77c0f903-9475-4a6a-9fad-3995a5ad8cfe",
      "origin_path": "/marketing/logo.png",
      "source_id": "5b81e81539ddc50001a5d955",
      "status": "PENDING",
      "url": "$PRESIGNED_UPLOAD_URL"
    },
    "id": "77c0f903-9475-4a6a-9fad-3995a5ad8cfe",
    "type": "asset_uploads"
  },
  "included": [],
  "jsonapi": {
    "version": "1.0"
  },
  "meta": {
    ...
  }
}

新しく作成したアップロードセッションからの url を使用して、アセットをアップロードする。

curl -XPUT $PRESIGNED_URL -T 'image.jpg'

アップロードセッションを取得する

GET /api/v1/sources/5b81e81539ddc50001a5d955/upload-sessions/status/77c0f903-9475-4a6a-9fad-3995a5ad8cfe
{
  "data": {
    "attributes": {
      "date_created": 1653506429,
      "date_expires": 1653535229,
      "date_modified": 1653506429,
      "id": "77c0f903-9475-4a6a-9fad-3995a5ad8cfe",
      "origin_path": "/marketing/logo.png",
      "source_id": "5b81e81539ddc50001a5d955",
      "status": "PENDING"
    },
    "id": "77c0f903-9475-4a6a-9fad-3995a5ad8cfe",
    "type": "asset_uploads"
  },
  "included": [],
  "jsonapi": {
    "version": "1.0"
  },
  "meta": {
    ...
  }
}

アップロードセッションを閉じる

POST /api/v1/sources/5b81e81539ddc50001a5d955/upload-sessions/close/77c0f903-9475-4a6a-9fad-3995a5ad8cfe
{
  "data": {
    "attributes": {
      ...
      "status": "CLOSED"
    },
    "id": "77c0f903-9475-4a6a-9fad-3995a5ad8cfe",
    "type": "asset_uploads"
  },
  "included": [],
  "jsonapi": {
    "version": "1.0"
  },
  "meta": {
    ...
  }
}

アップロードセッションをキャンセルする

DELETE /api/v1/sources/5b81e81539ddc50001a5d955/upload-sessions/cancel/77c0f903-9475-4a6a-9fad-3995a5ad8cfe
{
  "data": {
    "attributes": {
      ...
      "status": "CANCELED"
    },
    "id": "77c0f903-9475-4a6a-9fad-3995a5ad8cfe",
    "type": "asset_uploads"
  },
  "included": [],
  "jsonapi": {
    "version": "1.0"
  },
  "meta": {
    ...
  }
}
一般的な使い方ソース