비동기 작업

이 페이지는 비동기 미디어 생성 작업을 설명합니다. 생성 시 잔액을 hold하고 성공하면 실제 사용량으로 settle하며 failed·expired에서는 전액 해제합니다. 과거 canceled 기록도 같이 처리되지만, 새로 수락된 작업은 취소할 수 없습니다.

API

GET /api/v1/models?includeSchema=1&includeExamples=1
# choose an item where enabled && available

curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: render-001" \
  -d '{
    "model": "MODEL_ID_FROM_CATALOG",
    "input": { "prompt": "a folded paper lantern, hard side light" }
  }'

현재 키의 작업 기록

GET /api/v1/jobs는 요청을 인증한 API 키로 만든 작업만 조회합니다. 같은 계정에 속한 다른 키를 지정할 수 없습니다. 응답에는 메타데이터만 있고 input과 output은 없습니다. 선택한 taskId의 결과는 GET /api/v1/jobs/recordInfo로 가져오세요.

from과 to는 UTC 날짜이며 조회 구간은 [from, to)입니다. 기본 7일, 최대 92일을 조회합니다. state와 정확한 model 참조로 필터링할 수 있으며 limit은 기본 20, 최대 100입니다. hasMore가 true이면 nextCursor를 다음 요청의 cursor로 보내고 from, to와 나머지 조건을 그대로 유지하세요. createdAt 내림차순으로 정렬하며 같은 시각에는 id 내림차순을 적용해 작업을 빠짐없이 구분합니다. 각 페이지는 조회 시점의 상태를 읽으므로 상태나 필터 결과가 고정된 스냅샷은 아닙니다.

서로 다른 네 가지 기한

deadlineAt은 서버가 반환하는 실제 작업 처리 기한입니다. SDK의 timeoutMs는 클라이언트가 기다리는 시간만 제한하며 이미 수락된 작업을 취소하지 않습니다. 결과 URL의 expiresAt은 보통 20분 뒤이고, 생성 미디어 보관 기간은 14일입니다. URL 만료가 작업 실패나 미디어 삭제를 뜻하지는 않습니다.

작업 생성

POST /api/v1/jobs/createTask에 model, input, 선택적인 callBackUrl를 보냅니다. 논리 요청마다 Idempotency-Key 하나를 발급하고 네트워크 재시도에서는 같은 값을 재사용하세요.

상태 판정

새 작업에서 queued와 running은 진행 중 상태이고 succeeded, failed, expired는 종료 상태입니다. 과거 canceled는 읽기 호환성을 위한 종료 상태일 뿐 현재 취소 기능이 아닙니다. HTTP 응답이나 응답 구조의 code: 200은 조회 성공만 뜻하며 생성 결과는 data.state로 판단합니다.

output.assets[].pending이 true면 저장 중이므로 잠시 후 다시 조회합니다. unavailable이 true면 복구할 수 없어 재생성이 필요합니다.

알림과 폴링

운영에서는 webhook을 주 경로로, 지수 백오프와 지터를 적용한 폴링을 복구 경로로 사용하세요. recordInfo와 webhook은 같은 {code,msg,data,request_id} 응답 구조를 사용하므로 파서를 공유할 수 있습니다.

전체 필드 정의는 OpenAPI 3.1 사양을 확인하세요.