GET
/
v1
/
voice-usage
curl --request GET \
  --url https://supertoneapi.com/v1/voice-usage \
  --header 'x-sup-api-key: <x-sup-api-key>'
{
  "usages": [
    {
      "date": "<string>",
      "voice_id": "<string>",
      "name": "<string>",
      "style": "<string>",
      "language": "<string>",
      "model": "<string>",
      "thumbnail_url": "<string>",
      "total_minutes_used": 123
    }
  ]
}

이 API는 지정한 기간 동안 TTS API 사용 내역을 조회합니다.
클론 보이스 포함, 어떤 보이스를 몇 분 동안 사용했는지 파악할 수 있어요.

조회 일자는 UTC+0 기준이라는 사실을 유의해주세요.

​
요청 파라미터

파라미터필수설명
start_date✅조회 시작일 (형식: YYYY-MM-DD, UTC+0 기준)
end_date✅조회 종료일 (형식: YYYY-MM-DD, UTC+0 기준)
x-sup-api-key⭕인증용 API Key (Header에 포함)

​
예시 요청

GET /v1/voice-usage?start_date=2025-05-19&end_date=2025-05-28
x-sup-api-key: [YOUR_API_KEY]

​
응답 예시

{
  "usages": [
    {
      "date": "2025-05-22",
      "voice_id": "e5f6fb1a53d0add87afb4f",
      "name": "Agatha",
      "style": "neutral",
      "language": "en",
      "model": "sona_speech_1",
      "total_minutes_used": 12.43251349
    },
    {
      "date": "2025-05-24",
      "voice_id": "opSGuRvHBe7EfZ4LQga1hE",
      "name": "My Voice 1",
      "style": "sad",
      "language": "ko",
      "model": "sona_speech_1",
      "total_minutes_used": 3.24566213
    }
  ]
}

​
활용 예시

  • 특정 날짜별 TTS 사용량 합산
  • 어떤 캐릭터/스타일이 많이 쓰였는지 파악
  • 월별 예산 관리 또는 내부 보고용 로그로 활용 가능

​
유의사항

  • 조회 가능한 최대 기간은 30일입니다.
  • 해당 기간 동안 사용 기록이 없으면 빈 배열이 반환됩니다.
  • total_minutes_used는 실제 생성된 음성의 길이를 기반으로 합니다.

Headers

​
x-sup-api-key
string
required

The API key to authenticate and authorize access to the service. This key is required for every request.

Query Parameters

​
start_date
string
required

The start date in YYYY-MM-DD format.

Example:

"2024-11-01"

​
end_date
string
required

The end date in YYYY-MM-DD format.

Example:

"2024-11-30"

Response

200
application/json

A list of TTS API usage records matching the specified date range.

The response is of type object.