용어집

SpicyAPI는 API 제품이라서 이 문서에도 기술 용어가 많이 나옵니다. 이 페이지는 그 용어들을 하나씩 쉬운 말로 설명하며, 영문 표기의 알파벳순으로 정렬했습니다. 항목마다 세 부분으로 나뉩니다. 그 용어가 일반적으로 뜻하는 것, SpicyAPI에서 뜻하는 것, 그리고 자세한 내용이 있는 페이지입니다.

다른 페이지에서도 이곳의 항목으로 바로 링크하므로, 읽다가 모르는 단어가 나오면 대부분 여기에 있습니다. 전체 그림부터 보고 싶다면 SpicyAPI 작동 방식에서 시작하세요.

Agent Skill

AI 코딩 어시스턴트가 작업을 시작하기 전에 읽는 설명서 묶음입니다. 새로 온 동료에게 건네는 업무 매뉴얼 같은 것으로, 프로그램이 들어 있지 않아서 스스로는 아무 일도 하지 않습니다.

SpicyAPI에서는: @spicyapi/skill로 배포되는 공식 Skill이 Claude Code, Codex, Cursor 같은 어시스턴트에게 SpicyAPI를 올바르게 쓰는 법을 가르칩니다. 추측하지 말고 실시간 카탈로그를 읽을 것, 비용이 드는 작업 전에는 가격을 먼저 보여 줄 것, 멱등 키를 재사용할 것, API 키를 코드에 절대 붙여 넣지 않을 것 등입니다. npx skills add spicyapi-ai/spicy-skill로 설치하며, MCP 서버와 함께 쓰면 잘 맞습니다.

더 보기: Agent Skill

API

Application Programming Interface(애플리케이션 프로그래밍 인터페이스)의 줄임말입니다. 한 프로그램이 다른 프로그램에 보낼 수 있는 정해진 요청들과, 그에 대해 돌아오는 응답의 약속입니다. 웹사이트가 사람이 클릭하도록 만든 것이라면, API는 프로그램이 호출하도록 만든 것입니다.

SpicyAPI에서는: 모든 도구가 API를 통해 모델에 닿습니다. 플레이그라운드, CLI, MCP 서버, SDK는 모두 내가 직접 짠 코드가 보낼 수 있는 것과 똑같은 종류의 요청을 api.spicyapi.ai로 보냅니다.

더 보기: OpenAPI와 엔드포인트 목록

API 키 (API key)

요청이 나에게서 왔다는 것을 증명하는 비밀 문자열입니다. 프로그램이 쓰는 비밀번호라고 생각하고 다루세요.

SpicyAPI에서는: 키는 sk-spicy-로 시작하며, 콘솔의 API 키 페이지에서 만듭니다. 키는 한 번만 표시되므로 잃어버렸다면 새로 만들어야 합니다. 요청할 때마다 키를 Authorization: Bearer 헤더에 담아 보냅니다. 키는 내 컴퓨터나 서버에만 두고, 웹 페이지·모바일 앱·공개 저장소·스크린샷·채팅에는 절대 넣지 마세요. 키마다 지출 한도, 허용할 모델 목록, 허용할 IP 주소 목록을 따로 정할 수 있습니다.

더 보기: 인증 · 계정 설정

에셋과 출력 URL (Asset and output URL)

에셋은 작업이 만들어 낸 파일 하나, 예를 들어 이미지나 영상 한 개를 말합니다. 출력 URL은 그 파일을 내려받는 웹 주소입니다.

SpicyAPI에서는: 끝난 작업은 만들어진 파일을 output.assets[]에 나열합니다. 파일마다 API 키 없이 바로 내려받을 수 있는 url과 함께 expiresAt, mime(파일 형식), 크기 정보가 들어 있습니다. 링크는 약 20분 동안 유효하며, 작업을 다시 조회하면 새 링크를 받습니다. 파일 자체는 최대 약 14일 동안 보관되므로 필요한 것은 직접 복사해 두세요. pending: true로 표시된 에셋은 아직 저장 중이니 몇 초 뒤에 다시 시도하고, unavailable: true로 표시된 에셋은 영구히 사라진 것입니다.

더 보기: 비동기 작업 · 미디어

잔액 (Balance)

계정에 들어 있어 생성 비용을 치르는 돈입니다.

SpicyAPI에서는: 미국 달러로 미리 충전해 두는 잔액이며, 크레딧이나 포인트가 아닙니다. 충전한 금액은 만료되지 않으며, 프로모션 잔액에는 각각 만료일이 있습니다. 콘솔의 결제 페이지에서 충전합니다. GET /api/v1/chat/credit은 "128.42"처럼 텍스트로 된 금액 세 가지를 돌려줍니다. available(자유롭게 쓸 수 있는 금액), held(아직 실행 중인 작업을 위해 예약된 금액), total(합계)입니다. 일부 계정에는 프로모션 지원금이나 승인된 후불 한도가 있으며, 이는 별도 내역으로 표시됩니다. 무료 제공량은 없어서 새 계정은 0에서 시작합니다.

더 보기: 과금 · 계정 설정

베이스 URL (Base URL)

API가 쓰는 모든 주소에 공통으로 붙는 고정된 앞부분입니다. 코드나 도구 설정에 한 번만 적어 두면, 요청마다 그 뒤에 각자의 경로가 붙습니다.

SpicyAPI에서는: 두 가지가 있습니다.

Google Gemini 형식의 요청은 https://api.spicyapi.ai/v1beta로 보냅니다. 공식 Anthropic 라이브러리와 Google GenAI 라이브러리는 버전 부분을 스스로 붙이므로, 이 둘에는 https://api.spicyapi.ai까지만 설정합니다.

더 보기: 빠른 시작 · 텍스트와 스트리밍

콜백 (Callback)

웹훅의 다른 이름입니다. SpicyAPI에서는 작업을 만들 때 callBackUrl 필드에 주소를 넣습니다.

카탈로그 (Catalog)

제공하는 모델의 목록으로, 모델마다 가격과 받을 수 있는 입력값이 함께 적혀 있습니다.

SpicyAPI에서는: 같은 목록이 두 가지 형태로 있습니다.

• 공개 카탈로그는 계정도 키도 필요 없습니다. spicyapi.ai/explore에 보이는 목록이자 GET /console/v1/catalog/models가 돌려주는 목록입니다. 둘러보고 비교하는 데 쓰세요.
• 인증 카탈로그, 즉 API 키를 붙여 호출하는 GET /api/v1/models는 내 키가 지금 호출할 수 있는 모델과 내 계정에 적용되는 가격을 알려 주는 유일하게 믿을 수 있는 출처입니다. 비용이 드는 작업 전에는 enabled와 available이 모두 true인 항목을 고르세요.

CLI 명령 spicyapi models list, SDK 메서드 listModels(), MCP 도구 spicyapi_models_list는 모두 인증 카탈로그를 읽습니다.

더 보기: 모델 카탈로그와 스키마

CLI

Command-Line Interface(명령줄 인터페이스)의 줄임말입니다. 버튼을 누르는 대신 터미널에 명령을 입력해서 쓰는 프로그램입니다.

SpicyAPI에서는: @spicyapi/cli로 배포되는 spicyapi 명령으로, 코드를 짜지 않고도 모델 목록 보기, 가격 확인, 이미지·영상 작업 만들기, 작업 완료 기다리기, 결과 내려받기를 할 수 있습니다. 비용이 드는 명령은 tasks create와 tasks retry뿐이며, 둘 다 먼저 확인을 받습니다. Node.js 22.13 이상이 필요하고, 설치하지 않고 npx @spicyapi/cli로 실행할 수도 있습니다.

더 보기: 명령줄 도구(CLI)

엔드포인트 (Endpoint)

API가 받아 주는 요청 하나하나를 말합니다. HTTP 메서드(읽을 때 쓰는 GET, 보낼 때 쓰는 POST 등)와 경로로 이름을 붙입니다.

SpicyAPI에서는: 예를 들어 POST /api/v1/jobs/createTask는 생성을 시작하고, GET /api/v1/jobs/recordInfo는 작업을 조회합니다. 전체 주소는 베이스 URL 뒤에 경로를 붙인 것입니다.

더 보기: OpenAPI와 엔드포인트 목록

응답 외피 (Envelope)

모든 응답을 감싸는 고정된 겉 형식입니다. 덕분에 프로그램은 어디를 읽어야 하는지 언제나 알 수 있습니다.

SpicyAPI에서는: 네이티브 API(/api/v1 아래)의 응답은 다음과 같은 모양입니다.

{ "code": 200, "msg": "success", "data": {}, "request_id": "req_01k3m8x9q2z4v7n5p6r8s0t1w2" }

code는 업무 코드(200이 성공), msg는 사람이 읽는 메시지, data는 응답 내용이며 실패하면 아예 빠집니다. request_id는 이 요청을 식별하는 값입니다. OpenAI·Anthropic·Gemini 호환 엔드포인트는 이 외피 대신 각 프로토콜의 형식을 따릅니다.

더 보기: 오류

환경 변수 (Environment variable)

터미널이 자신이 실행하는 모든 프로그램에 넘겨주는, 이름이 붙은 값입니다. 비밀 키 같은 설정값을 파일이나 명령에 직접 적지 않고도 프로그램이 읽을 수 있게 해 줍니다.

SpicyAPI에서는: SDK, CLI, MCP 서버와 이 문서의 코드 예제는 모두 SPICY_API_KEY라는 환경 변수에서 API 키를 읽습니다. 지금 열려 있는 터미널 창에만 설정하려면 다음과 같이 입력합니다.

export SPICY_API_KEY="sk-spicy-paste-your-key-here"

이 설정은 창을 닫으면 사라집니다. 영구적으로 설정하는 방법과 키 전체를 출력하지 않고 확인하는 방법은 CLI 페이지에 나와 있습니다.

더 보기: CLI: 시작하기 전에 · 계정 설정

오류 코드 (Error code)

무엇이 잘못됐는지 알려 주는 짧고 고정된 값입니다. 프로그램은 메시지 문장을 읽지 않고도 이 값으로 대응할 수 있습니다.

SpicyAPI에서는: 두 종류가 있습니다.

• 응답 외피 안의 code 값은 요청 자체에 대한 결과입니다. 200은 성공이고, 그 밖에 400(잘못된 요청), 401(키 문제), 40201(잔액 부족), 40202(지출 한도 도달), 429(요청이 너무 많음) 등이 있습니다. 함께 전송되는 HTTP 상태 코드보다 더 구체적인 업무 코드입니다.
• errorCode 값은 접수된 뒤 실패한 작업에 붙습니다. invalid_request, unsupported_combination, content_rejected, rate_limited, upstream_unavailable, generation_failed, timeout, invalid_asset, upstream_failed의 아홉 가지 중 하나입니다.

짝을 이루는 메시지인 msg와 errorMessage는 사람이 읽기 위한 것입니다. 문구는 바뀔 수 있고, 내가 고른 언어로 반환될 수도 있습니다. 프로그램에서는 코드로만 분기하세요.

더 보기: 오류

예약, 정산, 해제 (Hold, settle and release)

작업 비용을 치르는 세 단계입니다. 예약은 따로 떼어 두었지만 아직 쓰지는 않은 돈으로, 호텔이 체크인할 때 카드에 금액을 가승인해 두는 것과 비슷합니다.

SpicyAPI에서는:

• 예약: 작업이 접수되면 예상 비용(estimatedCost)만큼이 잔액에서 따로 떼어져 held로 표시됩니다. 아직 청구된 것이 아니며, 이 작업에 들 수 있는 최대 금액이기도 합니다.
• 정산: 작업이 성공하면 실제로 사용한 만큼만 청구되며, 예약된 금액을 넘지 않습니다. 남은 금액은 사용 가능 잔액으로 돌아갑니다. 작업에 settled: true가 표시되면 cost의 금액이 최종 금액이라는 뜻입니다.
• 해제: 실패하거나 만료된 작업은 보통 예약 금액이 전액 해제됩니다. 다만 모델 페이지에 명시된 일부 콘텐츠 거부는 접수 시 견적 금액으로 과금됩니다. 최종 청구액은 settled와 cost로 확인하세요.

더 보기: 과금

HTTP 상태 코드 (HTTP status)

모든 웹 응답 맨 앞에 붙는 세 자리 숫자로, 요청이 대략 어떻게 처리됐는지 알려 줍니다. 2xx는 성공, 4xx는 요청에 뭔가 문제가 있다는 뜻, 5xx는 서버 쪽에 문제가 생겼다는 뜻입니다.

SpicyAPI에서는: 작업을 만들면 202 Accepted가 돌아옵니다. 작업이 끝났다는 뜻이 아니라 접수됐다는 뜻입니다. 네이티브 응답에는 이보다 구체적인 업무 코드 code도 함께 들어 있습니다. 예를 들어 잔액이 부족하면 HTTP 402에 code는 40201입니다. 코드에서는 둘 중 하나만 골라 분기하고, 정한 쪽을 계속 쓰세요.

더 보기: 오류

멱등 키 (Idempotency key)

작업 하나에 내가 직접 지어 붙이는 이름표로, 같은 요청을 두 번 보내도 일은 한 번만 처리되게 해 줍니다. 멱등(idempotent)이란 같은 동작을 다시 해도 결과가 더 달라지지 않는다는 뜻입니다.

SpicyAPI에서는: 작업을 만들거나 다시 시도할 때 Idempotency-Key 헤더에 넣어 보냅니다. 예를 들면 order-8814-render-1입니다. 연결이 끊겨서 작업이 시작됐는지 확실하지 않다면 24시간 안에 같은 요청을 같은 키와 같은 API 키로 다시 보내세요. 원래 작업을 돌려받고, 두 번 과금되지 않습니다. 새로운 일에는 새 키를 쓰세요. 같은 키를 다른 요청에 다시 쓰면 409로 거부됩니다. 키는 최대 128자까지 쓸 수 있습니다.

더 보기: 멱등성

입력 스키마 (Input schema)

요청에 어떤 필드를 넣을 수 있는지, 각 필드가 어떤 타입인지, 어떤 값이 허용되는지를 기계가 읽을 수 있게 적어 둔 설명입니다.

SpicyAPI에서는: 모델마다 JSON Schema로 작성된 고유한 inputSchema가 있습니다. input에 넣을 수 있는 prompt, image_url, duration_seconds 같은 필드와 각각의 제한, 기본값이 적혀 있습니다. 서버는 모든 요청을 이 스키마로 검사하며, 모르는 필드가 하나만 있어도 400 오류가 됩니다. 플레이그라운드는 같은 스키마로 입력 양식을 만들고, 카탈로그의 examples는 이미 이 검사를 통과한 완전한 입력값입니다.

더 보기: 모델 카탈로그와 스키마 · Spicy Schema

JSON

구조가 있는 데이터를 담는 텍스트 형식으로, 중괄호 안에 이름과 값을 나열합니다. 모든 프로그래밍 언어가 읽을 수 있어서 거의 모든 API가 이 형식을 씁니다.

SpicyAPI에서는: 요청과 응답이 모두 JSON입니다. 가장 간단한 작업 요청은 다음과 같습니다.

{ "model": "MODEL_ID_FROM_CATALOG", "input": { "prompt": "A paper lantern on a rainy street at night" } }

MODEL_ID_FROM_CATALOG 자리에는 실시간 카탈로그에서 가져온 실제 모델 ID가 들어갑니다. 금액은 언제나 "0.008"처럼 텍스트로 주고받으므로, 어떤 금액도 실수로 반올림되지 않습니다.

더 보기: 빠른 시작

MCP

Model Context Protocol의 줄임말입니다. AI 어시스턴트가 MCP 서버라는 작은 프로그램에서 도구라고 부르는 추가 기능을 불러와 쓸 수 있게 하는 공개 표준입니다.

SpicyAPI에서는: 공식 서버 @spicyapi/mcp는 내 컴퓨터에서 실행되며, Claude, Cursor, VS Code, Codex 같은 어시스턴트에게 모델 둘러보기, 견적 받기, 작업 만들기, 파일 업로드, 결과 가져오기 같은 SpicyAPI 도구 15개를 제공합니다. 작업을 시작하거나, 다시 시도하거나, 파기할 때는 멈추고 사용자 본인에게 확인을 요청하며, 가격이 있는 경우 가격도 보여 줍니다. 어시스턴트가 대신 답할 수 없습니다. Node.js 22.13 이상이 필요합니다.

더 보기: MCP 서버

모달리티 (Modality)

모델이 다루는 미디어의 종류입니다.

SpicyAPI에서는: 카탈로그 항목마다 image, video, text 같은 modality와 text-to-image, image-to-video 같은 tasks 목록이 있습니다. 예를 들어 GET /api/v1/models?modality=video&task=image-to-video처럼 이 값들로 카탈로그를 걸러 볼 수 있습니다.

더 보기: 모델 카탈로그와 스키마

모델 ID (Model ID)

모델을 고를 때 보내는 정확한 이름입니다.

SpicyAPI에서는: ID는 publisher/model/task 형태입니다. 누가 만든 모델인지, 어떤 모델과 버전인지, 그 엔드포인트가 무슨 일을 하는지를 나타냅니다. 이미지 편집 엔드포인트는 edit으로 끝납니다. 모델은 추가되고, 일시 중지되고, 종료되므로 ID는 기억이나 웹 페이지에서 옮기지 말고 언제나 실시간 카탈로그(GET /api/v1/models, spicyapi models list, listModels())에서 복사하세요. 이 문서의 예제에서는 실제 ID가 들어갈 자리에 MODEL_ID_FROM_CATALOG라고 적었으며, 이 자리표시자를 그대로 보내면 실패합니다.

더 보기: 모델 카탈로그와 스키마

Node.js

웹 브라우저 밖에서 JavaScript를 실행해 주는 무료 프로그램입니다. JavaScript로 만든 개발 도구가 많아서, 그런 도구를 쓰려면 Node.js를 설치해야 합니다.

SpicyAPI에서는: SDK, CLI, MCP 서버에는 Node.js 22.13 이상이 필요하고, Skill이 쓰는 설치 프로그램은 22.20 이상을 요구합니다. nodejs.org에서 LTS 버전을 설치한 뒤 터미널에서 node --version으로 확인하세요. 플레이그라운드만 쓰거나 다른 언어로 API를 호출한다면 Node.js는 필요 없습니다.

더 보기: CLI: 시작하기 전에

npm과 npx (npm and npx)

npm은 Node.js와 함께 설치되는 패키지 관리자로, JavaScript 패키지를 내려받아 설치합니다. 함께 딸려 오는 npx는 패키지를 영구히 설치하지 않고 바로 실행해 줍니다.

SpicyAPI에서는: Node.js용 도구 네 가지가 모두 npm 패키지입니다. @spicyapi/sdk, @spicyapi/cli, @spicyapi/mcp, @spicyapi/skill입니다. 예를 들어 npm install @spicyapi/sdk는 프로젝트에 TypeScript SDK를 추가하고, npx @spicyapi/cli status는 CLI를 설치하지 않고 한 번 실행합니다. Python, Go, PHP, Java SDK는 대신 각자의 생태계 도구로 설치합니다. SDK별 페이지를 보세요.

더 보기: TypeScript SDK · 명령줄 도구(CLI)

OpenAI 호환 (OpenAI-compatible)

OpenAI API와 같은 형식의 요청을 받는다는 뜻입니다. 그래서 OpenAI용으로 만든 소프트웨어를 주소와 키만 바꿔서 그대로 쓸 수 있습니다.

SpicyAPI에서는: 텍스트 모델은 OpenAI 형식의 POST /v1/chat/completions와 POST /v1/responses, Anthropic 형식의 POST /v1/messages, Google Gemini 형식의 /v1beta/models/…로 호출할 수 있으며, 모두 같은 API 키를 씁니다. 공식 openai 라이브러리는 https://api.spicyapi.ai/v1을 가리키도록 설정하세요. 어떤 텍스트 모델이든 이 형식들 중 어느 것으로나 호출할 수 있습니다. 이 엔드포인트들은 요청이 접수된 시점의 가격으로 과금하고 견적을 받지 않으므로, 키에 지출 한도를 설정해 두세요.

더 보기: 텍스트와 스트리밍

플레이그라운드 (Playground)

웹사이트에 있는 입력 양식으로, 코드를 짜지 않고 필드를 채우고 버튼을 눌러 모델을 써 볼 수 있습니다.

SpicyAPI에서는: spicyapi.ai의 모든 모델 페이지에 플레이그라운드 탭이 있습니다. 계정이 없어도 양식을 채우고 그 양식이 만드는 요청을 볼 수 있지만, 실행하려면 로그인하고 잔액이 있어야 합니다. 실행할 때마다 예상 비용을 먼저 보여 주고, API 호출과 똑같이 과금되며, 콘솔의 로그에 남습니다.

더 보기: SpicyAPI 작동 방식

폴링 (Polling)

알려 주기를 기다리지 않고, 일이 끝났는지 서버에 계속 반복해서 물어보는 방식입니다.

SpicyAPI에서는: GET /api/v1/jobs/recordInfo?taskId=…로 작업 상태가 더 이상 queued나 running이 아닐 때까지 조회합니다. 첫 조회 전에 23초 기다리고, 기다리는 시간을 매번 약 1.5배씩 늘려 1015초까지 늘리며, 직접 정한 마감 시각이 되면 기다리기를 그만두세요. 기다리기를 그만둬도 작업은 멈추지 않습니다. 폴링도 레이트 제한에 포함되므로, 운영 환경에서는 웹훅을 우선 쓰세요.

더 보기: 비동기 작업

파기 (Purge)

저장된 내용이 만료되기를 기다리지 않고, 요청해서 영구히 지우는 것입니다.

SpicyAPI에서는: POST /api/v1/jobs/purge(또는 콘솔 로그의 결과 폐기, spicyapi tasks purge, purgeTask())는 끝난 작업이 만든 파일, 그 결과, 입력에 들어 있던 프롬프트 텍스트를 지웁니다. 금액, 모델, 상태, 타임스탬프, request_id 같은 과금 기록은 남습니다. 파기는 취소가 아니며 환불도 되지 않고, 되돌릴 수도 없습니다. 끝난 작업에만 쓸 수 있습니다.

더 보기: 보관과 파기

견적 (Quote)

요청 하나에 대해 미리 계산해 둔 가격입니다.

SpicyAPI에서는: POST /api/v1/jobs/quote에 제출할 때와 똑같은 본문을 보내면 estimatedCost, maxCharge, expiresAt을 돌려줍니다. 작업을 만들지도, 금액을 예약하지도 않습니다. 비용이 들지 않고 5분 동안 유효합니다. 돌려받은 quoteId와 expectedCost를 붙여 제출했는데 요청이나 가격이 바뀌었다면, 다른 금액으로 과금하는 대신 40901로 제출을 거부합니다. CLI와 MCP 서버는 작업을 만들기 전에 자동으로 견적을 받습니다.

더 보기: 견적과 호환성

레이트 제한 (Rate limit)

일정 시간 동안 보낼 수 있는 요청 수의 상한입니다. 폭주하는 프로그램 하나가 서비스 전체를 짓누르지 못하게 막습니다.

SpicyAPI에서는: 네이티브 API는 기본적으로 계정마다 10초에 요청 1,000건까지 허용합니다. 읽기와 쓰기는 이 한도를 각각 따로 가지며, 두 한도 모두 계정의 모든 키가 함께 씁니다. 폴링은 읽기로 세므로 폴링을 많이 해도 작업 제출이 막히지 않습니다. 넘으면 429와 함께 몇 초 기다려야 하는지 알려 주는 Retry-After 헤더가 돌아옵니다. 세는 대상은 작업이 아니라 요청이므로, 이미 실행 중인 작업은 이 한도를 쓰지 않습니다.

더 보기: 레이트 제한

request_id

서버가 요청 하나하나에 붙이는 식별자로, 나중에 로그에서 그 요청을 다시 찾을 수 있게 해 줍니다.

SpicyAPI에서는: 모든 네이티브 응답에는 성공이든 실패든 request_id(예: req_01k3…)가 들어 있고, X-Request-Id 헤더로도 전송됩니다. 내 로그에 남겨 두고, 지원팀에 문의할 때 함께 알려 주세요. 버전 2 웹훅에서는 request_id가 그 전송 자체를 식별하며(whd_…), 전송을 다시 시도해도 바뀌지 않습니다.

더 보기: 오류 · 웹훅

보관 기간 (Retention)

저장된 데이터가 삭제되기 전까지 보관되는 기간입니다.

SpicyAPI에서는:

생성된 파일, 업로드한 파일, 프롬프트 텍스트의 보관 기간은 콘솔의 데이터 보호 페이지에서, 또는 작업 하나에 대해 X-Spicy-Retention 헤더로 더 짧게 줄일 수 있고, 파기로 언제든 내용을 지울 수 있습니다. 어떤 설정으로도 기간을 늘릴 수는 없습니다.

더 보기: 보관과 파기

SDK

Software Development Kit(소프트웨어 개발 키트)의 줄임말입니다. 내 프로그램에 추가해 쓰는 완성된 코드 라이브러리로, 요청을 하나하나 직접 만들지 않아도 되게 해 줍니다.

SpicyAPI에서는: 공식 SDK가 다섯 개 있습니다. Node.js용 TypeScript·JavaScript 라이브러리인 @spicyapi/sdk와, Python·Go·PHP·Java용으로 각각 하나씩입니다. 모두 키 처리, 작업 대기, 재시도, 업로드, 웹훅 검증을 맡아 주므로 호출 두어 번으로 작업 제출부터 결과까지 처리할 수 있습니다. 다섯 개 모두 서버에서만 실행되며 브라우저나 모바일 앱에서는 쓸 수 없고, 어느 것도 채팅 모델은 다루지 않습니다.

더 보기: TypeScript SDK · Python SDK · Go SDK · PHP SDK · Java SDK

서명 (Signature, HMAC)

메시지와 공유된 비밀 값으로 계산한 코드로, 받는 쪽이 메시지가 진짜인지, 도중에 바뀌지 않았는지 확인할 수 있게 해 줍니다. HMAC은 이런 코드를 계산하는 표준 방법입니다.

SpicyAPI에서는: 모든 웹훅 전송에는 X-Webhook-Signature 헤더가 붙습니다. 작업 ID, 전송 시각, 그리고 본문 그대로의 다이제스트를 웹훅 서명 키로 HMAC-SHA256 계산한 값입니다. 서명 키는 콘솔의 웹훅 페이지에서 생성하거나 교체하며, 그 순간에만 표시됩니다. 복사해 두지 않았다면 그 페이지에서 교체하세요. 전송 내용을 믿기 전에 SDK의 verifyWebhook이나 spicyapi webhooks verify로 서명을 확인하고, 타임스탬프가 현재 시각과 5분 넘게 차이 나는 전송은 거부하세요.

더 보기: 웹훅

지출 한도 (Spend cap)

미리 정해 두는 지출 상한입니다. 실수를 하거나 키가 유출돼도 잔액 전체가 사라지지 않게 막아 줍니다.

SpicyAPI에서는: API 키마다 미국 달러 기준으로 일, 월, 누적 한도를 직접 걸 수 있고, 새 키에는 추가하기 전까지 한도가 없습니다. 팀은 일·월 예산을 추가로 둘 수 있고, 플랫폼에도 자체 일 한도가 있습니다. 이 중 어느 하나라도 넘게 될 작업은 시작 전에 40202로 거부되며, 아무것도 과금되지 않습니다. 일 한도는 UTC 00:00에, 월 한도는 매월 1일에 초기화되고, 누적 한도는 초기화되지 않습니다. 0을 입력하면 그 단계에는 한도가 없다는 뜻입니다.

더 보기: 과금 · 인증

스트리밍 (Streaming, SSE)

답변을 끝까지 다 만든 뒤 한꺼번에 보내지 않고, 열린 연결 하나로 만들어지는 대로 조금씩 보내는 방식입니다. SSE(Server-Sent Events)는 이를 위한 웹의 일반적인 형식입니다.

SpicyAPI에서는: 텍스트 모델은 호환 엔드포인트(예: /v1/chat/completions에 stream: true)나 네이티브 POST /api/v1/jobs/stream을 통해 답변을 단어 단위로 흘려보낼 수 있습니다. 스트림이 끝났음을 알리는 방식은 프로토콜마다 다릅니다. 연결을 일찍 끊으면 텍스트를 더 받지 못할 뿐 모델은 멈추지 않으며, 사용량은 그대로 과금됩니다. 스트리밍된 텍스트는 저장되지 않으므로 나중에 다시 가져올 수 없습니다.

더 보기: 텍스트와 스트리밍

작업 (Task)

백그라운드에서 실행되는 일의 단위입니다. 맡겨 두고, 결과는 나중에 받습니다.

SpicyAPI에서는: 이미지나 영상을 생성하는 일은 모두 작업입니다. POST /api/v1/jobs/createTask가 작업을 접수하고 job_으로 시작하는 작업 ID를 돌려주면, 작업을 폴링하거나 끝났을 때 웹훅을 받습니다. API로는 작업을 만든 같은 API 키로만 그 작업을 조회할 수 있고, 콘솔의 로그 페이지에는 계정의 모든 작업이 표시됩니다. 접수된 작업은 취소할 수 없습니다.

더 보기: 비동기 작업 · 작업 확정과 재시도

작업 상태 (Task state)

작업이 지금 어느 단계에 있는지를 나타냅니다.

SpicyAPI에서는:

예전 기록에는 canceled가 보일 수도 있지만, 새 작업이 이 상태가 되는 일은 없습니다. queued나 running이 아닌 상태는 모두 종료 상태로 취급하세요.

더 보기: 비동기 작업

터미널 (Terminal)

명령을 입력하고 Enter 키를 눌러 실행하는 텍스트 창입니다. macOS에서는 터미널 앱, Windows에서는 PowerShell을 쓰고, 대부분의 Linux 데스크톱에서는 Ctrl + Alt + T로 엽니다. 영어 문서에서 같은 단어(terminal)를 쓰는 종료 상태(terminal state)와는 전혀 다른 개념입니다.

SpicyAPI에서는: CLI를 실행할 때, MCP 서버나 Skill 같은 Node.js 도구를 설치할 때, 이 문서의 curl 예제를 실행해 볼 때 터미널을 씁니다.

더 보기: CLI: 시작하기 전에

종료 상태 (Terminal state)

최종 상태를 말합니다. 작업이 한 번 이 상태가 되면 다시는 바뀌지 않습니다.

SpicyAPI에서는: queued나 running이 아닌 작업 상태는 모두 종료 상태입니다. succeeded, failed, expired, 그리고 예전 기록의 canceled입니다. 종료 상태를 하나하나 나열해 비교하지 말고 "queued도 아니고 running도 아닌지"를 확인하세요. 그래야 새로운 상태가 추가돼도 코드가 계속 작동합니다. 웹훅은 작업이 종료 상태가 되었을 때만 전송됩니다. 파기는 끝난 작업에만 할 수 있고, 다시 시도는 failed나 expired 작업에만 할 수 있습니다.

더 보기: 비동기 작업

업로드 (Upload)

내 컴퓨터에 있는 파일을 서버로 보내서 그곳에서 쓸 수 있게 하는 것입니다.

SpicyAPI에서는: 이미지·영상·오디오를 입력으로 받는 모델에는 세 가지 방법으로 파일을 넘길 수 있습니다. 파일의 공개 HTTPS 링크, 요청 안에 data URI로 넣은 작은 이미지(최대 1 MiB), 또는 업로드한 파일입니다. 업로드는 세 단계입니다. 티켓을 요청하고(POST /api/v1/common/upload-url), 티켓에 적힌 주소로 파일을 보낸 다음, 확정합니다(POST /api/v1/files/{fileId}/commit). 확정하면 모델의 입력 필드에 넣을 spicy:// 주소가 돌아오며, 이 주소는 1일 동안 쓸 수 있습니다. 이미지는 최대 10 MiB, 오디오와 영상은 최대 90 MiB에 600초까지입니다. SDK의 uploadFile(), spicyapi files upload, MCP 서버는 세 단계를 모두 알아서 처리합니다.

더 보기: 미디어

웹훅 (Webhook)

무슨 일이 생기면 다른 서비스가 호출해 주는 내 서버의 주소입니다. 덕분에 계속 물어보지 않아도 됩니다. 콜백이라고도 합니다.

SpicyAPI에서는: 작업을 만들 때 callBackUrl에 공개 HTTPS 주소를 넣습니다. 작업이 종료 상태가 되면 SpicyAPI가 그 주소로 POST 요청을 보내며, 내용은 recordInfo가 돌려주는 것과 같고 웹훅 서명 키로 서명되어 있습니다. 15초 안에 아무 2xx 상태 코드로든 응답하세요. 그렇지 않으면 약 9시간에 걸쳐 최대 8번까지 전송을 다시 시도하며, 콘솔의 웹훅 페이지에서 직접 다시 보낼 수도 있습니다. 작업이 시작되기만 했을 때는 알림이 없습니다. http://localhost:3000 같은 로컬 주소로는 웹훅을 받을 수 없으므로, 내 컴퓨터에서 개발하는 동안에는 폴링을 쓰세요.

더 보기: 웹훅

워크스페이스와 팀 (Workspace and team)

여러 사람이 한 계정 아래에서 같은 키, 작업, 예산을 함께 쓰는 공유 공간입니다.

SpicyAPI에서는: 팀 워크스페이스의 멤버에게는 owner, admin, developer, billing, readonly 중 하나의 역할이 있습니다. 모든 멤버가 작업 요약과 사용량을 볼 수 있고, owner, admin, developer는 작업의 입력과 결과도 볼 수 있습니다. 팀의 새 작업 비용은 소유자 계정이 내며, 멤버는 소유자 개인의 잔액이나 결제 내역을 볼 수 없습니다. 팀은 일·월 예산을 설정할 수 있습니다.

더 보기: 콘솔과 팀