명령줄 도구(CLI)

CLI란

spicyapi는 터미널에서 실행하는 작은 프로그램입니다. 터미널은 버튼을 누르는 대신 명령을 입력하는 창입니다. 명령 하나가 한 가지 일을 합니다. 내 계정으로 쓸 수 있는 모델을 나열하고, 생성 한 번에 얼마가 드는지 알려 주고, 이미지나 영상 생성을 시작하고, 끝날 때까지 기다렸다가 결과를 내려받을 링크를 건네줍니다.

코드는 한 줄도 쓰지 않습니다. 명령을 입력하고 Enter 키를 누른 다음, 돌아온 답을 읽으면 됩니다.

이럴 때 잘 맞습니다.

• 누군가 연동 코드를 짜기 전에 여러 모델을 써 보고 가격을 비교하고 싶을 때
• 내 컴퓨터에서 이미지나 영상을 생성하고 파일로 저장하고 싶을 때
• 같은 종류의 생성을 매번 웹 페이지를 클릭하지 않고 반복하고 싶을 때
• 무언가를 만들기 전에 모델의 정확한 설정을 확인하고 싶을 때

CLI가 다루는 것은 이미지와 영상 생성입니다. 텍스트·채팅 모델은 텍스트와 스트리밍에서 설명하는 채팅 호환 엔드포인트로 호출합니다.

공식 도구는 이 밖에도 세 가지가 더 있습니다. 명령을 직접 입력하고 싶다면 CLI를 고르세요.

다른 언어로 작성하고 계신가요? Python, Go, PHP, Java용 공식 SDK도 있습니다.

할 수 있는 일

위 명령에서 <task-id>처럼 꺾쇠괄호로 감싼 단어는 "여기에 내 값을 넣으세요"라는 뜻입니다. 넣을 때 꺾쇠괄호는 빼세요.

시작하기 전에

준비물은 네 가지입니다. 터미널, Node.js, API 키, 그리고 CLI를 실행할 방법입니다. 처음이라면 10분 정도 걸립니다.

node -v

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

nano ~/.zshrc

echo "${SPICY_API_KEY:0:9}"

npx @spicyapi/cli status

첫 결과 받기

이미지 한 장을 생성하고 내려받는 과정을 따라가 봅니다. 단계마다 명령, 대략 어떤 화면이 나오는지, 방금 무슨 일이 일어났는지를 보여 줍니다. 숫자, ID, 시각은 사람마다 다르게 나옵니다.

spicyapi status

SpicyAPI is reachable — api.spicyapi.ai answered in 523 ms.

spicyapi balance

available: 12.34
held: 0.06
total: 12.40

spicyapi models list --modality image --json

{
  "total": 1,
  "items": [
    {
      "model": "MODEL_ID_FROM_CATALOG",
      "displayName": "Example image model",
      "modality": "image",
      "tasks": ["text-to-image"],
      "enabled": true,
      "available": true,
      "pricing": [
        { "variant": "", "unit": "per_image", "price": "0.03", "currency": "USD" }
      ]
    }
  ]
}

spicyapi models get MODEL_ID_FROM_CATALOG --json

{
  "model": "MODEL_ID_FROM_CATALOG",
  "enabled": true,
  "available": true,
  "inputSchema": {
    "type": "object",
    "required": ["prompt"],
    "properties": {
      "prompt": { "type": "string" },
      "aspect_ratio": { "type": "string", "enum": ["1:1", "16:9", "9:16"] }
    },
    "additionalProperties": false
  }
}

cat > input.json <<'EOF'
{"prompt": "A paper lantern glowing on a rainy street at night, cinematic light"}
EOF

spicyapi tasks quote --model MODEL_ID_FROM_CATALOG --input-file input.json

quoteId: eyJ2IjoxLCJtIjoi…
model: MODEL_ID_FROM_CATALOG
estimatedCost: 0.03
maxCharge: 0.03
currency: USD
quantity: 1
unit: per_image
expiresAt: 2026-09-17T08:05:00Z

spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --wait

Estimated charge: USD 0.03; maximum charge: USD 0.03. Quote expires: 2026-09-17T08:05:00Z.
Idempotency-Key: 4f6755a5-0d72-4420-9f6b-9faf0e2b0241
Create a billable task with model MODEL_ID_FROM_CATALOG? Estimated charge: USD 0.03; maximum charge: USD 0.03. Quote expires: 2026-09-17T08:05:00Z. Idempotency-Key: 4f6755a5-0d72-4420-9f6b-9faf0e2b0241. Continue? [y/N]

Accepted: job_01k3m8x9q2z4v7n5p6r8s0t1w3
If waiting is interrupted: spicyapi tasks get job_01k3m8x9q2z4v7n5p6r8s0t1w3

idempotencyKey: 4f6755a5-0d72-4420-9f6b-9faf0e2b0241
accepted: {"taskId":"job_01k3m8x9q2z4v7n5p6r8s0t1w3","state":"queued","estimatedCost":"0.03","deadlineAt":"2026-09-17T08:30:00Z"}
task: {"taskId":"job_01k3m8x9q2z4v7n5p6r8s0t1w3","model":"MODEL_ID_FROM_CATALOG","state":"succeeded","output":{"assets":[{"key":"tasks/…/result.png","url":"https://…","expiresAt":"2026-09-17T08:20:00Z","mime":"image/png","width":1024,"height":1024}]},"cost":"0.03","settled":true,…}

curl -L -o result.png "PASTE_THE_URL_HERE"

출력 읽는 법

• 일반 출력은 한 줄에 name: value를 하나씩 보여 줍니다. output이나 retention처럼 여러 부분으로 이루어진 값은 한 줄짜리 JSON으로 나옵니다.
• --json 옵션을 붙이면 전체 응답을 들여쓰기한 JSON으로 보여 줍니다. 모든 명령에서 쓸 수 있고, 명령 이름 앞에 붙이든 뒤에 붙이든 같습니다. spicyapi --json balance와 spicyapi balance --json은 같은 명령입니다.
• 결과는 화면의 표준 출력으로, 안내 메시지는 오류 출력으로 나갑니다. 가격, 멱등 키, Accepted: 줄, 오류는 안내 메시지에 속합니다. 그래서 spicyapi --json tasks get <task-id> > task.json을 실행하면 task.json에는 결과만 저장되고, 안내 메시지는 계속 화면에 나옵니다.
• 오류는 Error: <what went wrong> (request req_…) 모양이며, 보통 무엇을 하면 되는지 알려 주는 Next: 줄이 뒤따릅니다. --json을 붙이면 오류는 error, type, status, code, requestId가 든 한 줄짜리 JSON 객체로 나오고, Next: 줄은 없습니다. 키가 설정되지 않았을 때 type은 MissingApiKeyError입니다. 지원팀에 문의할 때는 req_… 값을 함께 알려 주세요.
• 금액은 0.03처럼 $ 기호 없이 텍스트로 적은 미국 달러입니다.
• 시각은 UTC입니다. 2026-09-17T08:05:00Z 끝의 Z가 UTC라는 뜻입니다.
• 종료 상태는 명령이 성공하면 0, 실패하면 0이 아닌 값입니다. 스크립트에서 이 값으로 성공 여부를 확인할 수 있습니다.

명령 레퍼런스

모든 명령에는 도움말이 내장되어 있습니다. spicyapi tasks create --help처럼 --help를 붙이세요.

전역 옵션과 환경 변수

다음 옵션은 모든 명령에서 쓸 수 있습니다.

status

하는 일: SpicyAPI가 정상 작동 중이고 내 컴퓨터에서 접속할 수 있는지 확인합니다.

spicyapi status

옵션이 없습니다. 키가 필요 없습니다. 무료입니다.

출력: 한 문장입니다. SpicyAPI is reachable — … answered in … ms.가 나오면 모두 정상입니다. could not be reached는 내 컴퓨터가 아무 응답도 받지 못했다는 뜻이니 네트워크나 프록시를 확인하세요. is not healthy나 reports it is not ready는 저희 쪽 문제입니다. 현재 발생 중인 장애는 status.spicyapi.ai에서 볼 수 있습니다.

--json을 붙이면 원래의 점검 결과가 나옵니다. 중요한 것은 operational: true입니다. 공개 주소에서는 상태가 404인 readiness 항목이 나오는 것이 정상입니다.

docs search

하는 일: 주제에 맞는 문서 페이지를 찾습니다. CLI에 내장된 작은 색인을 검색하므로 키가 필요 없고 SpicyAPI를 호출하지도 않습니다. 결과마다 이 문서 사이트 docs.spicyapi.ai의 페이지 링크가 붙습니다.

spicyapi docs search [words] [--limit <count>]

spicyapi docs search retention

slug: retention
title: Retention and destruction
summary: What the platform caps are, how far down you can dial them, how to destroy a task's content, and what we cannot promise.
keywords: ["privacy","delete","storage","retention","per-request retention","purge","destroy"]
url: https://docs.spicyapi.ai/docs/retention

결과가 여러 개면 차례로 이어서 나오며, 각 결과는 slug:로 시작합니다. 일치하는 결과가 없으면 그렇다고 알려 주고, 종료 상태는 그래도 0입니다.

No documentation matched "refnd". Try fewer or different words, or run `spicyapi docs search` without words to browse pages.

--json을 붙였을 때 일치하는 결과가 없으면 빈 목록 []이 나옵니다. 무료입니다.

models list

하는 일: 내 계정으로 지금 호출할 수 있는 모델을, 내 계정에 적용되는 가격과 함께 나열합니다.

spicyapi models list [options]

spicyapi models list --modality video --task image-to-video --json

출력: total과 items입니다. --json을 붙이지 않으면 모든 항목이 한 줄에 나오므로 꼭 붙이세요. 항목마다 가장 쓸모 있는 필드는 다음과 같습니다.

무료입니다. 다만 모델 목록 조회도 계정의 요청 빈도 제한에 포함되므로, 생성할 때마다 먼저 실행할 필요는 없습니다.

models get

하는 일: 모델 하나를 받는 설정까지 포함해 자세히 보여 줍니다.

spicyapi models get <model>

spicyapi models get MODEL_ID_FROM_CATALOG --json

출력: models list와 같은 필드에 inputSchema가 더해집니다. inputSchema에서는 required(반드시 보내야 하는 설정), properties(허용되는 모든 설정과 그 형식), enum(쓸 수 있는 값 목록), minimum과 maximum(숫자 범위), default(설정을 생략했을 때 쓰이는 값)를 읽으세요. x-ui라는 항목은 입력 양식을 만들 때 쓰는 힌트이므로 무시해도 됩니다. 무료입니다.

balance

하는 일: 계정에서 쓸 수 있는 금액을 보여 줍니다.

spicyapi balance

옵션이 없습니다. 무료입니다.

출력: available(지금 쓸 수 있는 금액), held(아직 실행 중인 작업을 위해 예약된 금액), total이며, 모두 미국 달러입니다. funding이 함께 나올 수도 있습니다. 잔액을 선불 충전금과 프로모션 지원금으로 나누고, 지원금이 언제 만료되는지, 어떤 모델에 쓸 수 있는지도 보여 줍니다. 생성할 때마다 잔액을 먼저 확인할 필요는 없습니다. tasks create가 대신 확인합니다.

usage

하는 일: 지금 쓰는 API 키로 실행한 생성 수와 그 비용을 날짜별·모델별로 묶어 보여 줍니다.

spicyapi usage [--from <date>] [--to <date>]

spicyapi usage --from 2026-09-01 --to 2026-10-01

이 명령은 9월 한 달 전체를 봅니다. --to에 적은 날은 포함되지 않습니다. 두 옵션을 모두 생략하면 오늘을 포함한 최근 7일을 보여 줍니다.

출력: from, to, currency, totalCalls, totalSpend에 이어, days(날짜별 calls, succeeded, failed, spend)와 models(같은 숫자를 모델별로)가 나옵니다. totalSpend에는 최종 청구 금액만 합산됩니다. days와 models는 같은 작업을 두 가지 방식으로 묶은 것이므로 서로 더하지 마세요. 키 하나가 아니라 계정 전체의 사용량은 콘솔의 사용량 페이지에서 보세요.

무료입니다. 1분에 30번까지만 호출할 수 있으므로, 합계를 확인하는 데 쓰고 반복문 안에서는 쓰지 마세요.

tasks quote

하는 일: 생성 한 번에 정확히 얼마가 드는지 알려 줍니다. 생성을 시작하지도, 금액을 예약하지도 않습니다.

spicyapi tasks quote --model <model> --input-file <path>

출력: quoteId, model, estimatedCost, maxCharge, currency, quantity(예: 과금되는 초 수), unit, expiresAt입니다. 견적은 5분 동안 유효합니다.

무료이며 확인을 묻지 않습니다. 모델이나 설정을 비교할 때 쓰세요. tasks create는 견적을 직접 받으므로, 그 전에 꼭 실행해야 하는 것은 아닙니다.

tasks create

하는 일: 이미지나 영상 생성을 시작합니다. 비용이 듭니다. CLI는 언제나 가격을 먼저 보여 주고 확인을 받습니다.

spicyapi tasks create --model <model> --input-file <path> [options]

진행 순서:

1. CLI가 입력을 읽고 JSON 객체인지 확인합니다. 입력이 없으면 여기서 멈춥니다.
2. 스크립트 안처럼 질문에 답할 사람이 없는데 --yes도 없으면 여기서 멈춥니다.
3. 견적을 받아 예상 청구 금액, 최대 청구 금액, 견적 만료 시각, 멱등 키를 출력합니다.
4. Continue? [y/N]라고 묻습니다. y나 yes라고 답해야만 계속합니다. 기본 답은 아니요입니다.
5. 견적 가격으로 작업을 만듭니다. 예상 금액이 잔액에서 예약되며, 그 금액이 이 작업에 청구될 수 있는 최대 금액이기도 합니다.
6. --wait가 없으면 idempotencyKey, taskId, state(queued), estimatedCost, deadlineAt을 출력하고 끝납니다. --wait가 있으면 곧바로 Accepted: <task-id>와 복구 명령을 출력하고, 기다린 뒤 idempotencyKey, accepted, 끝난 task를 출력합니다.

deadlineAt은 작업이 expired로 끝나기 전에 완료될 수 있는 가장 늦은 시각입니다. 다운로드 링크나 파일이 만료되는 시각이 아닙니다.

spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --wait

macOS와 Linux에서는 입력을 명령 안에 바로 적을 수도 있습니다.

spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-json '{"prompt": "A paper lantern on a rainy street"}'

기다리기가 (Ctrl + C가 아니라) 오류로 끝나면, 마지막 몇 줄에 필요한 정보가 모두 다시 나옵니다. 위로 스크롤해 Accepted: 줄을 찾을 필요가 없습니다.

Error: task job_01k3m8x9q2z4v7n5p6r8s0t1w3 did not reach a terminal state within 600000ms
Task job_01k3m8x9q2z4v7n5p6r8s0t1w3 was accepted and may still be running; only the wait stopped.
Recover: spicyapi tasks get job_01k3m8x9q2z4v7n5p6r8s0t1w3
To replay the same request without creating a second task, reuse --idempotency-key 4f6755a5-0d72-4420-9f6b-9faf0e2b0241.

429나 서버 오류처럼 해결 방법이 알려진 오류였다면 Next: 줄이 이어집니다. --json을 붙이면 같은 정보가 오류 객체의 taskId, idempotencyKey, recover에 들어 있습니다.

tasks wait

하는 일: 이미 시작한 작업이 끝날 때까지 기다립니다.

spicyapi tasks wait <task-id> [options]

spicyapi tasks wait job_01k3m8x9q2z4v7n5p6r8s0t1w3 --wait-timeout-ms 1800000

출력: 작업 상태가 succeeded, failed, expired 중 하나가 되면 끝난 작업을 tasks get과 같은 필드로 보여 줍니다. 작업은 성공했지만 파일을 아직 복사하는 중이라면 조금 더 기다립니다.

시간 제한이 다 되면 Error: task … did not reach a terminal state within 600000ms가 나옵니다. 실패가 아니라 작업이 아직 실행 중이라는 뜻입니다. 필요하면 --wait-timeout-ms를 더 길게 잡아 다시 기다리세요. 기다리기를 멈춰도 작업은 절대 취소되지 않습니다. 무료입니다.

tasks get

하는 일: 작업 하나의 현재 모습을 보여 줍니다. 상태, 비용, 결과 링크, 그리고 내용이 언제 삭제되는지입니다.

spicyapi tasks get <task-id>

작업을 만든 API 키와 같은 키를 쓰세요. 다른 키로는 "찾을 수 없음"이 나옵니다.

출력 필드:

일반 출력은 Outputs expire: …나 Content: Destroyed — you removed the outputs … 같은 쉬운 말 요약으로 끝납니다. 호출할 때마다 새 다운로드 링크를 돌려줍니다. 무료입니다.

tasks list

하는 일: 지금 쓰는 API 키로 만든 작업을 한 페이지씩 나열합니다.

spicyapi tasks list [options]

spicyapi --json tasks list --from 2026-09-01 --to 2026-09-08 --state failed

출력: items(항목마다 taskId, model, state, cost, settled, createdAt, deadlineAt, completedAt), hasMore, nextCursor입니다. hasMore가 true이면 --from과 --to까지 똑같은 명령에 --cursor와 nextCursor 값을 더해 다시 실행하세요. 목록에는 다운로드 링크가 없으니, 원하는 작업은 tasks get으로 여세요. 무료입니다.

tasks retry

하는 일: failed나 expired로 끝난 작업을 새 ID를 가진 새 작업으로 다시 실행합니다. 비용이 듭니다.

spicyapi tasks retry <task-id> [options]

Retry source task … Continue? [y/N]라고 묻습니다. tasks create와 달리, 묻기 전에 가격을 보여 주지 않습니다. 새 작업은 모델의 현재 가격으로 과금되므로, 가격이 중요하다면 spicyapi models get <model>로 먼저 확인하세요.

출력: idempotencyKey, 새 taskId, sourceTaskId(원래 작업), state, estimatedCost(예약된 금액), deadlineAt입니다.

• 재시도할 수 있는 작업은 failed와 expired, 그리고 예전의 canceled 작업뿐입니다. 성공한 결과를 다른 버전으로 또 받고 싶다면 tasks create를 쓰세요.
• 원래 입력을 바꾸지 않고 그대로 다시 쓰므로, 재시도는 실패 원인이 일시적이었을 때만 도움이 됩니다. 먼저 errorCode를 확인하세요. 실패한 작업 다시 시도하기와 오류를 보세요.
• 입력이 가리키던 업로드 파일이 그사이 만료됐다면 재시도는 실패합니다. 파일을 다시 업로드하고 tasks create를 쓰세요.
• 재시도는 원래 작업의 보관 설정을 그대로 따릅니다.
• 작업 ID를 보기 전에 tasks create의 연결이 끊겼다면, 그것은 실패한 작업이 아닙니다. 대신 기다리기가 중단된 작업 다시 이어 가기의 복구 방법을 따르세요.

tasks purge

하는 일: 끝난 작업의 생성 미디어, 결과 페이로드(저장된 결과 데이터), 프롬프트와 그 밖의 입력 텍스트를, 만료를 기다리지 않고 바로 영구히 삭제합니다.

spicyapi tasks purge <task-id> [--yes]

아직 queued나 running인 작업은 파기할 수 없습니다. 취소도 할 수 없습니다. 취소 명령도 취소 API도 없습니다. 그러니 spicyapi tasks wait <task-id>로 끝날 때까지 기다린 뒤 파기하세요.

되돌릴 수 없는 작업이므로, 무엇이 삭제되는지 설명하고 확인을 받습니다. 남겨 두고 싶은 것은 먼저 내려받으세요.

출력: taskId, contentState(purged), purgedAt, contentRemovedBy(user), billingRetained(언제나 true), mediaDeletionPending이 나오고, 이어서 무엇을 파기했는지와 저장된 미디어가 1분쯤 안에 지워진다는 안내가 한 줄 나옵니다. contentState가 여전히 present라면 이번에는 아무것도 지워지지 않은 것이니, 잠시 뒤에 다시 시도하세요.

무료이며, 환불이 아닙니다. 과금 원장 항목, 청구 금액, 모델, 상태, 타임스탬프, 요청 ID는 기록으로 남습니다. 데이터 보관과 파기를 보세요.

files upload

하는 일: 이미지로 영상을 만들 때 첫 장면으로 쓸 사진처럼, 내 컴퓨터의 파일을 업로드하고 입력에 넣을 spicy:// 주소를 돌려줍니다.

spicyapi files upload <path> [--content-type <type>]

지원하는 파일은 최대 10 MiB의 .jpg, .jpeg, .png, .webp, .gif 이미지, 그리고 최대 90 MiB·600초의 .mp4, .webm 영상과 .mp3, .wav 오디오입니다. 모델에 따라 더 낮은 제한이 따로 있을 수 있습니다.

spicyapi files upload ./start-frame.jpg

fileId: fil_01k3m8x9q2z4v7n5p6r8s0t1w3
status: ready
bytes: 402118
contentType: image/jpeg
sha256: a91f4c2e5b7d16809e3f2a4c8d0b61e7c4a890e5d2f71b3c609ae8427d15f0c6
uri: spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3
expiresAt: 2026-09-18T09:12:11Z
width: 1280
height: 720

출력: uri 값을 출력된 그대로 복사해 모델의 파일 설정(흔히 image_url)에 넣으세요. expiresAt까지, 보통 하루 동안 쓸 수 있습니다. 그 뒤에는 파일을 다시 업로드하세요. 업로드는 무료입니다.

files download-url

하는 일: 끝난 작업의 결과를 내려받을 새 링크를 만듭니다. 링크를 출력할 뿐, 파일을 저장하지는 않습니다.

spicyapi files download-url <task-id> [--key <key>]

출력: key, url, expiresAt입니다. 링크는 약 20분 동안 유효하니 브라우저로 열거나 curl로 내려받으세요. 아직 성공하지 않은 작업이면 "찾을 수 없음"이 나옵니다. 파일을 아직 복사하는 중이면 충돌 오류가 나니 몇 초 뒤에 다시 시도하세요. 작업의 파일이 이미 삭제됐다면 새 링크를 만들 수 없습니다. 무료입니다.

webhooks verify

하는 일: SpicyAPI 콜백을 받는 서버를 운영한다면(--callback-url 참고), 저장해 둔 콜백 하나가 진짜이고 변조되지 않았는지 확인합니다. 전부 내 컴퓨터 안에서 실행되며 API 키가 필요 없습니다.

spicyapi webhooks verify --body-file <path> --timestamp <seconds> --signature <base64> --payload-version <version>

출력: 성공하면 payload(콜백 내용), payloadVersion, taskId, deliveryId(버전 2), timestamp가 나옵니다. 하나라도 맞지 않으면 오류를 출력하고 0이 아닌 종료 상태로 끝납니다. 무료입니다.

서명 키는 가입할 때 자동으로 만들어지지만, 그 값은 보여 주지 않습니다. 복사할 수 있는 키를 받으려면 콘솔에서 웹훅을 열고 발급을 누르세요(이미 키가 설정되어 있다면 교체). 새 키는 한 번만 표시됩니다. 교체는 유예 기간 없이 즉시 적용되며, 이전 키는 바로 서명을 멈춥니다. 웹훅을 보세요.

자주 쓰는 레시피

이미지 생성하기

spicyapi models list --modality image --json
spicyapi models get MODEL_ID_FROM_CATALOG --json
spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --wait

첫 번째 명령에서 ID를 고르고, 두 번째 명령이 보여 주는 설정으로 input.json을 만든 다음, 세 번째 명령을 실행하고 y로 확인하세요. 단계별 설명은 첫 결과 받기에 있습니다.

사진으로 영상 만들기

spicyapi models list --modality video --task image-to-video --json
spicyapi models get MODEL_ID_FROM_CATALOG --json

spicyapi files upload ./start-frame.jpg

{
  "prompt": "Slow push-in, rain running down the window",
  "image_url": "spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3",
  "duration_seconds": 5
}

spicyapi tasks quote --model MODEL_ID_FROM_CATALOG --input-file input.json
spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --wait --wait-timeout-ms 1800000

업로드한 사진은 하루 동안 쓸 수 있습니다. 그 뒤에는 다시 업로드하세요.

기다리기가 중단된 작업 다시 이어 가기

터미널이 닫히거나, 네트워크가 끊기거나, 컴퓨터가 잠자기에 들어가거나, 기다리는 시간이 다 되어도 작업은 계속 실행됩니다. 어떻게 다시 찾아갈지는 화면에서 무엇을 봤는지에 따라 다릅니다.

• Accepted: job_… 줄이나, 오류 아래의 Recover: 줄을 봤다면 작업 ID를 가지고 있는 것입니다. 다시 기다리거나, 상태만 확인하세요.

  spicyapi tasks wait job_01k3m8x9q2z4v7n5p6r8s0t1w3 --wait-timeout-ms 1800000
  spicyapi tasks get job_01k3m8x9q2z4v7n5p6r8s0t1w3

• Idempotency-Key: 줄만 봤다면(예를 들어 작업을 만드는 도중에 연결이 끊긴 경우), 모델과 입력까지 똑같은 명령에 그 키를 더해 다시 실행하세요.

  spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --idempotency-key 4f6755a5-0d72-4420-9f6b-9faf0e2b0241 --wait

  CLI는 가격을 보여 주고 다시 묻습니다. 하지만 첫 시도가 접수됐었다면, SpicyAPI는 두 번째 작업을 시작해 과금하는 대신 그 작업을 그대로 돌려줍니다. 같은 API 키로 24시간 동안 통합니다. 첫 시도가 아예 도착하지 않았다면 지금 한 번만 작업이 만들어집니다.

• 둘 다 없다면 최근 작업 목록을 띄워, 시각과 모델로 찾으세요.

  spicyapi --json tasks list --limit 10

실패한 작업 다시 시도하기

먼저 실패한 이유를 알아보세요.

spicyapi tasks get job_01k3m8x9q2z4v7n5p6r8s0t1w3

그다음 errorCode를 읽으세요. 실패하거나 만료된 작업은 보통 예약 금액이 전액 해제됩니다. 다만 모델 페이지에 명시된 일부 콘텐츠 거부는 접수 시 견적 금액으로 과금됩니다. 최종 청구액은 settled와 cost로 확인하세요. tasks retry는 같은 입력을 다시 보내므로, 원인이 일시적이었을 때만 도움이 됩니다.

전체 목록은 오류에 있습니다.

재시도가 의미 있을 때 실행하세요. 새 작업이 만들어지고, 그만큼 과금됩니다.

spicyapi tasks retry job_01k3m8x9q2z4v7n5p6r8s0t1w3 --wait

사용량 내보내기

지금 쓰는 키의 한 달 사용량을 파일로 저장합니다.

spicyapi --json usage --from 2026-09-01 --to 2026-10-01 > usage-2026-09.json

이 파일에는 날짜별·모델별 합계가 들어 있습니다. 작업 하나하나의 목록이 필요하다면 spicyapi --json tasks list --from 2026-09-01 --to 2026-09-08 --limit 100을 같은 방식으로 저장하되, hasMore가 true인 동안 nextCursor를 따라가세요. 계정 전체의 수치와 인보이스는 콘솔에 있습니다.

스크립트에서 CLI 실행하기

스크립트 안에서는 Continue? [y/N]에 답할 사람이 없으므로, 비용이 드는 명령은 --yes를 붙이지 않으면 실행을 거부합니다. --yes를 붙인다면 다음을 지키세요.

• 먼저 견적을 받고 스크립트 안에서 가격을 확인하세요.
• 생성마다 poster-2026-09-17-v1처럼 고정된 --idempotency-key를 따로 붙이세요. 그래야 스크립트를 두 번 실행해도 두 번 과금되지 않습니다.
• --json을 붙이고 결과에서 state를 읽으세요. 명령이 종료 상태 0으로 끝났다고 해서 작업이 성공했다는 보장은 없습니다.
• 콘솔에서 키에 지출 한도를 설정하세요.

spicyapi --json tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --idempotency-key poster-2026-09-17-v1 --yes --wait > result.json

비용, 확인, 안전

비용이 드는 명령. tasks create와 tasks retry뿐입니다. 가격은 미국 달러입니다. 견적 받기, 목록 보기, 확인하기, 업로드, 다운로드, 삭제는 무료입니다.

가격을 먼저 보기. tasks quote는 아무것도 시작하지 않고 요청의 가격을 계산합니다. tasks create는 견적을 직접 받아, 묻기 전에 Estimated charge와 maximum charge를 보여 줍니다. 작업이 접수되면 예상 금액이 예약(held)되며, 그 금액이 청구될 수 있는 최대 금액이기도 합니다. 작업이 성공하면 실제로 만들어진 만큼만, 예약 금액을 넘지 않게 정산되고, 남은 금액은 잔액으로 돌아옵니다.

확인 질문. Continue? [y/N]는 y를 입력하지 않는 한 답이 아니요라는 뜻입니다. --yes는 대신 답해 주므로, 가격을 이미 알 때만 쓰세요. 스크립트 안이나 파이프로 입력을 넘길 때처럼 CLI가 물어볼 수 없는 곳에서 --yes가 없으면, 예라고 가정하지 않고 실행을 거부합니다. tasks purge도 삭제는 되돌릴 수 없으므로 같은 방식으로 묻습니다. tasks retry도 묻지만, 가격을 먼저 보여 주지는 않습니다.

멱등 키, 쉽게 말하면. 주문 번호처럼 생성 한 건에 붙이는 이름표입니다. tasks create와 tasks retry는 실행할 때마다 멱등 키를 하나씩 출력합니다. 인터넷 연결이 끊겨 생성이 시작됐는지 확실하지 않다면, 같은 명령에 --idempotency-key와 출력된 값을 붙여 다시 실행하세요. 원래 작업을 돌려받고, 두 번 과금되지 않습니다. 이 이름표는 같은 API 키로 24시간 동안 통합니다. 다른 생성에 다시 쓰지 마세요. 같은 키를 다른 입력과 함께 보내면 거부됩니다.

취소는 없습니다. 접수된 작업은 취소할 수 없습니다. Ctrl + C를 누르거나, 터미널을 닫거나, 키를 폐기해도 기다리기만 멈출 뿐, 작업은 끝까지 실행되고 정상적으로 과금됩니다.

실패하거나 만료된 작업은 보통 예약 금액이 전액 해제됩니다. 다만 모델 페이지에 명시된 일부 콘텐츠 거부는 접수 시 견적 금액으로 과금됩니다. 최종 청구액은 settled와 cost로 확인하세요.

남기고 싶은 것은 내려받으세요. 결과 파일은 최대 약 14일 동안(계정 설정이나 --retention이 더 짧으면 그보다 짧게) 보관된 뒤 영구히 삭제됩니다. 다운로드 링크는 약 20분 동안 유효하지만, 파일이 남아 있는 동안은 언제든 새 링크를 받을 수 있습니다. 업로드한 파일은 하루 동안 쓸 수 있습니다. 프롬프트 텍스트는 기본적으로 30일 뒤에 지워집니다. 과금 기록은 남습니다. 데이터 보관과 파기를 보세요.

지출 한도. 키마다 일 한도, 월 한도, 누적 한도를 API 키 페이지에서 걸 수 있습니다. 새 키에는 직접 설정하기 전까지 한도가 없습니다. 한도를 넘게 될 작업은 시작 전에 거부됩니다.

내 키. CLI는 키를 SPICY_API_KEY에서만 읽고, 절대 출력하지 않으며, 오류 안내에서도 앞의 아홉 글자(sk-spicy-)까지만 보여 줍니다.

더 자세한 내용: 과금, 멱등성, 작업 확정과 재시도.

문제 해결

화면에 나온 메시지를 찾으세요. SpicyAPI에서 온 오류는 (request req_…)로 끝납니다. 지원에 문의할 때는 그 값을 함께 알려 주되, 키는 절대 보내지 마세요.

모든 오류 코드는 오류에서, 복구 방법은 문제 해결과 복구에서 설명합니다.

소스

이 패키지는 MIT 라이선스이고 **github.com/spicyapi-ai/spicy-cli**에서 공개적으로 개발됩니다. 이 페이지에서 설명한 명령의 구현을 읽거나, 문서와 다르게 동작하는 부분을 알리거나, 변경을 제안하는 일 모두 저장소에서 하면 됩니다.

다음 단계