작업 확정과 재시도

createTask가 승인되면 생성 작업이 확정되며 취소할 수 없습니다. 이 규칙은 queued와 running 모두에 적용됩니다. 생성이 시작된 뒤에는 확실하게 중지할 수 없으므로, 작업과 비용은 계속 발생하는데 취소되었다고 표시하는 로컬 동작을 SpicyAPI는 제공하지 않습니다.

종료된 작업 재시도

재시도는 성공하지 못한 종료 작업을 다시 실행합니다. 같은 모델, input과 콜백 URL로 새 작업을 생성하므로 원래 요청 본문을 다시 보낼 필요가 없습니다. 새 작업도 일반 작업과 같은 방식으로 과금됩니다. 승인 시 예상 금액을 선점하고 성공한 경우에만 과금합니다.

POST /api/v1/jobs/retry

curl -X POST https://api.spicyapi.ai/api/v1/jobs/retry \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: retry-order-8814-1" \
  -d '{"taskId":"job_01k3m8x9q2z4v7n5p6r8s0t1w3"}'

예시 taskId를 실패한 작업의 ID로 바꾸세요. retry에는 반드시 Idempotency-Key를 보내세요(예: retry-<sourceTaskId>-1). 없으면 두 번 클릭하거나 네트워크 재시도를 했을 때 과금 대상 작업이 두 개 생성됩니다.

재시도 대상은 failed와 expired 작업입니다. 과거 canceled 기록도 읽을 수 있고 하위 호환성을 위해 재시도할 수 있지만, 새 작업은 이용자 동작으로 이 상태에 들어갈 수 없습니다. 재시도가 성공하면 새 대기 작업을 만들고 **HTTP 200**을 반환합니다(createTask의 202와 다릅니다). 응답에는 code: 200이 포함됩니다.

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "job_01k3mnewtask",
    "sourceTaskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
    "state": "queued",
    "estimatedCost": "0.08",
    "deadlineAt": "2026-08-28T10:12:04Z"
  },
  "request_id": "req_01k3mretry"
}

원본 ID가 아니라 새 taskId로 조회하거나 완료를 기다리세요. 비동기 작업을 참고하세요.

• 원본 작업은 종료 상태로 유지되며 변경되지 않습니다.
• 새 작업의 sourceTaskId가 원본을 가리켜 재시도 관계를 보존합니다.
• 현재 스키마, 가격, 권한과 잔액을 다시 확인합니다. 재시도는 새 작업이므로 다시 대기열에 들어가 원본과 독립적으로 처리됩니다.
• 새 작업은 원본과 **동일한 callBackUrl**로 콜백을 보내며 원본의 보관 기간을 유지합니다. retry의 X-Spicy-Retention 헤더는 무시됩니다.
• 재시도는 원본 input을 그대로 사용합니다. 업로드로 저장되는 작은 Base64 이미지를 포함해 SpicyAPI에 업로드한 참조 파일은 하루 동안 유지됩니다. 그 이후 재시도하면 400을 반환합니다. 파일을 다시 업로드하고 createTask로 새 작업을 만드세요.
• Idempotency-Key의 범위는 원본 작업과 재시도 동작입니다. 같은 원본에 같은 키를 반복하면 추가 작업을 생성하지 않고 동일한 새 작업을 반환합니다.

재시도가 거절되는 경우

retry가 오류를 반환하면 금액을 선점하거나 과금하지 않습니다.

상태별 재시도와 동작

재시도 전에 errorCode를 확인하세요. rate_limited, upstream_unavailable과 upstream_failed는 재시도를 고려할 수 있습니다. timeout과 generation_failed는 같은 방식으로 다시 실패할 수 있습니다. invalid_request, unsupported_combination과 content_rejected는 같은 입력으로 다시 실패하며, invalid_asset는 참조 파일을 다시 업로드해야 합니다. 입력을 바꾸고 createTask를 사용하세요. 작업 실패 코드를 참고하세요.