시작하기
공개 API로 현재 계정의 데이터를 조회하고 소유한 일반 모델 키를 관리합니다. 상위 계정에 하위 계정 데이터 권한이 자동으로 부여되지 않으며, 관리자도 자신의 리소스만 사용할 수 있습니다.
공개 API로 현재 계정의 데이터를 조회하고 소유한 일반 모델 키를 관리합니다. 상위 계정에 하위 계정 데이터 권한이 자동으로 부여되지 않으며, 관리자도 자신의 리소스만 사용할 수 있습니다.
국제 서비스는 https://api.toapis.com, 중국 본토 서비스는 https://api.toapis.cn을 사용합니다. 이 API 그룹에 웹사이트 루트 도메인을 사용하지 마세요.
시스템 액세스 토큰 발급
계정 설정에서 시스템 액세스 토큰을 발급합니다. 다시 발급하면 기존 토큰은 무효화되므로 연동 설정도 갱신해야 합니다.
모든 요청은 Authorization 헤더에 Bearer YOUR_SYSTEM_ACCESS_TOKEN을 담으며 헤더는 하나만 보냅니다. 모델 API 키 (sk-...), 쿠키, URL 자격 증명, Agent/MCP 토큰은 신원으로 사용할 수 없고 X-User-Id도 필요 없습니다.
시스템 액세스 토큰은 키 쓰기 작업도 할 수 있으므로 읽기 전용 자격 증명이 아닙니다.
선택 헤더 X-Locale은 en, zh, zh-TW, ja, ko, ru를 지원합니다. 유효한 값이 없으면 계정 언어 설정과 협상 결과를 사용하며 요청이 계정 설정을 초기화하지는 않습니다. 결과 판단은 HTTP 상태와 숫자 code로 하고 언어에 따라 바뀌는 message는 비교하지 마세요.
curl https://api.toapis.com/api/v1/account \
--header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN'응답 및 금액
모든 응답의 최상위 필드는 code, message, data 세 개뿐입니다. 성공 시 code=0, message=""이고 HTTP 상태는 일반 성공 200, 키 생성 201, Webhook 테스트 큐 등록 및 파일 삭제 접수 202입니다.
실패 시 실제 HTTP 상태가 유지되고 오류 data에는 param, params, request_id 또는 null만 포함되며 내부 오류 상세는 공개되지 않습니다.
리소스 ID와 금액은 십진 문자열이고 Webhook의 api_key_id는 정수입니다. 시간은 시간대가 있는 RFC 3339이며 확인할 수 없거나 해당 없는 값은 필드 규약에 따라 null을 반환합니다. 잔액과 사용량은 USD와 credits를 함께 반환하며 환산 기준은 응답의 credits_per_usd입니다.
결제 금액은 원래 통화를 유지합니다.
모든 응답에 Cache-Control: private, no-store와 X-Request-Id 헤더가 포함됩니다. X-Request-Id는 이번 API 요청을 나타내며 사용량 trace에 기록된 원래 생성 요청 ID와는 다른 값입니다.
{
"code": 0,
"message": "",
"data": {
"items": [],
"has_more": false,
"next_cursor": null,
"meta": {}
}
}페이지와 시간 범위
사용자 파일 목록을 제외한 목록은 data.items, has_more, next_cursor, meta를 반환합니다. 빈 목록의 items는 [], 마지막 페이지의 next_cursor는 null이며 총 개수는 반환하지 않습니다. 다음 페이지는 next_cursor를 그대로 cursor에 전달하고 필터를 유지합니다.
필터를 바꾸면 첫 페이지부터 다시 시작하세요.
시간 범위는 UTC 반개구간 [from, to)이며 초 단위 경계는 올림합니다. 기본 범위와 상한은 엔드포인트마다 다릅니다: 사용량은 매 페이지 from과 to가 필수이고 최대 31일, 작업은 기본 최근 24시간·최대 31일, 충전과 청구서는 기본 최근 31일·최대 366일입니다.
기본 범위는 첫 페이지에서 확정되므로 이후 페이지에서는 생략할 수 있습니다. 알 수 없는 파라미터, 중복 파라미터, 잘못된 이스케이프는 400을 반환합니다.
시간 범위는 UTC 반개구간 [from,to)이며 초 단위 경계는 올림합니다. 사용량은 모든 페이지에 from과 to가 필수이며 최대 31일입니다. 작업은 기본 24시간, 최대 31일, 충전 및 청구서는 기본 31일, 최대 366일입니다. 기본 범위는 첫 페이지에서 고정되므로 다음 페이지에서도 생략할 수 있습니다.
알 수 없는 매개변수, 중복 스칼라, 잘못된 이스케이프는 400입니다.
속도 제한 및 오류
읽기 요청은 사용자당 분당 120회를 공유합니다. 사용량 집계, 청구서, 요금은 각각 분당 6회의 추가 제한이 있으며 청구서 목록과 상세는 같은 한도를 공유합니다.
API Key, Webhook, 사용자 파일 쓰기는 별도의 사용자당 분당 10회를 공유하며 읽기 한도를 사용하지 않습니다. 시스템 토큰을 다시 발급해도 한도는 초기화되지 않고 새 경로와 기존 호환 경로는 같은 한도를 공유합니다.
요청 빈도나 동시 요청 수가 많으면 429가 반환될 수 있습니다. Retry-After에 무작위 지연을 더해 재시도하세요. 503은 서비스를 일시적으로 사용할 수 없음을 뜻합니다. 요청 빈도를 낮추고 시간 초과된 생성, 교체, 삭제 요청을 무조건 재전송하지 마세요.
| HTTP | code | 처리 |
|---|---|---|
| 400 | 10001 / 10004 / 13002 / 13028 / 16014 | 본문, 매개변수 또는 커서를 수정하세요. |
| 401 | 11032 / 11059 | 시스템 액세스 토큰을 확인하세요. |
| 403 | 11023 / 12001 / 12002 / 12006 / 13003 | 계정 상태, 리소스 권한 및 키 그룹을 확인하세요. |
| 404 | 13001 / 16008 | 리소스가 없거나 다른 계정 소유입니다. |
| 409 | 13004 / 13005 / 13006 / 15045 / 16015 / 16016 | 키 개수, 만료, 할당량 또는 결제 연결 조건을 해결하세요. |
| 429 | 10002 | Retry-After에 따라 대기하세요. |
| 500 | 10000 / 13029 | 조사를 위해 request_id를 보관하세요. |
| 503 | 11001 / 13030 / 13032 / 13035 / 15046 / 15047 / 18028 / 18029 | 대기하고 필요하면 사용량 범위를 줄이세요. |
데이터 범위
상위 계정은 자신의 데이터만 볼 수 있고 구성원 (하위 계정) 데이터는 포함되지 않으며 하위 계정은 결제를 조회할 수 없습니다. 사용량 레코드는 소비 로그의 실시간 스냅샷으로 이후 정산과 환불로 바뀌므로 최종 순지출과 같지 않습니다.
작업 API는 저장된 작업 메타데이터와 확인 가능한 과금만 반환하며 생성 결과, 상류 폴링, 정산, 환불을 수행하지 않습니다. 충전에는 수동 지급 크레딧과 별도 오프라인 환불이 제외되고 청구서는 현재 검증된 Stripe Customer만 대상입니다.
리소스 ID는 키 목록이나 상세의 숫자 id를 사용하고 비밀 키 문자열 (sk-...)은 사용할 수 없습니다. 전체 비밀 키는 생성과 교체 응답에서 한 번만 반환되고 이후 모든 조회에서 반환되지 않습니다. 쓰기 성공은 설정이 저장되었다는 뜻이며 적용까지 잠시 걸릴 수 있습니다.
키를 비활성화, 교체, 폐기하면 진행 중인 요청이나 작업이 실패할 수 있습니다. 작업 자동 취소나 환불은 제공하지 않고 신구 비밀 키가 동시에 유효한 기간도 없습니다.
엔드포인트
아래 기본 경로를 사용하세요. 호환을 위해 유지되는 기존 /api/v1/account/... GET 경로와 이전 API 마이그레이션은 변경 내역을 참조하세요.
사용자 파일 API는 등록된 파일, 보존 기간, 비동기 삭제를 관리합니다. 파일 목록은 페이지 규약의 예외로 items, next_cursor만 반환하며 마지막 커서는 ""이고 has_more와 meta가 없습니다. 삭제 접수는 HTTP 202입니다. 보존 설정과 삭제는 계정 쓰기 예산을 공유합니다. 사용자 기한은 플랫폼 자동 정리가 켜져야 적용되지만 수동 삭제는 무관합니다. 범위와 예제는 아래 사용자 파일 API를 참고하세요.
| HTTP | |
|---|---|
GET /api/v1/account | 계정 정보 조회 |
GET /api/v1/account/balance | 계정 잔액 조회 |
GET /api/v1/api-keys | API 키 목록 조회 |
GET /api/v1/api-keys/{api_key_id} | API 키 상세 조회 |
GET /api/v1/api-keys/{api_key_id}/balance | 키 잔액 조회 |
POST /api/v1/api-keys | API 키 생성 |
PATCH /api/v1/api-keys/{api_key_id} | API 키 수정 |
DELETE /api/v1/api-keys/{api_key_id} | API 키 폐기 |
POST /api/v1/api-keys/{api_key_id}/rotate | API 키 교체 |
GET /api/v1/webhook | Webhook 설정 조회 |
PATCH /api/v1/webhook | Webhook 설정 수정 |
POST /api/v1/webhook/rotate-secret | Webhook 서명 비밀 키 교체 |
POST /api/v1/webhook/test | Webhook 테스트 |
GET /api/v1/webhook/events | Webhook 이벤트 목록 |
GET /api/v1/webhook/events/{event_id} | Webhook 이벤트 조회 |
GET /api/v1/usage/records | 사용량 내역 조회 |
GET /api/v1/usage/summary | 사용량 집계 조회 |
GET /api/v1/tasks | 계정 작업 목록 조회 |
GET /api/v1/tasks/{task_id} | 계정 작업 상세 조회 |
GET /api/v1/billing/topups | 충전 주문 목록 조회 |
GET /api/v1/billing/topups/{trade_no} | 충전 주문 상세 조회 |
GET /api/v1/billing/payment-method | 결제 수단 조회 |
GET /api/v1/billing/auto-topup | 자동 충전 설정 조회 |
GET /api/v1/billing/stripe/invoices | 청구서 목록 조회 |
GET /api/v1/billing/stripe/invoices/{invoice_id} | 청구서 상세 조회 |
GET /api/v1/pricing | 모델 가격 조회 |
GET /api/v1/user/file | 사용자 파일 목록 |
GET /api/v1/user/file/retention | 파일 보존 기간 조회 |
PUT /api/v1/user/file/retention | 파일 보존 기간 설정 |
POST /api/v1/user/file/deletion-requests | 파일 삭제 요청 생성 |
GET /api/v1/user/file/deletion-requests/{id} | 파일 삭제 진행 상황 조회 |
Webhook
연동 순서:
POST /api/v1/webhook/rotate-secret로 서명 비밀 키를 생성해 수신 측에 저장합니다.PATCH /api/v1/webhook으로 콜백 URL을 설정해 활성화합니다.POST /api/v1/webhook/test로 테스트 이벤트를 보내거나 이벤트 목록에서 전달 결과를 확인합니다.
서명 검증 규칙과 전체 절차는 Webhook 설정 조회를 참고하세요.