SpicyAPI 작동 방식

SpicyAPI를 처음 쓴다면 여기서 시작하세요. 이 페이지는 SpicyAPI가 하는 일을 쉬운 말로 설명하고, 나에게 맞는 이용 방법을 고르도록 돕고, 나머지 문서가 이미 알고 있다고 가정하는 몇 가지 개념을 소개합니다. 프로그래밍을 몰라도 읽을 수 있습니다.

SpicyAPI란

SpicyAPI는 여러 모델 개발사의 이미지·영상·텍스트 모델을 API 키 하나로 쓸 수 있게 해 주고, 쓴 만큼 미국 달러로 요금을 받는 서비스입니다.

SpicyAPI 없이 여러 AI 모델을 쓰려면 회사마다 계정을 만들고, 회사마다 다른 요청 형식을 익히고, 잔액도 따로따로 충전해야 합니다. SpicyAPI에서는 계정 하나, 잔액 하나면 됩니다. 모델을 고르고 프롬프트를 보내면(참조 이미지를 받는 모델이라면 이미지도 함께) 이미지나 영상, 텍스트가 돌아옵니다. 다른 모델로 바꿔도 요청을 보내는 방법과 결과를 받는 방법은 달라지지 않습니다.

• 키 하나로 여러 모델. 이미지·영상 모델은 모두 같은 방식으로 씁니다. 작업을 제출하고, 나중에 결과를 받습니다. 텍스트 모델은 OpenAI, Anthropic, Google Gemini 공식 라이브러리의 요청 형식도 그대로 받습니다.
• 쓴 만큼 달러로 결제. 가격은 모델에 따라 이미지 1장, 영상 1초, 요청 1회, 토큰 단위로 매겨집니다. 구독도 없고 크레딧이나 포인트 제도도 없습니다. 화면에 보이는 가격이 곧 잔액에서 빠져나가는 달러 금액입니다. 무료 제공량도 없으므로 첫 생성 전에 잔액을 충전해야 합니다. 자세한 내용은 과금을 보세요.
• 작업이 접수되면 예상 비용만큼이 잔액에서 예약됩니다. 성공하면 실제로 사용한 만큼만 내고, 예약된 금액을 넘는 일은 없습니다. 실패하거나 만료된 작업은 보통 예약 금액이 전액 해제됩니다. 다만 모델 페이지에 명시된 일부 콘텐츠 거부는 접수 시 견적 금액으로 과금됩니다. 최종 청구액은 settled와 cost로 확인하세요.
• 따로 켜야 할 콘텐츠 설정이 없습니다. SpicyAPI는 요청에 콘텐츠 모드 플래그를 요구하지 않으며, 요청마다 콘텐츠를 심사하지도 않습니다. 무엇이 생성되는지는 모델에 달려 있어서, 어떤 모델은 특정 요청을 거절하거나 수위를 낮춰 생성합니다. 생성한 결과를 어떻게 쓰는지에 대한 책임은 이용자에게 있습니다. 콘텐츠와 이용 책임을 보세요.

SpicyAPI는 중국 본토에서는 이용할 수 없고, 그 밖에도 이용이 제한된 지역이 몇 곳 있습니다. 같은 정책 페이지를 확인하세요.

무엇을 만들 수 있나요

카탈로그에는 이 밖에도 좀 더 특화된 영상 작업이 몇 가지 있습니다. 예를 들어 다른 클립의 움직임을 따라 인물을 움직이거나, 기존 클립을 이어 붙여 늘리는 작업입니다. 모델은 계속 추가되고 종료되므로, 지금 무엇이 있는지는 언제나 실시간 카탈로그가 기준입니다.

현재 모델을 이미지, 설명, 가격과 함께 보려면 spicyapi.ai/explore를 여세요. 같은 목록을 계정이나 키 없이 가공하지 않은 JSON으로도 받을 수 있습니다. 터미널에서 직접 보고 싶다면 다음 명령을 실행하세요.

curl "https://api.spicyapi.ai/console/v1/catalog/models?locale=en&strict=1"

긴 텍스트가 한꺼번에 출력됩니다. 그 안의 모델마다 modality(image, video, text 중 하나), tasks, 그리고 시작 가격인 price가 들어 있습니다. 이 공개 목록은 둘러보기용입니다. 키를 만든 뒤에 그 키로 실제로 호출할 수 있는 목록은 GET /api/v1/models에서 받습니다. 용어집의 카탈로그 항목도 참고하세요.

이용 방법 고르기

시작하는 길은 다섯 가지입니다. 다섯 가지 모두 같은 계정, 같은 잔액, 같은 모델, 같은 가격을 쓰므로 하나로 시작했다가 나중에 다른 방법을 더해도 됩니다.

브라우저에서 바로 써 보기

• 이런 분께 맞습니다: 무엇을 정하기 전에 모델이 어떤 결과를 내는지 먼저 보고 싶은 모든 분. 설치할 것도, 코드도 없습니다.
• 필요한 것: 웹 브라우저. 계정이 없어도 아무 모델이나 열고 입력 양식을 채워 볼 수 있습니다. 실행을 누르려면 로그인하고 잔액이 있어야 합니다.
• 비용이 드나요? 실행할 때마다 API 호출과 똑같이 과금됩니다. 실패하거나 만료된 작업은 보통 예약 금액이 전액 해제됩니다. 다만 모델 페이지에 명시된 일부 콘텐츠 거부는 접수 시 견적 금액으로 과금됩니다. 최종 청구액은 settled와 cost로 확인하세요.
• 시작하기: spicyapi.ai/explore를 열고 모델을 고른 뒤 모델 페이지의 플레이그라운드 탭을 쓰세요. 끝난 실행은 콘솔의 로그에도 나타납니다.

AI 어시스턴트에게 부탁하기

• 이런 분께 맞습니다: Claude, Cursor, VS Code, Codex, Windsurf, Gemini CLI 같은 AI 어시스턴트를 이미 쓰고 있고, 대화만으로 모델을 둘러보고 가격을 비교하고 이미지나 영상을 만들고 싶은 분. 개발자도 본격적으로 만들기 전에 탐색용으로 씁니다.
• 필요한 것: Node.js 22.13 이상, API 키, MCP를 지원하는 어시스턴트 앱. 비용이 드는 단계는 사용자에게 확인 질문을 띄울 수 있는 앱에서만 작동합니다.
• 비용이 드나요? 둘러보기, 견적 받기, 결과 조회는 무료입니다. 생성을 시작하거나 다시 시도할 때는 먼저 멈추고 가격을 보여 주며, 그 확인 질문에 어시스턴트가 대신 답할 수 없습니다.
• 시작하기: MCP 서버를 연결하면 어시스턴트가 SpicyAPI 기능을 쓸 수 있게 됩니다. Agent Skill은 AI 코딩 어시스턴트에게 SpicyAPI 연동 코드를 안전하게 짜는 법을 가르치며, MCP 서버와 함께 쓰면 잘 맞습니다.

터미널에 명령 입력하기

• 이런 분께 맞습니다: 가격을 비교하고, 내 컴퓨터에서 이미지와 영상을 만들어 파일로 저장하고, 같은 종류의 작업을 반복하거나 간단한 스크립트를 돌리고 싶은 분. 프로그래밍은 필요 없습니다.
• 필요한 것: 터미널, Node.js 22.13 이상, 그리고 SPICY_API_KEY 환경 변수에 넣어 둔 API 키.
• 비용이 드나요? 비용이 들 수 있는 명령은 spicyapi tasks create와 spicyapi tasks retry 두 가지뿐이며, 둘 다 과금 전에 먼저 확인을 받습니다.
• 시작하기: 명령줄 도구(CLI).

ComfyUI에서 노드 워크플로 만들기

• 이런 분께 맞습니다: 이미 ComfyUI로 작업하면서 내 컴퓨터의 노드 옆에 호스팅 모델을 두고 싶은 분. 이미지 모델의 결과를 영상 모델에 연결하고, 배경음악을 더하고, 채팅 모델이 프롬프트를 쓰게 할 수 있습니다.
• 필요한 것: 내 컴퓨터나 서버에 설치된 ComfyUI와 API 키. SpicyAPI의 모델은 저희 서버에서 실행되므로 GPU는 필요 없습니다.
• 비용이 드나요? 실행할 때마다 API 호출과 똑같이 과금됩니다. 모든 노드가 요금을 보여 주고, 실행 전에 견적을 받으며, 내가 정한 한도를 넘는 실행은 멈출 수 있습니다.
• 시작하기: ComfyUI 노드.

코드 작성하기

• 이런 분께 맞습니다: 내 앱, 웹사이트 백엔드, 데이터 파이프라인에 이미지·영상·텍스트 생성 기능을 넣고 싶은 분.
• 필요한 것: 서버나 내 컴퓨터에서 실행되는 코드. API 키는 절대로 웹 페이지나 모바일 앱에 넣으면 안 되기 때문입니다. 공식 SDK는 TypeScript(Node.js 22.13 이상), Python 3.11 이상, Go 1.23 이상, PHP 8.1 이상, Java 17 이상용으로 준비돼 있고, 그 밖의 언어에서는 HTTP API를 직접 호출하면 됩니다.
• 비용이 드나요? 접수된 생성은 모두 과금됩니다. 견적, 카탈로그 조회, 작업 조회는 무료입니다.
• 시작하기: Node.js라면 TypeScript SDK, 그 밖에는 Python, Go, PHP, Java SDK를 보세요. 일반 HTTP 요청이라면 curl·Node.js·Python·Go 예제가 있는 빠른 시작을, 채팅 모델이라면 텍스트와 스트리밍을, 처음부터 끝까지 따라 해 볼 완성된 예제로는 이미지→영상 튜토리얼을 보세요.

어디서나 만나게 될 개념

플레이그라운드를 써 보는 데는 아래 내용이 하나도 필요 없지만, 다른 모든 페이지는 이 개념들을 안다고 가정합니다. 개념마다 여기서는 한두 문장으로 설명하고, 자세한 내용을 담은 페이지 링크와 용어집의 쉬운 설명을 함께 달았습니다.

생성하면 일어나는 일

1. 모델을 고르고 입력값을 채웁니다.
2. 원한다면 견적을 받습니다. 정확한 가격을 무료로 알려 줍니다.
3. 제출합니다. SpicyAPI가 요청을 작업으로 접수하고, 작업 ID를 돌려주고, 예상 비용만큼을 잔액에서 예약합니다.
4. 모델이 백그라운드에서 작업합니다. 이미지는 보통 몇 초, 영상은 몇 분씩 걸리는 경우가 많습니다.
5. 작업이 끝납니다. 성공했다면 실제로 사용한 만큼만 내며, 예약된 금액을 넘지 않습니다. 실패하거나 만료된 작업은 보통 예약 금액이 전액 해제됩니다. 다만 모델 페이지에 명시된 일부 콘텐츠 거부는 접수 시 견적 금액으로 과금됩니다. 최종 청구액은 settled와 cost로 확인하세요.
6. 결과를 받습니다. SpicyAPI가 내 서버로 알려 주거나 내가 직접 물어봐서 결과를 확인한 뒤 파일을 내려받습니다. 다운로드 링크는 잠시만 유효하고 파일도 정해진 기간만 보관되므로, 남겨 둘 파일은 직접 저장하세요.

모델 ID

모든 모델에는 publisher/model/task 형태의 정확한 ID가 있습니다. 기억이나 웹 페이지에서 옮겨 적지 말고 실시간 카탈로그(GET /api/v1/models, spicyapi models list, listModels())에서 복사하세요. 모델은 추가되기도 하고, 일시 중지되거나 종료되기도 합니다. 이 문서의 코드 예제에서는 실제 ID가 들어갈 자리에 MODEL_ID_FROM_CATALOG라고 적었습니다. 모델 카탈로그와 스키마 · 용어집: 모델 ID

작업과 작업 상태

이미지와 영상 생성은 비동기로 처리됩니다. 제출과 결과 받기가 별개의 두 단계이고, 둘은 job_으로 시작하는 작업 ID로 이어집니다. 작업은 queued에서 running으로 넘어가고, 마지막에는 succeeded, failed, expired 중 하나로 끝납니다. queued나 running이 아닌 상태는 모두 최종 상태입니다. 텍스트 모델은 이와 달리 같은 연결에서 바로 답하며, 단어 단위로 흘려보내는 경우가 많습니다. 비동기 작업 · 텍스트와 스트리밍 · 용어집: 작업 상태

견적

견적은 보내려는 요청 그대로의 가격을 계산해 줍니다. 아무것도 시작하지 않고 금액을 예약하지도 않습니다. 유효 기간은 5분입니다. 견적을 붙여 제출했는데 그사이 가격이나 요청 내용이 바뀌었다면, 다른 금액으로 과금하는 대신 제출 자체가 거부됩니다. 견적과 호환성 · 용어집: 견적

멱등 키

작업 하나에 내가 직접 붙여 요청과 함께 보내는 이름표입니다. 연결이 끊겨서 24시간 안에 같은 이름표와 같은 API 키로 같은 요청을 다시 보내면, 두 번째 작업이 새로 시작되어 비용이 또 드는 대신 처음 작업을 그대로 돌려받습니다. CLI와 MCP 서버는 이 키를 알아서 만들어 주고, SDK나 일반 HTTP 요청에서는 직접 넣어야 합니다. 멱등성 · 용어집: 멱등 키

콜백

작업이 끝났는지 계속 물어보는 대신, 작업에 callBackUrl을 지정할 수 있습니다. 내 서버에 있는 공개 HTTPS 주소입니다. 작업이 끝나면 SpicyAPI가 그 주소로 결과를 보내며, 정말 SpicyAPI가 보낸 것인지 확인할 수 있도록 서명을 붙입니다. 반복해서 물어보는 방식은 폴링이라고 하며, 내 컴퓨터에서 테스트하는 동안에는 폴링으로도 충분합니다. 웹훅 · 용어집: 웹훅

결과 보관 기간

결과 다운로드 링크는 약 20분 동안 유효합니다. 작업을 다시 조회하면 새 링크를 받을 수 있습니다. 생성된 파일은 최대 약 14일, 업로드한 파일은 1일, 프롬프트 텍스트는 30일 동안 보관되며, 세 기간 모두 더 짧게 줄일 수 있고 작업 하나의 내용을 원할 때 파기할 수도 있습니다. 과금 기록은 훨씬 오래 보관됩니다. 남겨 두고 싶은 것은 모두 내려받으세요. 보관과 파기 · 용어집: 보관 기간

잔액과 지출 한도

잔액은 미리 충전해 두는 미국 달러입니다. API 키마다 직접 설정하는 일·월·누적 지출 한도도 걸 수 있습니다. 잔액으로 작업 비용을 감당할 수 없으면 오류 40201이, 한도에 닿으면 40202가 반환됩니다. 두 경우 모두 작업은 만들어지지 않고 과금도 되지 않습니다. 과금 · 인증 · 용어집: 지출 한도

처음이라면 이 순서대로

도움 받기

• 빠른 답변: 자주 묻는 질문, 용어집, 문제 해결, 오류.
• 서비스가 정상인가요? status.spicyapi.ai.
• 문의하기: 콘솔의 지원 페이지에서 대화를 시작하거나 문의 페이지를 이용하세요. request_id나 작업 ID, 그리고 UTC 기준 시각을 함께 적어 주세요. API 키는 절대 보내지 마세요.

다음 단계