2026-09-26Sume Avatar 1.0

스톡 AI 아바타 API: 말하는 영상에 바로 쓸 아바타 찾기

POST /v1/avatar-catalog/search로 Sume 아바타 카탈로그를 검색해 준비된 공개 아바타를 고르고, 아바타를 만들 필요 없이 그 handle을 말하는 영상에 넘기세요.

읽는 시간 5분Sume

Sume API로 스톡 AI 아바타를 쓰려면 POST /v1/avatar-catalog/search로 아바타 카탈로그를 검색해 준비된 결과를 고르고, 그 handle을 avatar_handle로 POST /v1/avatar-1.0/talking-video에 넘기세요. 결과에는 인증된 모든 호출자가 쓸 수 있는 공개 시스템 아바타와, 여러분의 워크스페이스가 소유한 아바타가 포함됩니다.

요청·응답 필드는 Sume API 레퍼런스 스키마에서 가져왔고, 이 라우트는 Sume의 API 레퍼런스 문서 페이지에 나와 있습니다. 모두 2026-09-26에 확인했습니다. 진행자를 직접 만들고 싶다면 재사용 가능한 AI 아바타 만들기를 참고하세요.

아바타 카탈로그는 어떻게 검색하나요?

검색하려면 텍스트 query를 보내고, 둘러보려면 생략하세요. query가 있으면 기본 모드는 search입니다. 관련성을 우선하는 순위이며, shuffle을 요청하지 않는 한 결정적으로 유지됩니다. query가 없으면 기본값은 explore로, 둘러보기용으로 시드 기반 다양성을 더합니다. 필터는 어느 모드에서든 결과를 좁힙니다. 다음 요청은 준비된 공개 아바타를 찾습니다.

curl -X POST https://api.sume.com/v1/avatar-catalog/search \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "warm skincare creator",
    "filters": {
      "status": "ready",
      "visibility": "public",
      "product_category": "beauty"
    },
    "limit": 10
  }'

어떤 검색 필드를 보낼 수 있나요?

query를 포함해 모든 필드가 선택 사항입니다.

API 레퍼런스에 나온 `POST /v1/avatar-catalog/search`의 Sume API 레퍼런스 스키마 기준, 2026-09-26 확인.
필드	값	하는 일
`query`	1-500자	공개 가능한 아바타 메타데이터와 표시 필드에 대해 매칭.
`mode`	`search` 또는 `explore`	query가 있으면 `search`, 없으면 `explore`가 기본값.
`limit`	1-100, 기본값 20	반환할 아바타 수.
`seed`, `shuffle`	1-128자 / boolean, 기본값 false	`shuffle`은 search 모드에 시드 기반 지터를 더함. 같은 `seed`를 쓰면 explore와 shuffle 결과가 안정적으로 유지됨.
`diversity`	0-1	값이 클수록 다양성이 커짐. 기본값은 search에서 0.2, explore에서 0.5.
`auto_expand`, `min_results`	boolean, 기본값 true / 1-100, 기본값 5	결과가 `min_results`보다 적으면 소프트 텍스트, `product_category`, `best_for` 순으로 조건을 완화. 언어, 공개 범위, 소유권은 완화하지 않음.
`filters`	`status`, `visibility`, `product_category`, `product_categories`, `use_case`, `best_for`, `language`	`status`의 기본값은 `ready`. `visibility`는 `public` 또는 `private`.

검색 결과에는 무엇이 들어 있나요?

응답은 data.avatars[]와 함께 count, 요청에서 되돌려 준 query와 filters, 사용된 mode, seed_used, relaxed_filters를 담습니다. relaxed_filters는 auto_expand가 완화한 항목을 나열하며, 완화한 것이 없으면 비어 있습니다. 각 아바타에는 다음이 담깁니다.

id와 handle. 말하는 영상에 넘기는 값은 handle입니다.
metadata: avatar_profile_v1 프로필 또는 null입니다. 페르소나(요약, 말투, 언어 적합성), 외모, best_for, avoid_for, product_categories 같은 적합성, 샘플 미디어를 설명합니다.
search_score와 search_reasons: 그 결과의 텍스트 검색 점수 메타데이터입니다.

카탈로그 아바타를 말하는 영상에 어떻게 쓰나요?

talking-video 라우트는 준비된 아바타 handle로 스크립트 기반 영상을 만듭니다. 결과의 handle을 avatar_handle로 넘기세요. 현재 API는 여러분의 아바타뿐 아니라 공개 시스템 아바타의 handle도 해석합니다. 이 라우트에는 준비된 아바타가 필요하므로 기본 status: "ready" 필터를 그대로 두세요. 아바타가 영상에 쓸 준비가 되지 않았다면 라우트는 avatar_not_ready와 함께 409를 반환합니다.

아바타 생성 단계를 건너뛰므로 API 요금에 나온 일회성 생성 비용(아바타당 $0.95)이 들지 않습니다. 영상 자체는 아바타 영상 초당 요율로 과금되며, 요율은 초당 $0.184(standard), $0.245(plus), $0.55(max), 제품 이미지 없음 기준입니다. 여기에 기본적으로 5.5% 에이전트 수수료가 더해집니다.

curl -X POST https://api.sume.com/v1/avatar-1.0/talking-video \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: catalog-avatar-video-001" \
  -d '{
    "avatar_handle": "HANDLE_FROM_SEARCH",
    "script": "Meet the Acme travel mug, now in three colors.",
    "aspect_ratio": "9:16"
  }'

카탈로그 검색이 하지 않는 일은 무엇인가요?

카탈로그 검색은 아바타를 찾을 뿐, 만들거나 바꾸지 않습니다.

아무것도 만들지 않습니다. 새 아바타는 유료 Job인 POST /v1/avatar-1.0/generate로 만듭니다.
비공개 결과는 인증된 소유 워크스페이스로 한정되므로, 다른 워크스페이스의 아바타는 보이지 않습니다.
auto_expand는 language, visibility, 소유권을 완화하지 않습니다. 필터를 엄격하게 적용하려면 false로 설정하세요.
호스팅 MCP에서는 같은 검색이 avatars_search이며, 유료 도구가 아니라 읽기 도구로 분류되어 있습니다.

출처

작성자 Sume