이미지는 생성되는 순간이 아니라, 사용자가 정확히 기대했던 파일을 받았을 때 비로소 제품을 통과하게 됩니다. 올바른 url과 명시된 image_format을 포함한 API 응답만으로는 클라이언트에게 충분한 결과가 아닙니다. 응답과 사용자의 화면 사이에는 최소 네 개의 외부 레이어, 즉 귀하의 스토리지(storage), 귀하의 변환(transformations), 귀하의 UI, 그리고 다운로드 메커니즘이 존재하기 때문입니다. 이들 각각은 조용히 형식을 변경하거나, 알파 채널(alpha channel)을 잘라내거나, 메타데이터(metadata)를 삭제할 수 있습니다.

다음은 Recraft API의 하나의 엔드 투 엔드(end-to-end) 경로인 생성, 저장, 변환, 표시 및 다운로드에 대한 분석입니다. 이 작업의 목적은 생성 기능을 다시 한번 찬양하는 것이 아니라, 체인의 가장 마지막 단계인 사용자 측에서 자산(asset)의 어떤 속성들이 검증되는지, 그리고 왜 API 출력 단계에서의 검증만으로는 불충분한지를 정의하는 것입니다.

먼저 범위를 명확히 하겠습니다. Recraft의 공식 문서(2026-07-18 기준 접근 가능)는 인증, 엔드포인트(endpoint), 파라미터(parameters), 가격, 제한 및 라이선스를 설명하며, 이는 외부적인 사실입니다. 반면, 특정 스토리지, 특정 변환, 특정 UI의 동작은 실행 전까지는 알 수 없습니다. 이 텍스트에 언급된 경로의 어떤 단계도 "이미 완료된" 것이 아닙니다. 이는 귀하가 자신의 스탠드(stand)에서 수행해야 할 방법론이지, 완료된 테스트에 대한 보고서가 아닙니다.

Recraft API에 대한 단일 요청이 확인하는 것

API가 실제로 보장하는 것부터 시작하겠습니다. 액세스는 베어러 토큰(bearer-token)을 통해 활성화됩니다. 키는 계정 설정에서 생성되며 API 유닛(API units)의 양수 잔액이 필요합니다. 모든 REST 호출은 Authorization: Bearer RECRAFT_API_TOKEN 헤더와 함께 기본 주소인 https://external.api.recraft.ai/v1로 전송됩니다. 이는 문서화된 계약(S1)이며, 이 단계에서 오류가 발생하기는 어렵습니다. 키가 유효하고 잔액이 있거나, 아니면 요청이 거부되거나 둘 중 하나입니다.

Recraft API의 생성 엔드포인트 POST /v1/images/generations는 핵심 역할을 하지만, 이 코어 기능이 파일이 저장소에 도달하거나, 변환되거나, 사용자 인터페이스(UI)에서 어떻게 처리될지는 책임지지 않습니다. 해당 엔드포인트는 model 필드(예: recraftv4, recraftv4_1, recraftv4_1_pro 및 이들의 _vector 변형), `

저장에 관한 중요한 세부 사항입니다. Recraft (S5)의 조건에 따르면, 서비스는 API를 통해 생성된 이미지를 응답을 보낸 후 기본적으로 저장하지 않습니다. 서버 측 저장은 별도의 파라미터를 통해 활성화되며, 보유 기간이 제한되어 있습니다. 실질적인 결론은 다음과 같습니다: 여러분의 트래스 (trace)에서 "저장소"는 거의 항상 S3 호환 버킷 (S3-compatible bucket), CDN 또는 로컬 디스크와 같은 여러분 자신의 인프라가 됩니다. 이 단계에서 포맷의 보존에 대한 책임은 Recraft가 아닌 여러분에게 있습니다.

여기에 전달 방식의 분기점이 숨어 있습니다. response_format 값은 전달 메커니즘 (S3)을 결정합니다: "url"은 외부 요청을 통해 파일을 가져와야 하는 링크를 반환하고, "b64_json"은 응답 본문에 파일을 base64 형식으로 직접 반환합니다. 이 선택은 트래스의 어느 단계가 실제로 네트워크를 부하 시키는지, 아니면 프로세스의 메모리를 부하 시키는지를 문자 그대로 결정합니다. url을 사용하면 사용자에게 도달하기 전 별도의 네트워크 다운로드 단계가 발생하며, b64_json을 사용하면 파일이 먼저 메모리에 통째로 올라가므로 인코딩 과정에서 아무것도 손실되지 않도록 주의해서 디코딩하고 기록해야 합니다.

한 번의 실행(run)으로 검증할 수 있는 가설은 다음과 같습니다: API 응답과 최종 다운로드 사이에서 동일한 에셋 (asset)이 최소한 하나 이상의 요구되는 속성을 변경한다는 것입니다. 가장 흔한 경우는 포맷 (예: 평면 배경에서 알파 채널이 손실되면서 CDN에서 PNG가 WebP로 재인코딩되는 경우) 또는 메타데이터 (변환 과정에서의 EXIF/ICC 스트립)입니다. 실행 전까지는 이것이 사실이 아닌 가설일 뿐이지만, 이 가설은 각 노드(node)에서 정확히 무엇을 기록해야 하는지를 설정해 줍니다.

트래스 끝단에서 속성을 고정하는 방법

다운로드 단계에서는 파일의 특정 바이트를 확인해야 합니다. 즉, 실제 컨테이너 포맷, 픽셀 크기, 바이트 길이, 해시(hash)와 같은 세 가지에서 네 가지 측정 가능한 속성을 추출해야 합니다. 만약 투명도가 있는 PNG를 요청했는데 결과물로 알파 채널이 없는 JPEG를 받았다면, API 응답은 "정상(green)"이었을지라도 제품은 망가진 것입니다.

response_format: "url" 설정 시 다운로드 노드를 위한 최소한의 Python 픽스처 (fixture):

import requests, hashlib
from io import BytesIO
from PIL import Image
...

동일한 스냅샷을 두 번 찍습니다. 하나는 저장소 직후에, 다른 하나는 파일이 당신의 변환(transformation) 과정과 UI를 거쳐 사용자에게 다운로드된 후에 찍습니다. 이 두 스냅샷 사이의 차이가 바로 통합(integration)이 적합한지에 대한 답입니다. 만약 format이나 mode가 의도하지 않게 변경되었다면, 특정 노드를 수정하기 전까지 해당 통합은 부적합한 것으로 간주됩니다.

여기서부터 상업용 이미지 기능에 대해 제가 옳다고 생각하는 인수 기준 (acceptance criteria)이 도출됩니다. 통합은 첫 번째 성공적인 200 OK 직후가 아니라, 다운로드된 파일의 해시(hash)와 형식이 기대치와 일치하는지 최종 전달(end-to-end delivery)을 확인한 후에야 비로소 적합한 것으로 간주됩니다. 이는 저의 규범적 입장이며 Recraft 문서의 항목이 아니기에, 저는 이를 의도적으로 구분합니다.

Recraft API의 비용 및 제한 사항

경로(pipeline)를 설계하는 단계에서부터 경제성을 염두에 두어야 합니다. 왜냐하면 모든 보조 단계는 각각 별도의 유료 요청이기 때문입니다.

과금 방식은 선불 방식이며, 소멸되지 않고 환불되지 않는 "API units"로 구성됩니다. 환율은 1,000 units당 $1 (S2) 기준입니다. 래스터(raster) 생성 비용은 모델 버전에 따라 이미지당 $0.022에서 $0.25 사이이며, 벡터(vector) 생성은 $0.044에서 $0.30 사이입니다. 보조 작업은 개별적으로 과금됩니다: crisp upscale $0.004, 벡터화 (vectorization) $0.01, 배경 제거 (background removal) $0.01, erase region $0.002, creative upscale $0.25, 프롬프트 강화 (prompt enhancement) $0.01. 만약 당신의 경로 내부 변환 과정에서 upscale이나 벡터화를 호출한다면, 그것은 "무료 후처리 (post-processing)"가 아니라 각 에셋(asset)마다 청구되는 비용 항목이 됩니다.

별도로 제한 사항이 있습니다. Recraft의 조건은 구매한 유닛 (units) 패키지나 요금제 (S5)와 관계없이 계정당 API 사용량을 분당 100회 요청 (requests)으로 제한합니다. 이 제한은 개별 엔드포인트 (endpoint) 호출이 아니라 api recraft 계정 전체에 고정되어 있습니다. 따라서 트래스 (trace) 내부의 보조적인 변환 과정에서 사용자 에셋 (asset) 하나당 2~3회의 호출이 발생한다면, 제품의 실제 처리량 (throughput)은 그 수치만큼 나누어지게 됩니다. 솔직히 말씀드리자면, 이 제한과 저장 규칙은 API 레퍼런스가 아닌 일반 약관에서 발견되었으며, Recraft는 요금제나 엔터프라이즈 (enterprise) 예외 사항을 별도로 공지할 수 있습니다. 그러므로 분당 100회 요청 (100 req/min)을 보편적인 규칙으로 선언하기 전에, 본인의 실제 플랜에서 이를 반드시 재확인하십시오.

Recraft는 달러로 선불 유닛 (units)을 결제하며, 외화 카드가 없는 팀에게는 API 자체의 품질과는 무관하게 별도의 불편함이 됩니다. 만약 트래스 (trace) 내에서 Recraft와 함께 채팅 또는 텍스트 모델이 사용된다면, 이 인접한 시나리오를 위한 다른 경로가 있습니다. 이미 OpenAI 또는 Anthropic 프로토콜을 사용할 줄 아는 클라이언트는 키 (key)와 base_url 교체만으로 provod.ai에 연결할 수 있습니다. 이를 통해 해외 카드나 VPN 없이도 루블화 카드, SBP 또는 계좌 이체를 통해 잔액을 충전할 수 있으며, 모델 가격은 제공업체의 공식 가격에 추가 마진 없이 적용됩니다. 이것은 Recraft API 호출을 대체하는 것이 아니라 인접한 작업을 위한 별도의 경로입니다. 즉, Recraft 자체는 여전히 직접 호출하며 트래스 (trace)는 직접 검증하게 됩니다.

다운로드한 파일의 소유권은 누구에게 있는가?

에셋 (asset)에는 픽셀뿐만 아니라 그에 대한 권리도 있으며, 이 또한 확인해야 할 속성입니다. 여기에는 잘못된 키 (key)로 확인하기 쉬운 갈림길이 존재합니다.

조건(S5)에 따라, 참가자는 API를 통해 생성된 에셋(assets)에 대한 완전한 소유권과 저작권을 유지하며, API 서비스 자체에 대한 라이선스는 문자 그대로 "비독점적이고(non-exclusive), 제한적이며(limited), 양도 불가능하고(non-transferable), 서브라이선스 부여가 불가능하며(non-sublicensable), 할당 불가능하고(non-assignable), 자유롭게 취소 가능한(freely revocable)" 것으로 기술되어 있습니다. API를 통해 생성된 에셋은 Recraft 자체의 학습 파이프라인 (training pipeline)에서 제외되며, 제3자의 AI 시스템 학습에 사용될 수 없습니다. 이는 상업적 기능 측면에서 매우 중요한 요소입니다. 즉, 사용자가 다운로드한 파일은 완전한 상업적 권리를 가진 생성물의 소유자에게 귀속됩니다.

하지만 액세스 티어 (access tier, S4)라는 함정이 존재합니다. 웹 애플리케이션을 통한 무료 플랜에서의 생성물은 개인적 비상업적 라이선스와 함께 Recraft의 소유로 남는 반면, 유료 및 API 액세스는 완전한 상업적 소유권을 부여합니다. 여기서 실질적인 리스크가 발생합니다. 만약 테스트 계정의 라이선스 상태를 API 키 자체가 아니라 웹 애플리케이션을 통해 확인한다면, 실제 프로덕션 경로 (production route)에서 적용되는 권한과 다른 권한을 확인하게 될 수 있습니다. 따라서 라이선스는 포맷과 마찬가지로, 에셋이 실제로 사용자에게 도달하는 것과 동일한 경로에서 확인해야 합니다.

이 테스트가 해결하지 못하는 것

하나의 경로가 모든 기기, 브라우저 및 변환 (transformations)에 대한 검증을 대신할 수는 없습니다. 이 테스트는 가능한 모든 제품 빌드 (product builds)가 아니라, 특정 스토리지 (storage), 특정 처리 라이브러리 (processing library), 특정 UI를 가진 특정 구성의 속성을 보여줄 뿐입니다. 이는 방법론 자체의 내재된 한계이며, 단 한 번의 실행 결과를 보편적인 보증으로 간주해서는 안 됩니다.

방법론 자체가 실패하는 직접적인 조건들도 있습니다. 만약 5단계 중 하나라도 테스트 환경 (stand)에서 재현되지 않거나, 파일의 속성이 측정 가능한 형태로 기록되지 않거나, 혹은 필요한 티어에서 라이선스와 제한 사항이 확인되지 않는다면, 해당 트레이스 (trace)는 신뢰할 수 없으며 그 결론을 사용할 수 없습니다. 이 경우 테스트를 통과한 것처럼 가장할 것이 아니라, 방법론을 수정해야 합니다.

마지막으로, 문서가 모든 것을 기록하고 있지는 않습니다. 특정 모델에 대한 픽셀 상한선은 가이드북에 "1MP 대 4MP"라는 일반적인 차이 외에는 명시적으로 정의되어 있지 않습니다. 따라서 구체적인 size 제한은 일반적인 기대치에 의존하지 말고, 요청 시점의 실제 Swagger/OpenAPI 스키마에서 가져와야 합니다. Recraft는 모델 버전(확인 날짜 기준으로 V3, V4, V4.1, V4.1 Pro가 존재했음)을 자주 출시하므로, 정확한 가격과 기본 모델 별칭(alias)은 2026-07-18 이후로 고정된 것으로 간주하지 말고 반드시 최신 가격 페이지에서 다시 확인하십시오.