이미지→영상 튜토리얼

계정, 잔액, API 키 준비하기

먼저 계정 설정을 따라 하세요. 끝나면 다음이 갖춰져 있어야 합니다.

• 잔액이 충전된 SpicyAPI 계정
• sk-spicy-로 시작하는 API 키
• SPICY_API_KEY라는 환경 변수에 넣어 둔 그 키. 환경 변수는 터미널이 자신이 실행하는 프로그램에 넘겨주는, 이름이 붙은 값입니다. 덕분에 키를 명령이나 코드에 직접 적을 필요가 없습니다.

지금 쓰고 있는 터미널 창에 키가 설정돼 있는지, 키 전체를 화면에 띄우지 않고 확인하세요.

echo "${SPICY_API_KEY:0:9}"

이렇게 보여야 합니다: sk-spicy-. 아무것도 나오지 않거나 오류가 나오면 이 창에는 키가 설정되지 않은 것입니다. 계정 설정으로 돌아가세요.

작업 폴더에 이미지 넣기

이 튜토리얼용 폴더를 만들고, 그 폴더에서 터미널을 여세요. 이 페이지의 모든 명령은 이 폴더에서 실행하며, 명령이 만드는 파일도 모두 이 폴더에 생깁니다.

mkdir -p ~/spicy-video
cd ~/spicy-video

이미지를 이 폴더에 복사하고 이름을 start-frame.jpg로 바꾸세요. PNG 파일이라면 start-frame.png로 하고, 이 페이지에 start-frame.jpg라고 적힌 곳마다 그 이름을 쓰면 됩니다.

좋은 시작 이미지의 조건은 다음과 같습니다.

• 형식과 크기: JPEG, PNG, WebP, GIF이며 최대 10 MiB(약 10메가바이트)입니다. 모델에 따라 더 엄격한 자체 제한이 있을 수 있으며, 1단계에서 확인할 수 있습니다.
• 파일이 실제로 그 형식이어야 합니다. SpicyAPI는 파일 이름만이 아니라 파일 내용을 검사합니다. 휴대폰 사진은 HEIC인 경우가 많은데, 이름만 .jpg로 바꿔서는 변환되지 않습니다. 먼저 사진을 열어 JPEG로 내보내거나 저장하세요.
• 모양: 이미지가 영상의 첫 프레임이 됩니다. 가로 영상에는 가로로 긴 이미지를, 세로 영상에는 세로로 긴 이미지를 쓰세요. aspect_ratio 설정을 제공하는 모델도 있습니다.
• 권리: 사용할 권리가 있는 이미지를 쓰세요.

고른 도구 준비하기

npm install -g @spicyapi/cli
spicyapi --version

spicyapi balance

1. 모델 고르고 설정 읽기

할 일: 내 계정으로 쓸 수 있는 이미지→영상 모델을 나열하고, 하나를 고른 뒤, 그 모델이 받는 설정을 읽습니다.

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

{
  "total": 1,
  "items": [
    {
      "model": "MODEL_ID_FROM_CATALOG",
      "displayName": "Example video model",
      "modality": "video",
      "tasks": ["image-to-video"],
      "enabled": true,
      "available": true,
      "quantityField": "duration_seconds",
      "maxOutputDurationSeconds": 10,
      "taskTimeoutSeconds": 1800,
      "pricing": [
        { "variant": "720p", "unit": "per_second", "price": "…", "currency": "USD" },
        { "variant": "1080p", "unit": "per_second", "price": "…", "currency": "USD" }
      ]
    }
  ]
}

spicyapi models get MODEL_ID_FROM_CATALOG --json

목록에서 확인할 것:

설정 읽는 법. inputSchema는 JSON Schema로 작성된 모델의 설정 목록입니다.

• required에는 반드시 보내야 하는 설정이 나열됩니다. 이런 종류의 모델에서는 image_url이 언제나 들어 있고, 대부분은 prompt도 필수입니다.
• properties에는 모델이 받는 모든 설정이 나열됩니다. 설정마다 type과 쉬운 영어로 쓴 description이 있고, 흔히 enum(허용되는 값의 전부), minimum과 maximum, default(설정을 생략했을 때 쓰이는 값)도 있습니다.
• 설정마다 들어 있는 x-ui는 화면 표시용 힌트입니다. x-ui.affects_price: true는 그 설정을 바꾸면 가격이 바뀐다는 뜻입니다.
• 일부 모델은 "A를 보내면 B도 보내야 한다" 같은 조건을 최상위에 추가합니다. 읽는 법은 Spicy Schema 사양에서 설명합니다.
• examples에는 서버가 이미 검사한 완전한 입력값이 들어 있어, 안전하게 시작할 수 있는 출발점이 됩니다.

가장 자주 만나는 설정. 이름은 모든 모델에서 같지만, 모델마다 그중 일부만 받으며 허용되는 값도 모델마다 다릅니다.

방금 일어난 일: 내 계정의 실시간 카탈로그를 내 가격까지 포함해 읽었습니다. 과금된 것은 없습니다. 카탈로그 조회도 계정의 요청 한도에 포함되므로, 영상을 만들 때마다 반복할 필요는 없습니다. 모델을 바꾸거나 400을 받았을 때 다시 하세요.

2. 이미지 업로드하기

할 일: start-frame.jpg를 업로드하고, 돌려받은 spicy:// 주소를 복사합니다. 업로드는 무료입니다.

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

방금 일어난 일: 이미지가 내 계정 전용으로 비공개 저장되고, 검사를 거쳐(실제 파일 형식이 지정한 형식과 일치해야 합니다) spicy:// 주소를 받았습니다. 이 주소는 웹 링크가 아닙니다. 내 계정만, 그것도 작업의 입력 안에서만 쓸 수 있습니다. 쓸 수 있는 기간은 1일이며(expiresAt 참고), 그 뒤에는 이미지를 다시 업로드하세요.

업로드가 실패하면:

3. 영상 묘사하고 가격 확인하기

할 일: 설정을 input.json이라는 파일에 적고, 견적을 요청합니다.

input.json 작성하기. 모든 이미지→영상 모델이 받는 두 가지 설정부터 시작하세요. prompt에는 내 문장을 넣고, image_url 값은 2단계에서 복사한 uri로 바꾸세요.

{
  "prompt": "The camera slowly pushes in while rain runs down the window and neon light flickers",
  "image_url": "spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3"
}

생략한 설정에는 모델의 default가 쓰입니다. 직접 정하고 싶다면 내 모델의 properties에 있는 설정만, 허용되는 값으로 추가하세요. 예를 들어 모델이 duration_seconds와 resolution을 나열하고 아래 값을 허용한다면 다음과 같이 씁니다.

{
  "prompt": "The camera slowly pushes in while rain runs down the window and neon light flickers",
  "image_url": "spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3",
  "duration_seconds": 5,
  "resolution": "720p"
}

작업 폴더에 파일을 저장하세요.

cat > input.json <<'EOF'
{
  "prompt": "The camera slowly pushes in while rain runs down the window and neon light flickers",
  "image_url": "spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3"
}
EOF

따옴표는 둥근 따옴표가 아니라 곧은 따옴표(")를 쓰고, 마지막 설정 뒤에는 쉼표를 붙이지 마세요.

견적 받기:

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

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

방금 일어난 일: SpicyAPI가 입력값을 모델의 설정과 대조해 검사하고, 바로 이 요청의 가격을 계산했습니다. 아무것도 시작되지 않았고, 아무것도 과금되지 않았습니다. estimatedCost는 지금 시작하면 예약될 금액이고, maxCharge는 청구될 수 있는 최대 금액입니다. quantity와 unit은 무엇에 대해 돈을 내는지, 예를 들어 5초라는 것을 보여 줍니다.

견적은 5분 동안, 그리고 바로 이 입력값에 대해서만 유효합니다. 길이나 해상도를 바꿔 다시 견적을 받으면 가격을 비교할 수 있습니다. 견적은 작업을 시작할 때와 같은 검사를 거치므로, 문제가 있다면 여기서 무료로 드러납니다. 400은 입력값이 모델의 설정과 맞지 않는다는 뜻이고(1단계를 참고해 input.json을 고치세요), 40201은 잔액이 모자란다는 뜻입니다. 나머지 코드는 7단계에 정리해 두었습니다.

4. 생성 시작하기

멱등 키를 쉬운 말로 풀면. 멱등 키는 주문 번호처럼 영상 하나에 붙이는 라벨입니다. 연결이 끊겨 영상이 시작됐는지 확실하지 않다면, 같은 요청을 같은 라벨로 다시 보내세요. SpicyAPI는 두 번째 영상을 시작해 과금하는 대신, 이미 시작한 작업을 돌려줍니다. 라벨은 같은 API 키로 24시간 동안 유효합니다. 다른 영상에는 새 라벨을 쓰세요. 같은 라벨을 다른 입력값과 함께 보내면 409로 거부됩니다. 자세한 내용은 멱등성에 있습니다.

할 일:

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

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

idempotencyKey: 4f6755a5-0d72-4420-9f6b-9faf0e2b0241
taskId: job_01k3m8x9q2z4v7n5p6r8s0t1w3
state: queued
estimatedCost: …
deadlineAt: 2026-09-17T08:35:00Z

방금 일어난 일: SpicyAPI가 생성을 접수했습니다. 이제 이것은 작업이며, 잔액에서 estimatedCost만큼이 예약됐습니다. 이 금액이 이 영상에 들 수 있는 최대 금액이기도 합니다. state: queued는 차례를 기다리고 있다는 뜻입니다. deadlineAt은 작업이 끝날 수 있는 가장 늦은 시각이며, 그때까지 끝나지 않으면 expired로 끝나고 아무것도 과금되지 않습니다. deadlineAt은 파일이 만료되는 시각이 아닙니다.

견적을 함께 넘긴다는 것은 "내가 본 가격일 때만 접수해 달라"는 뜻입니다. 그사이 가격이나 입력값이 바뀌었다면, 다른 금액을 예약하는 대신 요청을 40901로 거부합니다. CLI는 이 일을 알아서 해 줍니다.

연결이 끊겨 작업 ID를 보지 못했다면 새 라벨로 그냥 다시 시작하지 마세요. 그러면 두 번째 영상이 만들어지고 그 비용까지 청구됩니다. 같은 라벨로 요청을 반복하세요.

• CLI: spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --idempotency-key <the value you copied>(<the value you copied> 자리에는 복사해 둔 Idempotency-Key 값을 넣습니다). 기다리기가 중단된 작업 다시 이어 가기를 보세요.
• SDK: node generate.mjs --yes를 다시 실행하세요. idempotency-key.txt를 그대로 다시 씁니다.
• HTTP: "영상 시작하기" 블록을 다시 실행하세요. idempotency-key.txt를 그대로 다시 씁니다.

4단계가 거부됐다면 아무것도 만들어지지 않았고, 과금되지도 않았습니다. 이유와 해결 방법은 7단계에 있습니다.

5. 영상 기다리기

할 일: 작업이 끝날 때까지 상태를 확인합니다. 영상은 보통 몇 분 걸립니다.

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

{
  "taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
  "model": "MODEL_ID_FROM_CATALOG",
  "state": "succeeded",
  "output": {
    "assets": [
      {
        "key": "tasks/2026/09/17/job_01k3m8x9q2z4v7n5p6r8s0t1w3/result.mp4",
        "url": "https://…",
        "expiresAt": "2026-09-17T08:40:00Z",
        "mime": "video/mp4",
        "durationSeconds": 5,
        "width": 1280,
        "height": 720,
        "bytes": 4839211
      }
    ]
  },
  "cost": "…",
  "settled": true
}

방금 일어난 일: 도구가 몇 초마다 SpicyAPI에 작업 상태를 물었습니다. 상태는 queued(대기 중), running(생성 중)을 거쳐 최종 상태 하나로 끝납니다. succeeded, failed, expired 중 하나입니다. 성공한 뒤에는 파일이 SpicyAPI 자체 저장소로 복사되는데, 몇 초가 더 걸립니다. 그동안 결과에는 pending: true가 표시됩니다. settled가 true가 되면 cost가 최종 금액입니다.

• 터미널을 닫거나 Ctrl + C를 눌러도 작업은 취소되지 않습니다. 기다리기만 멈춥니다. 작업 ID를 보관해 두었다가 나중에 이 단계를 다시 실행하세요.
• 몇 초에 한 번보다 자주 확인하지 마세요. 작업 조회는 새 작업 제출과 독립된 계정 읽기 허용량을 사용합니다. 호출 제한을 참고하세요.
• 앱이나 서버라면 계속 물어보는 대신, 작업이 끝났을 때 SpicyAPI가 알려 주게 하세요. 기다리지 말고 알림 받기를 보세요.

6. 영상 내려받아 보관하기

할 일: 새 다운로드 링크를 받아 파일을 내 컴퓨터에 저장합니다.

spicyapi files download-url job_01k3m8x9q2z4v7n5p6r8s0t1w3

key: tasks/2026/09/17/job_01k3m8x9q2z4v7n5p6r8s0t1w3/result.mp4
url: https://…
expiresAt: 2026-09-17T08:52:00Z

curl -L -o my-video.mp4 "PASTE_THE_URL_HERE"

방금 일어난 일: 모든 결과에는 직접 다운로드 링크가 딸려 옵니다. 링크는 약 20분 동안 유효하고 API 키가 필요 없습니다. 링크에 키를 절대 붙이지 마세요. 링크가 만료되면 작업을 다시 조회하거나 files download-url을 써서 새 링크를 받으세요.

7. 문제가 생겼을 때

문제는 두 종류가 있고, 대처 방법이 서로 다릅니다.

요청이 거부되는 경우. 명령이나 호출이 곧바로 오류를 받습니다. 아무것도 만들어지지 않았고, 아무것도 과금되지 않았습니다. 메시지가 이유를 알려 주며, 오류에는 code와 함께 지원팀에 문의할 때 알려 줄 요청 ID(req_…)가 들어 있습니다.

작업이 실패하는 경우. 작업은 접수됐지만 succeeded가 아니라 failed나 expired로 끝납니다. 작업에는 이유를 알려 주는 errorCode와, 더 자세한 설명이 문장으로 담긴 errorMessage가 표시됩니다. 실패하거나 만료된 작업은 보통 예약 금액이 전액 해제됩니다. 다만 모델 페이지에 명시된 일부 콘텐츠 거부는 접수 시 견적 금액으로 과금됩니다. 최종 청구액은 settled와 cost로 확인하세요.

다음과 같이 확인하세요.

spicyapi tasks get job_01k3m8x9q2z4v7n5p6r8s0t1w3

그다음 메시지 문구가 아니라 errorCode를 보고 무엇을 할지 정하세요.

그 밖의 값은 upstream_failed와 똑같이 다루세요. 전체 목록은 오류에 있습니다.

실패한 작업 다시 실행하기. 다시 시도하면 같은 모델과 입력값으로 새 작업이 만들어지며, 모델의 현재 가격이 적용됩니다. 4단계와 마찬가지로 비용이 들고, 원래 입력값을 그대로 씁니다. 원래 입력값이 이미 만료된 업로드를 쓰고 있었다면, 다시 시도하지 말고 이미지를 다시 업로드해 새 작업을 시작하세요.

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

다시 시도할 수 있는 것은 failed와 expired 작업뿐입니다. 성공한 영상을 다른 버전으로 만들고 싶다면 새 라벨로 3단계부터 다시 하세요. 한 번 접수된 작업은 취소할 방법이 없습니다. 자세한 내용은 작업 확정과 재시도에 있습니다.