人物リストの照会

Prev Next

最新のコンテンツが反映されていません。早急にアップデート内容をご提供できるよう努めております。最新のコンテンツ内容は韓国語ページをご参照ください。

VPC環境で利用できます。

人物リストを照会します。

リクエスト

リクエスト形式を説明します。リクエスト形式は次の通りです。

メソッド URI
GET /api/v1/workspaces/{workspace_name}/persons

リクエストヘッダ

Media Intelligence API で共通して使用されるヘッダの詳細は、Media Intelligenceのリクエストヘッダをご参照ください。

リクエストパスパラメータ

リクエストパスパラメータの説明は次の通りです。

フィールド タイプ 必須の有無 説明
workspace_name String Required ワークスペース名

リクエストクエリパラメータ

リクエストクエリパラメータの説明は次の通りです。

フィールド タイプ 必須の有無 説明
pageNum Integer Required ページ番号
  • 1以上
pageSize Integer Optional ページごとの項目数
  • 1~1,000 (デフォルト: 1,000)
name String Optional 検索する人物名
  • 2~50文字
  • セミコロン(;)、バーティカルバー(\|)、バッククォート(`)は使用不可
tagIdList Array<Integer> Optional 検索する人物タグ IDリスト
  • ,で区切られた複数 ID入力をサポート

リクエスト例

リクエストのサンプルコードは次の通りです。

curl --location --request GET 'https://maiu.apigw.ntruss.com/api/v1/workspaces/my-workspace/persons?pageNum=1&pageSize=10&name=ホン・ギルドン&tagIdList=100,200' \
--header 'x-ncp-apigw-timestamp: {Timestamp}' \
--header 'x-ncp-iam-access-key: {Access Key}' \
--header 'x-ncp-apigw-signature-v2: {API Gateway Signature}' \
--header 'Content-Type: application/json'

レスポンス

レスポンス形式を説明します。

レスポンスボディ

レスポンスボディの説明は次の通りです。

フィールド タイプ 必須の有無 説明
code String Required API処理結果コード
message String Required API処理結果メッセージ
result Object Required 人物リスト照会の結果

result

result項目の説明は次の通りです。

フィールド タイプ 必須の有無 説明
content Array Required 人物リスト
totalCount Integer Required 人物の総数
totalPage Integer Required ページの総数
pageNo Integer Required 現在のページ番号
pageSize Integer Required ページごとの項目数

result.content

result.content項目の説明は次の通りです。

フィールド タイプ 必須の有無 説明
id Integer Required 人物 ID
name String Required 人物名
description String Optional 人物の説明
tagNames Array Required 人物タグ名リスト
  • 0~
thumbnailId Integer Optional 代表サムネイル ID
thumbnailUrl String Optional 代表サムネイル画像 URL
  • Presigned URL
updatedTime String Required 人物情報の最終更新日時
  • ISO 8601形式
updatedUserName String Required 人物情報を最後に更新したユーザー名

レスポンスステータスコード

Media Intelligence APIで共通して使用されるレスポンスステータスコードの詳細は、Media Intelligenceのレスポンスステータスコードをご参照ください。

レスポンス例

レスポンスのサンプルコードは次の通りです。

{
  "code": "0",
  "message": "success",
  "result": {
    "content": [
      {
        "id": 1001,
        "name": "ホン・ギルドン",
        "description": "韓国の代表的な仮想人物です。",
        "tagNames": ["歌手", "テレビ俳優"],
        "thumbnailId": 3001,
        "thumbnailUrl": "https://maiu.presigned.ncloudstorage.com/persons/thumbnails/hong.jpg?...",
        "updatedTime": "2025-08-15T17:13:48Z",
        "updatedUserName": "ホン・*ドン"
      }
    ],
    "totalCount": 2,
    "totalPage": 1,
    "pageNo": 1,
    "pageSize": 10
  }
}