🔑 Ability 카탈로그
API 토큰의 ability(허용 action)는 그 토큰으로 무엇을 호출할 수 있는지 결정합니다.
정책 평가기는 default-deny 입니다. 필요한 ability 가 없으면 요청이 막히거나 기능만 조용히 비활성화됩니다 — 서비스는 정상이고 다른 기능은 잘 동작하므로, 원인이 권한이라는 것을 알아채기 어렵습니다. 이 페이지는 어떤 ability 가 어떤 기능을 여는지 를 정리합니다.
ability 는 서비스 스코프로 걸러집니다
토큰에는 service 가 있습니다(speech, pronunciation, tts …). 발급/편집 화면의
Allowed Actions 목록은 그 service 에 해당하는 ability 만 보여줍니다.
그래서 화면에 체크박스가 보이지 않는다면 두 가지 중 하나입니다.
| 상황 | 뜻 | 조치 |
|---|---|---|
| 그 service 의 카탈로그에 없다 | 그 토큰 종류로는 쓰지 않는 기능이다 | 해당 service 토큰을 따로 발급 |
| 써야 하는데 목록에 없다 | 카탈로그 누락 — 기능은 그 ability 를 요구하는데 부여할 방법이 없는 상태 | 운영자에게 문의 (플랫폼 수정 필요) |
최소권한
카테고리 wildcard(tts:*)는 그 네임스페이스 전체를 엽니다. 필요한 개별 action 만 고르는 편이
안전합니다. 최상위 wildcard * 는 all service 토큰에서만 노출됩니다.
각 ability 가 실제로 무엇을 막는가
아래는 서비스가 실제로 검사하는 ability 입니다. 목록에는 있으나 아직 어떤 경로도 검사하지 않는 ability 는 부여해도 동작이 달라지지 않습니다.
| Ability | 이것이 없으면 |
|---|---|
conversation:stream | 실시간 음성 대화 세션을 시작할 수 없습니다 |
conversation:assessment_on_end | 대화가 끝날 때 종합 평가 리포트가 생성되지 않습니다(경고만 전달) |
pronunciation:assess:script | 대화 중 실시간 발음 평가가 비활성화됩니다 |
pronunciation:assess:free · pronunciation:stream | 자유 발화 평가 · 스트리밍 평가 |
assessment:session:report | 세션 종합 리포트 조회 |
realtime:full · realtime:mini · gemini:live:* | 해당 실시간 모델 등급 |
tts:synthesize · tts:stream · stt:recognize · stt:stream | 각 합성/인식 경로 |
chorus:query · shortform:submit · render:submit · convert:audio | 각 서비스의 제출 경로 |
billing:read | 자기 계약 단가를 조회할 수 없어 재과금(소비자 미터링)이 불가능합니다 |
서비스 경계를 넘는 ability 가 있습니다
실시간 음성 대화에서 발음 평가를 켜려면 speech 토큰에 pronunciation:assess:script 가
필요합니다. 발음 평가가 pronunciation 네임스페이스에 있어 별도 토큰이 필요해 보이지만,
검사하는 주체는 대화 세션을 처리하는 speech 서비스입니다.
이 조합이 없으면 화면에서 "실시간 발음 평가" 를 켜도 세션 시작 직후 꺼집니다 — 세션 발급 응답의 availability 를 소비 측이 fail-closed 로 반영하기 때문입니다.
부여했는데 반영되지 않는 것 같다면
- 토큰의
service가 맞는지 확인하세요. ability 는 service 스코프로 걸러집니다. - 세션 토큰(단기 JWT)은 발급 시점의 ability 를 담습니다. 권한을 바꿨다면 새 세션을 발급해야 반영됩니다. 이미 진행 중인 세션에는 소급되지 않습니다.
- 그래도 안 되면 어떤 ability 가 거부됐는지 오류 코드와
request_id를 함께 문의하세요.
서비스별 부여 가능 목록
아래 표는 각 service 토큰의 Allowed Actions 에 노출되는 항목입니다.
all service 토큰은 전체를 노출하므로 생략합니다.
tts
| Ability | 설명 |
|---|---|
tts:* | TTS: * (TTS 전체) |
tts:synthesize | TTS Synthesize |
tts:synthesize:long | TTS Long Text |
tts:stream | TTS Streaming |
tts:voices | List Voices |
billing:* | Billing: * (단가·실비 조회 전체) |
billing:read | Billing: Read (재과금용 단가·확정 실비 조회) |
stt
| Ability | 설명 |
|---|---|
stt:* | STT: * (STT 전체) |
stt:recognize | STT Recognize |
stt:stream | STT Streaming |
stt:languages | List Languages |
billing:* | Billing: * (단가·실비 조회 전체) |
billing:read | Billing: Read (재과금용 단가·확정 실비 조회) |
llm
| Ability | 설명 |
|---|---|
llm:* | LLM: * (LLM 전체) |
llm:generate | LLM Generate |
llm:chat | LLM Chat |
billing:* | Billing: * (단가·실비 조회 전체) |
billing:read | Billing: Read (재과금용 단가·확정 실비 조회) |
speech
| Ability | 설명 |
|---|---|
tts:* | TTS: * (TTS 전체) |
tts:synthesize | TTS Synthesize |
tts:synthesize:long | TTS Long Text |
tts:stream | TTS Streaming |
tts:voices | List Voices |
stt:* | STT: * (STT 전체) |
stt:recognize | STT Recognize |
stt:stream | STT Streaming |
stt:languages | List Languages |
conversation:* | Speech: Conversation * (대화 전체) |
conversation:stream | Speech: Conversation (STT→LLM→TTS) |
conversation:assessment_on_end | Speech: Conversation Assessment on End (대화 종료 시 자동 세션 평가) |
realtime:* | Speech: Realtime * (Realtime 전체) |
realtime:mini | Speech: Realtime mini (gpt-4o-mini-realtime) |
realtime:full | Speech: Realtime full (gpt-4o-realtime) |
gemini:* | Speech: Gemini * (Gemini Live 전체) |
gemini:live:fast | Speech: Gemini Live Fast (gemini-2.5-flash-live) |
gemini:live:native | Speech: Gemini Live Native (native-audio, thinking) |
pronunciation:assess:script | Pronunciation: Script Assess |
billing:* | Billing: * (단가·실비 조회 전체) |
billing:read | Billing: Read (재과금용 단가·확정 실비 조회) |
profile:* | Profile: * (모든 restricted 프로필 허용, 와일드카드) |
profile:realtime-ultra | Profile: realtime-ultra (OpenAI Realtime full) |
profile:tutor-premium | Profile: tutor-premium |
profile:tutor-pro | Profile: tutor-pro |
profile:gemini-live-native | Profile: gemini-live-native |
pronunciation
| Ability | 설명 |
|---|---|
pronunciation:* | Pronunciation: * (발음 평가 전체) |
pronunciation:assess:script | Pronunciation: Script Assess |
pronunciation:assess:free | Pronunciation: Free Assess |
pronunciation:stream | Pronunciation: Streaming |
pronunciation:premium | Pronunciation: Premium (SpeechAce) |
assessment:* | Assessment: * (세션 종합 평가 전체) |
assessment:session:report | Assessment: Session Report (세션 집계 + LLM 리포트) |
assessment:report:save | Assessment: Report Save (리포트 저장) |
assessment:report:read | Assessment: Report Read (리포트 조회) |
assessment:report:delete | Assessment: Report Delete (리포트 삭제) |
billing:* | Billing: * (단가·실비 조회 전체) |
billing:read | Billing: Read (재과금용 단가·확정 실비 조회) |
profile:* | Profile: * (모든 restricted 프로필 허용, 와일드카드) |
profile:realtime-ultra | Profile: realtime-ultra (OpenAI Realtime full) |
profile:tutor-premium | Profile: tutor-premium |
profile:tutor-pro | Profile: tutor-pro |
profile:gemini-live-native | Profile: gemini-live-native |
image
| Ability | 설명 |
|---|---|
image:* | Image: * (이미지 API 전체) |
image:generate | Image: Generate |
image:edit | Image: Edit |
image:variation | Image: Variation |
billing:* | Billing: * (단가·실비 조회 전체) |
billing:read | Billing: Read (재과금용 단가·확정 실비 조회) |
email
| Ability | 설명 |
|---|---|
email:* | Email: * (이메일 API 전체) |
email:send | Email: Send (이메일 발송) |
billing:* | Billing: * (단가·실비 조회 전체) |
billing:read | Billing: Read (재과금용 단가·확정 실비 조회) |
storage
| Ability | 설명 |
|---|---|
storage:* | Storage: * (스토리지 API 전체) |
storage:upload | Storage: Upload |
storage:download | Storage: Temporary Download URL |
storage:metadata | Storage: Metadata Read |
storage:delete | Storage: Delete |
billing:* | Billing: * (단가·실비 조회 전체) |
billing:read | Billing: Read (재과금용 단가·확정 실비 조회) |
convert
| Ability | 설명 |
|---|---|
convert:* | Convert: * (변환 API 전체) |
convert:images | Convert: Images |
convert:markdown | Convert: Markdown |
convert:status | Convert: Status |
convert:output | Convert: Output |
convert:captions | Convert: Captions |
billing:* | Billing: * (단가·실비 조회 전체) |
billing:read | Billing: Read (재과금용 단가·확정 실비 조회) |
handwriter
| Ability | 설명 |
|---|---|
handwriting:* | Hand Writer: * (필기 인식 전체) |
handwriting:recognize | Hand Writer: Recognize |
billing:* | Billing: * (단가·실비 조회 전체) |
billing:read | Billing: Read (재과금용 단가·확정 실비 조회) |
assessment
| Ability | 설명 |
|---|---|
assessment:* | Assessment: * (세션 종합 평가 전체) |
assessment:session:report | Assessment: Session Report (세션 집계 + LLM 리포트) |
assessment:report:save | Assessment: Report Save (리포트 저장) |
assessment:report:read | Assessment: Report Read (리포트 조회) |
assessment:report:delete | Assessment: Report Delete (리포트 삭제) |
billing:* | Billing: * (단가·실비 조회 전체) |
billing:read | Billing: Read (재과금용 단가·확정 실비 조회) |
chorus
| Ability | 설명 |
|---|---|
chorus:* | Chorus: * (Chorus API 전체) |
chorus:query | Chorus: Query |
chorus:files:upload | Chorus: Files Upload |
chorus:jobs:broadcast | Chorus: Jobs Broadcast |
billing:* | Billing: * (단가·실비 조회 전체) |
billing:read | Billing: Read (재과금용 단가·확정 실비 조회) |
shortform
| Ability | 설명 |
|---|---|
shortform:* | Shortform: * (숏폼 오케스트레이션 전체) |
shortform:submit | Shortform: Submit |
shortform:read | Shortform: Read |
shortform:cancel | Shortform: Cancel |
shortform:assets | Shortform: Assets |
billing:* | Billing: * (단가·실비 조회 전체) |
billing:read | Billing: Read (재과금용 단가·확정 실비 조회) |
render
| Ability | 설명 |
|---|---|
render:* | Render: * (미디어 렌더 전체) |
render:submit | Render: Submit |
render:read | Render: Read |
render:cancel | Render: Cancel |
render:assets | Render: Assets |
billing:* | Billing: * (단가·실비 조회 전체) |
billing:read | Billing: Read (재과금용 단가·확정 실비 조회) |
edge-relay
| Ability | 설명 |
|---|---|
tts:* | TTS: * (TTS 전체) |
tts:synthesize | TTS Synthesize |
tts:synthesize:long | TTS Long Text |
tts:stream | TTS Streaming |
tts:voices | List Voices |
stt:* | STT: * (STT 전체) |
stt:recognize | STT Recognize |
stt:stream | STT Streaming |
stt:languages | List Languages |
conversation:* | Speech: Conversation * (대화 전체) |
conversation:stream | Speech: Conversation (STT→LLM→TTS) |
conversation:assessment_on_end | Speech: Conversation Assessment on End (대화 종료 시 자동 세션 평가) |
realtime:* | Speech: Realtime * (Realtime 전체) |
realtime:mini | Speech: Realtime mini (gpt-4o-mini-realtime) |
realtime:full | Speech: Realtime full (gpt-4o-realtime) |
gemini:* | Speech: Gemini * (Gemini Live 전체) |
gemini:live:fast | Speech: Gemini Live Fast (gemini-2.5-flash-live) |
gemini:live:native | Speech: Gemini Live Native (native-audio, thinking) |
billing:* | Billing: * (단가·실비 조회 전체) |
billing:read | Billing: Read (재과금용 단가·확정 실비 조회) |
profile:* | Profile: * (모든 restricted 프로필 허용, 와일드카드) |
profile:realtime-ultra | Profile: realtime-ultra (OpenAI Realtime full) |
profile:tutor-premium | Profile: tutor-premium |
profile:tutor-pro | Profile: tutor-pro |
profile:gemini-live-native | Profile: gemini-live-native |
함께 보면 좋은 문서
- API Access Keys — 발급·회수·정책 전반
- 인증 — 장기 키와 단기 세션 토큰의 역할 구분
- Sessions — 세션 발급 흐름