AI 요청을 사용 가능한 파일로 변환하는 방법: 작업(jobs), 재시도 및 출력 검증

저는 3Stone AI의 설립자입니다. 저희 API를 구축하면서 얻은 교훈 중 하나는 성공적인 생성 요청이 전체 과정의 일부에 불과하다는 것입니다. 결과물은 여전히 도착하고, 열릴 수 있으며, 사용 가능해야 합니다.

제공자가 '성공'을 반환하더라도 고객에게 사용할 수 있는 파일이 없을 수 있습니다. 지속 가능한 제품 계약(durable product contract)은 더 길습니다:

요청 → 영속적인 작업(persisted job) → 제공자 작업(provider work) → 저장된 아티팩트(stored artifact) → 인증된 다운로드 → 파일 열림

아래는 편집 가능한 Word 문서를 위해 저희가 사용하는 프로덕션 계약입니다. 3Stone API 키와 자금이 충전된 API 잔액이 필요합니다. 이 키는 환경 변수에 보관하고, 절대 소스 컨트롤에 붙여넣지 마십시오.

1. 아티팩트 요청 제출하기

export THREESTONE_API_KEY="your-key-from-developer-mode"

curl -sS https://one.3stoneai.com/v1/documents \
...

새로 수락된 요청은 지속적인 job_id와 queued 같은 상태를 가진 HTTP 202 응답을 반환합니다.

{
  "object": "response",
  "capability": "documents",
...

API는 1자에서 8,000자까지의 프롬프트를 허용합니다. Idempotency key는 8~200개의 안전한 문자여야 합니다.

2. 추측하는 대신 작업(job) 상태 폴링하기

JOB_ID="step-1에서 얻은-job-id"

curl -sS "https://one.3stoneai.com/v1/jobs/$JOB_ID" \
...

동일한 계정 경계가 작업 상태 및 아티팩트 접근에 적용됩니다. 완료된 응답은 아티팩트 메타데이터를 노출하며, 내부 저장 경로와 제공자 요청 ID는 반환되지 않습니다.

최소한의 셸 루프는 다음과 같을 수 있습니다:

while true; do
  BODY=$(curl -sS "https://one.3stoneai.com/v1/jobs/$JOB_ID" \
    -H "Authorization: Bearer $THREESTONE_API_KEY")
...

3. 동일한 키로 아티팩트 다운로드하기

curl -sS "https://one.3stoneai.com/v1/jobs/$JOB_ID/artifact" \
  -H "Authorization: Bearer $THREESTONE_API_KEY" \
  --output onboarding-brief.docx

그런 다음 고객이 실제로 받는 것을 검증합니다:

file onboarding-brief.docx
unzip -t onboarding-brief.docx

이러한 확인 절차는 다운로드된 파일이 .docx 확장자로 저장된 HTML 오류 페이지가 아니라 실제 Office 패키지임을 확증합니다. 다음 단계는 제품별 검사입니다: Word나 LibreOffice에서 파일을 열고, 제목과 목록을 검사하며, 편집하고, 저장하고, 다시 열어본 후, 수정 사항이 유지되었는지 확인해야 합니다.

전체 수명 주기 개요

POST /v1/documents + Idempotency-Key
                │
                ▼
...

안전한 재시도 및 결제

멱등성(Idempotency)은 단순한 편의 기능이 아니라 청구 경계(billing boundary)의 일부입니다.

• 동일한 키를 동일한 요청과 함께 재사용하는 것은 관련 없는 중복 작업을 시작하는 대신 원래의 접수(admission)를 다시 실행합니다.
• 해당 키를 다른 페이로드와 함께 재사용하면 HTTP 409 idempotency_conflict가 반환됩니다.
• HTTP 402는 새로운 키로 재시도하기 전에 계정에 잔액이 필요함을 의미합니다.
• HTTP 429는 현재 키당 분당 60회라는 비율 제한을 강제합니다.
• 조정(reconciliation) 응답은 새로운 유료 요청을 실행할 수 있는 권한이 아닙니다. 원래의 작업 및 요청 식별자를 유지하고 불확실한 결과가 조정되도록 두어야 합니다.

저희 구현에서는 작업이 시작되기 전에 금액이 예약됩니다. 완료된 작업은 측정된 사용량에 따라 정산됩니다. 실패는 제공업체 또는 아티팩트 저장소의 결과가 불확실할 경우 최종 처리되거나 명시적인 조정 상태로 이동합니다. 이 구분은 중요합니다: 맹목적으로 새로운 멱등성 키를 생성하는 것은 불확실성을 중복 청구로 바꿀 수 있습니다.

출력 검증 방식을 변경한 수정 사항들

실제 고객의 실패 사례들은 저희가 녹색(green) 요청을 성공의 정의로 취급하는 것을 멈추도록 강요했습니다. 이제 이전에는 쉽게 평탄화되던 여러 상태들을 분리합니다:

• 컨트롤러가 요청을 수락함;
• 워커가 실제로 이를 할당받음;
• 제공업체가 응답함;
• 아티팩트가 저장됨;
• 인증된 다운로드가 의도한 미디어 타입을 반환함;
• 파일이 열리고 편집 가능한 상태를 유지함.

이러한 교훈은 DOCX를 넘어 다른 파일 형식에도 적용됩니다. 스프레드시트는 수식과 재계산되는 워크북을 필요로 합니다. 프레젠테이션은 PPTX 컨테이너 안에 있는 스크린샷이 아니라 편집 가능한 슬라이드 개체를 필요로 합니다. 미디어 작업(media job)은 요청된 오디오 동작을 포함하는 재생 가능한 내보내기(export)가 필요합니다.

저는 3Stone AI를 상당한 Codex 지원을 받아 구현 및 검증 작업을 거쳐 구축했습니다. 가장 유용한 피드백은 구체적이기 때문에 이 계약서(contract)를 공유합니다: 이 작업 모델(job model)이 통합과 복구 과정을 명확하게 하는지, 그리고 API가 어떤 아티팩트 검증 신호(artifact validation signal)를 반환하기를 원하시는지요?

현재 개발자 인터페이스(developer surface)와 지원되는 엔드포인트는 3stoneai.com/developers에 있습니다.