이미지 API가 코인으로 과금되는 이유 (그리고 실패 시 스스로 환불되는 이유)

Fellowi Images 위에 공개 API를 만들면서, 문서에 기능으로 드러나지 않는 몇 가지 결정을 내려야 했습니다 - 그런 결정은 오히려 문제가 없다는 형태로 드러납니다. 이 글에서는 그 이유를 설명합니다. 왜 코인으로 과금하는지, 생성이 실패하면 어떤 일이 일어나는지, 그리고 문서에 적힌 몇 가지 숫자 (속도 제한, 보관 일수)가 보이는 것만큼 중요하지 않은 이유까지요.

구독이 아니라 코인

이미지 생성에는 호출마다 실제로 변동하는 비용이 듭니다. 월 정액 구독은 한 달에 다섯 장만 생성 하는 사람에게는 과도하게 청구하고, 오백 장을 생성하는 사람에게는 부족하게 청구합니다 - 여기에 깔끔하게 들어맞는 좌석 수나 요청 한도 같은 건 없습니다. 코인을 쓰면 비용이 사용량을 그대로 따라갑니다. 실제로 생성한 만큼만 지불하고, 그 이상은 없습니다. 코인은 만료되지 않고 해지할 것도 없어서 결제 주기를 놓칠 걱정도 없습니다 - 필요할 때 패키지를 구매하면, 쓸 때까지 지갑에 그대로 남아 있습니다.

실패한 생성은 스스로 환불된다

생성이 시간 초과되거나 이미지가 완성되기 전에 거부되면, 그때 사용한 코인은 자동으로, 즉시 돌아옵니다. 이는 고객 지원에 문의해서 처리하는 것이 아니라 시스템 자체의 속성입니다 - 받지 못한 이미지에 대해 요금이 청구되는 일은 절대 없습니다. 저희는 이를 단순한 배려가 아니라 신뢰성 보장으로 취급합니다.

모든 실패는 의도적으로 적게 유지된 네 가지 코드 중 정확히 하나로 귀결됩니다.

• TIMEOUT - 생성이 너무 오래 걸려 중단됨.
• MODERATION_REJECTED - 요청이 콘텐츠 정책을 위반함.
• VENDOR_ERROR - 생성 쪽에서 무언가 실패함.
• UNKNOWN - 앞의 세 가지에 해당하지 않는 모든 것을 위한 진짜 포괄 코드.

코드 종류를 작고 고정되게 유지한 것은 의도적인 선택입니다 - 나중에 바뀔 수도 있는 자유 형식의 오류 문자열을 패턴 매칭하는 대신, 실제로 switch 문을 작성할 수 있는 대상으로 만들고 싶었기 때문입니다.

이미지는 30일 후 만료된다

생성된 이미지 데이터는 30일 동안 보관됩니다. 그 이후에도 생성 기록 자체는 남아 있습니다 - 목록 엔드포인트에는 여전히 언제, 얼마의 비용으로 생성이 일어났는지가 표시됩니다 - 하지만 실제 이미지 콘텐츠를 요청하면 HTTP 410 Gone이 반환됩니다. 이는 숨겨진 것이 아니라 명확한 저장 비용 절충입니다. 30일이 지나서도 이미지를 보관하고 싶다면 다운로드해서 직접 저장하세요. 생성 기록 자체를 조용히 삭제하는 일은 없으며, 사라지는 것은 데이터뿐입니다.

속도 제한은 진짜 한계가 아니다

API 키의 분당 속도 제한(기본값으로 생성은 분당 20회, 읽기는 분당 120회)은 남용을 억제하기 위해 존재하는 것이지, 실제로 생성할 수 있는 이미지 수를 제한하는 요소가 아닙니다. 진짜 한계는 Fellowi 코인 잔액입니다 - 코인이 있는 한, 그 속도 범위 내에서 얼마든지 사용할 수 있습니다. 잔액이 허용하는 것보다 더 엄격한 예산을 원한다면, 키마다 스스로 설정하는 선택적 일일 코인 한도를 둘 수도 있습니다 - 저희가 아니라 당신 자신의 비용 관리를 위한 것입니다.

되찾을 수 없는 키

API 키는 생성 시 딱 한 번만 표시됩니다. 그 이후에는 저희 쪽에는 해시 값과 짧은 미리보기만 저장됩니다 - 제품 내 다른 모든 비밀 정보와 동일한 방식입니다. 키를 분실하면 새로 생성하면 됩니다. 복구 절차는 없습니다. 저희 쪽에 애초에 복구할 수 있는 것이 남아 있지 않기 때문입니다.

같은 지갑, 같은 가격

API와 웹 앱은 정확히 같은 Fellowi 코인 잔액에서, 화질 등급별로 정확히 같은 가격을 지불합니다 - 표준 화질 40코인, 고화질 60코인입니다. 별도의 "API 요금제"는 존재하지 않습니다. 이는 의도적인 설계입니다 - 어느 경로로 생성하든 비용은 예측 가능합니다.

실제 요청/응답 형식과 동작하는 코드 샘플은 API 빠른 시작 가이드를 참고하시거나, API 콘솔로 바로 이동해 키를 생성해 보세요.