OpenAPI와 엔드포인트 목록
다운로드 가능한 OpenAPI 3.1 계약, 공개 엔드포인트와 해당 가이드, 공통 요청 헤더 및 운영 API 주소를 안내합니다.
기계가 읽을 수 있는 공개 계약은 OpenAPI 3.1 YAML로 제공됩니다. 클라이언트를 생성하거나 현재 공개 엔드포인트에 맞게 통합되었는지 검증하는 데 사용하세요.
운영 API 주소
https://api.spicyapi.ai는 OpenAPI servers[0].url에 선언된 유일한 운영 주소입니다. 작업 API는 /api/v1, 프로토콜 호환 API는 /v1과 /v1beta를 사용합니다.
콘솔을 열지 않고도 플랫폼 API로 모델을 선택하고, 비용을 추정하고, 지출을 확인할 수 있습니다. 모델 카탈로그는 계정에 적용되는 가격을 포함합니다. 가격이 매개변수에 따라 달라지면 정확한 입력으로 견적을 요청하세요. 작업 내역과 사용량의 범위는 호출에 사용한 API 키입니다. 키 생성·교체와 예산 설정은 콘솔에서 수행합니다. 각 표에서 엔드포인트를 자세히 설명하는 가이드로 연결됩니다.
모델 탐색, 가격과 계정 API
| 메서드 | 경로 | 용도 | 가이드 |
|---|---|---|---|
GET | /console/v1/catalog/models | 평가용 공개 카탈로그: API 키 불필요, 표준 가격, 요청 출발지 주소별 호출 제한 | 빠른 시작 |
GET | /api/v1/models | 호출 가능한 모델, 계정 가격 및 선택적 스키마 조회 | 모델 카탈로그 |
GET | /api/v1/models/{model} | 모델 하나와 전체 JSON Schema 조회 | 모델 카탈로그 |
POST | /api/v1/jobs/quote | 작업을 생성하거나 금액을 선점하지 않고 정확한 요청의 5분 유효 견적 발급 | 견적 |
GET | /api/v1/chat/credit | 사용 가능 잔액, 선점 금액과 총잔액 조회 | 과금 |
GET | /api/v1/usage | 현재 키의 호출 수와 정산된 USD 지출을 날짜·모델별로 조회 | 과금 |
생성과 작업 API
| 메서드 | 경로 | 용도 | 가이드 |
|---|---|---|---|
GET | /api/v1/jobs | 커서 페이지 구분으로 현재 API 키의 작업 내역 조회 | 작업 |
POST | /api/v1/jobs/createTask | 비동기 생성 작업 만들기 | 작업 |
GET | /api/v1/jobs/recordInfo | 호출한 API 키로 생성된 작업 조회 | 작업 |
POST | /api/v1/jobs/retry | 실패·만료 작업에서 새 작업 생성. 과거 취소 기록도 호환 유지 | 작업 동작 |
POST | /api/v1/jobs/purge | 종료 작업 하나의 결과물과 프롬프트 폐기. 과금 기록은 유지 | 보관 |
POST | /api/v1/jobs/stream | 텍스트 모델 실행 및 SSE 답변 스트리밍 | 텍스트와 스트리밍 |
미디어 API
| 메서드 | 경로 | 용도 | 가이드 |
|---|---|---|---|
POST | /api/v1/common/upload-url | 직접 미디어 업로드 티켓 발급 | 미디어 |
POST | /api/v1/files/{fileId}/commit | 직접 업로드 검증·확정 후 작업에 사용할 spicy:// URI 반환 | 미디어 |
POST | /api/v1/files/import | 링크에서 LoRA 가중치 파일을 가져와 작업에 사용할 spicy:// URI 반환(액세스 토큰은 선택, 한 번만 사용하고 저장하지 않음) | 어댑터 가중치 |
POST | /api/v1/common/download-url | 유효 기간이 짧은 결과 다운로드 URL 발급. 완료 작업에 이미 URL이 포함되므로 선택 사항 | 미디어 |
POST | /api/v1/assets | 파일을 에셋 라이브러리에 저장(Idempotency-Key 필수) | 미디어 |
GET | /api/v1/assets | 저장한 에셋 목록 조회(favorite, collectionId, q로 필터링, sort로 정렬) | 미디어 |
GET | /api/v1/assets/usage | 에셋 라이브러리 플랜, 사용량, 한도 조회 | 미디어 |
GET | /api/v1/assets/{assetId} | 에셋 하나를 새 비공개 미리보기 링크와 함께 조회 | 미디어 |
PATCH | /api/v1/assets/{assetId} | 에셋 이름 또는 favorite 플래그 변경 | 미디어 |
DELETE | /api/v1/assets/{assetId} | 에셋 삭제 | 미디어 |
GET | /api/v1/assets/entities | 에셋 라이브러리의 캐릭터 목록 조회(읽기 전용) | 미디어 |
GET | /api/v1/assets/entities/{entityId} | 캐릭터 하나를 이미지 순서대로 조회(읽기 전용) | 미디어 |
인증과 응답 형식
공개 카탈로그를 제외한 모든 엔드포인트는 Authorization: Bearer sk-spicy-…로 API 키를 요구합니다. 호환 엔드포인트(/v1, /v1beta)는 Anthropic SDK가 보내는 x-api-key, Google GenAI SDK가 보내는 x-goog-api-key도 받습니다. URL 쿼리 문자열의 키는 허용하지 않습니다. 작업, 재시도, 폐기와 다운로드 링크는 작업을 생성한 API 키로만 접근할 수 있습니다. 인증을 참고하세요.
작업 API의 JSON 응답은 공통 {code,msg,data,request_id} 형식을 사용합니다. 호환 엔드포인트는 해당 프로토콜의 형식을 사용합니다. 작업 결과는 응답 바깥쪽 code가 아니라 data.state로 나타냅니다. 오류를 참고하세요.
엔드포인트 공통 요청 헤더
| 헤더 | 대상 | 용도 |
|---|---|---|
Authorization: Bearer … | 공개 카탈로그를 제외한 모든 엔드포인트 | API 키 |
Idempotency-Key | jobs/createTask, jobs/retry, jobs/stream, POST /v1/videos 및 /v1·/v1beta 텍스트 엔드포인트 | 네트워크 오류 후 안전하게 다시 보낼 수 있습니다. 작업 엔드포인트는 원래 작업을 반환합니다. 텍스트 엔드포인트는 중복 과금을 막지만 잃어버린 답변은 반환하지 못합니다. 멱등성 참조 |
X-Spicy-Retention | jobs/createTask, jobs/stream | 이 작업의 출력과 프롬프트 보관 기간을 초 단위로 단축합니다. 보관 참조 |
Accept-Language | 모든 엔드포인트 | 오류 메시지 언어입니다. 코드는 변경되지 않습니다. 오류 참조 |
OpenAPI 파일 활용
- 코드를 작성하지 않고 요청 테스트: 이 페이지 위의 OpenAPI 파일을 Postman, Insomnia, Bruno 같은 API 클라이언트에 가져온 뒤 Bearer 토큰에 API 키를 설정하세요. 작업을 생성하면 비용이 발생한다는 점에 유의하세요.
- 클라이언트 생성: 같은 파일을 사용하는 언어의 OpenAPI 3.1 코드 생성기에 입력하세요.
계약 변경에 대응하기
- 모델 매개변수를 영구적인 하드코딩 사본으로 보관하지 말고
/models/{model}에서inputSchema를 읽으세요. - 알 수 없는 응답 필드는 허용하되, 알 수 없는 요청 필드를 추측해 보내지는 마세요.
- 출시 전에 OpenAPI YAML을 코드 생성이나 계약 테스트에 사용하세요.
호환 엔드포인트
| 메서드 | 경로 | 프로토콜 |
|---|---|---|
GET | /v1/models | Models |
POST | /v1/chat/completions | Chat Completions |
POST | /v1/responses | Responses |
POST | /v1/messages | Messages |
POST | /v1beta/models/{model}:generateContent | Gemini generateContent |
POST | /v1beta/models/{model}:streamGenerateContent | Gemini streamGenerateContent |
POST | /v1/videos | Videos |
GET | /v1/videos/{videoId} | 영상 상태 |
GET | /v1/videos/{videoId}/content | 영상 콘텐츠 |
텍스트 엔드포인트는 텍스트와 스트리밍에서, 가격 책정은 견적과 호환성에서 설명합니다.
공식 TypeScript 패키지는 @spicyapi/sdk입니다. Python·Go를 사용하거나 의존성을 추가할 수 없는 경우 아래 참조 클라이언트를 복사해 언어 런타임만으로 엔드포인트를 호출할 수 있습니다. Python 클라이언트는 참조 파일 업로드·확정, 견적으로 가격 확인, 작업 생성과 종료까지 조회, 파일·텍스트 결과 읽기, 만료된 출력 링크 갱신, 저장 콘텐츠 폐기, webhook 서명 검증까지 전체 미디어 작업을 처리합니다. Go 클라이언트도 같은 흐름을 제공하며 호출마다 컨텍스트를 받고 errors.As로 추출할 수 있는 타입 오류를 사용합니다. TypeScript 참조 클라이언트는 작업 생성·재시도·상태 조회·제한 시간 대기를 지원합니다. Node.js의 업로드와 나머지 API에는 SDK를 사용하세요.
복사 가능한 참조 클라이언트
모델 검색, 작업 생성, 실패한 작업 재시도, 상태 조회, 모든 종료 상태, 제한된 대기, 멱등성과 오류 처리를 포함한 무의존성 예제입니다. 수락된 작업은 취소할 수 없습니다.
문서 예제이며 npm, PyPI, Go 모듈로 배포된 것이 아닙니다. 10분은 로컬 대기 한도이지 운영 SLA가 아닙니다.
