개요
FLUX는 독일에 기반을 둔 Black Forest Labs(BFL)의 대표 이미지 생성 모델 패밀리입니다. 최신 FLUX.2 세대는 1초 미만부터 4MP 플래그십 품질까지 5개 티어를 제공하며, 이미지 편집용 이전 세대 FLUX.1 Kontext와 함께 총 7개의 활성 모델이 있습니다. 레거시 FLUX.1 [pro] 모델도 계속 호출할 수 있습니다. APIYI 게이트웨이는 BFL의 비동기 폴링 API를 동기식 OpenAI Images API(/v1/images/generations and /v1/images/edits)로 감싸므로, 단 base_url 변경만으로 OpenAI SDK를 그대로 사용할 수 있습니다.
텍스트-투-이미지 API
/v1/images/generations, 5개 FLUX.2 모델 전반에서 텍스트 프롬프트로 이미지를 생성합니다.이미지 편집 API
input_image 필드(융합용 참조 최대 8개, /generations를 통해), 그리고 OpenAI 호환 multipart /edits 단일 이미지 경로를 제공합니다. FLUX.2 + FLUX.1 Kontext에서 사용할 수 있습니다.과거 버전
APIYI의 FLUX를 사용하는 이유는?
BFL 공식 채널의 드롭인 대체재로, 프로덕션에서 안정성, 비용, 통합 경험 측면에 최적화되어 있습니다:OpenAI 호환 래퍼 · 코드 없는 마이그레이션
base_url를 여기에 연결하면 됩니다 — 직접 polling_url 루프를 작성할 필요가 없습니다.동시 실행 수 제한 없음 · 활성 작업 24개 초과
flux-kontext-max은 6개뿐입니다). APIYI는 요청을 게이트웨이에서 풀링하므로, 기업 사용자는 계정별 상한 없이 선형적으로 확장할 수 있습니다.동일한 가격 또는 최대 17% 할인
전 세계 무마찰 접근
api.apiyi.com에 직접 접근할 수 있습니다.완전한 모델 생태계
전문 서비스 · 엔터프라이즈 지원
주요 기능
전 속도 스펙트럼
네이티브 4MP 출력
다중 참조 퓨전
input_image ~ input_image_8에는 여러 참조(URL 또는 base64 data URL)가 포함됩니다: FLUX.2 [pro/max/flex]는 최대 8개, [klein]은 최대 4개까지 지원합니다. prompt에서는 “image 1 / image 2”처럼 참조합니다.그라운딩 검색
정확한 Hex 색상 제어
#02eb3c / #ff0088와 같은 hex 코드를 직접 입력합니다. 모델이 정확한 색상을 렌더링하므로 브랜드에 민감한 작업에서 후처리가 필요 없습니다.32K-Token 장문 prompt
타이포그래피 최적화
OpenAI SDK 바로 적용
base_url를 https://api.apiyi.com/v1로 설정하고 client.images.generate(model="flux-2-pro", ...)를 바로 호출하면 됩니다 — 코드 변경 없이.가격
이미지당 가격 — APIYI 가격 열을 참조하십시오. BFL의 공식 가격은 MP(메가픽셀) 기준이며, 1MP 이내에는 기본 요금이 있고 추가 MP마다 증분 비용이 붙습니다. APIYI의 이미지당 고정 요금은 더 예측 가능합니다.FLUX.2 시리즈 (최신 세대)
FLUX.1 Kontext 시리즈 (이미지 편집 전문)
FLUX.1 [pro] 레거시 (역사적 버전, 여전히 호출 가능)
- APIYI는 이미지당 고정 요금을 사용합니다 — 출력 MP와 관계없이 비용이 동일합니다
- 공식 가격은 MP 구간별입니다: 첫 MP에는 기본 요금이 적용되고 추가 MP마다 증분 비용이 붙습니다
- 편집 요청은 텍스트-투-이미지와 동일한 비용입니다(OpenAI gpt-image-2에서는 편집이 Vision tokens으로 과금되는 것과 다릅니다)
- klein 4B / klein 9B 오픈 웨이트는 Hugging Face에서 셀프 호스팅용으로 제공됩니다(Apache 2.0 / FLUX NCL)
- 실패한 요청(4xx / moderation 차단)은 과금되지 않습니다
기술 사양
API 엔드포인트
/generations(JSON input_image_N)을 사용합니다. /edits 엔드포인트는 단일 image 파일만 허용하며, 기존 OpenAI SDK 편집 코드를 마이그레이션할 때 가장 적합합니다.
크기(너비 / 높이) 상세
일반적인 치수
사용자 지정 크기 제약
FLUX.2는 다음 조건을 모두 만족하는 한 임의의 치수를 허용합니다:- 너비 / 높이는 16의 배수여야 합니다
- 최소 64×64
- 최대 ~4MP (예: 2048×2048 / 1920×2048 / 2048×1920)
- 속도와 비용의 균형을 위해 총합은 2MP 이하를 권장합니다
1280x720, 1920x1080, 2048x1024, 1456x1920
유효하지 않은 예시: 1000x1000 (16의 배수가 아님), 3840x2160 (4MP 초과), 32x32 (64×64 미만)
모범 사례
시나리오별로 모델 선택
flux-2-max. 프로덕션 배치 → flux-2-pro. 타이포그래피 포스터 / 인포그래픽 → flux-2-flex. 고처리량 실시간 → flux-2-klein-9b. 이미지 편집 → flux-kontext-max 또는 flux-kontext-pro.기본은 ≤ 2MP
prompt에서 인덱스로 참조 이미지 지정
input_image / input_image_2 / input_image_3의 번호는 prompt의 “image 1 / image 2 / image 3” 인덱스와 정확히 일치합니다. “image 1의 인물, image 2의 장면, image 3의 색상 팔레트”라고 말하는 편이 모델이 추측하게 두는 것보다 훨씬 더 신뢰할 수 있습니다.결과 URL을 즉시 다운로드
data[0].url은 10분 동안만 유효합니다, delivery-eu.bfl.ai / delivery-us.bfl.ai에 호스팅되며 CORS가 비활성화되어 있습니다. 프로덕션에서는 서버 측에서 다운로드하여 자체 CDN에 저장해야 합니다.타이포그래피는 flex 또는 max로 고정
flux-2-flex(타이포그래피 특화) 또는 flux-2-max(전체 품질 최고)을 우선 사용합니다. 다른 모델은 작은 텍스트가 여전히 흐려질 수 있습니다.그라운딩 검색에는 max 사용
flux-2-max에서만 지원됩니다. 다른 모델은 학습 데이터에 의존하므로 실시간 정보를 가져올 수 없습니다.클라이언트 타임아웃 60–120s
재현성을 위해 seed 고정
seed + 동일한 다른 파라미터 = 일관된 결과로, A/B 테스트와 클라이언트 검토에 유용합니다. klein은 prompt_upsampling를 지원하지 않으며, pro/max/flex는 기본적으로 꺼져 있으므로 필요할 때 사용 설정합니다.오류 코드 및 재시도
- 요청 타임아웃 60–120s(최대 180s까지 유연하게)
- 5xx 및 429에 대한 지수 백오프(재시도 2회 권장)
data[0].url를 받으면 즉시 비동기로 다운로드하십시오 — 사용자의 클릭을 기다리지 마십시오- 지원을 위해
x-request-id응답 헤더를 기록하십시오
자주 묻는 질문
URL 필드가 왜 10분 후에 만료됩니까?
URL 필드가 왜 10분 후에 만료됩니까?
delivery-eu.bfl.ai / delivery-us.bfl.ai에 10분 동안 유효한 서명된 URL로 호스팅하며, CORS는 비활성화되어 있습니다. 프로덕션 서비스는 서버 측에서 자체 OSS / CDN으로 다운로드해야 합니다. 원본 URL을 브라우저에 전달하지 말고, 사용자가 나중에 접근할 수 있다고 기대해서도 안 됩니다.APIYI는 동일한 URL 메커니즘을 그대로 상속합니다. 동작은 공식 채널과 동일합니다.공식 API는 비동기 폴링을 사용하는데, APIYI는 어떻게 동기식으로 만듭니까?
공식 API는 비동기 폴링을 사용하는데, APIYI는 어떻게 동기식으로 만듭니까?
polling_url를 Ready까지 폴링하고, 최종 result.sample URL을 data[0].url로 감싸서 반환합니다. 클라이언트 입장에서는 단일 요청-응답이며, OpenAI / GPT-Image / Nano Banana와 동일합니다.참조 이미지는 몇 장까지 보낼 수 있습니까? prompt는 어떻게 작성해야 합니까?
참조 이미지는 몇 장까지 보낼 수 있습니까? prompt는 어떻게 작성해야 합니까?
- FLUX.2 [pro/max/flex]: 최대 8장
- FLUX.2 [klein]: 최대 4장
- FLUX.1 Kontext [pro/max]: 단일 참조만 지원함(다중 이미지는 클라이언트 측 스티칭 필요)
prompt_upsampling은 무엇을 합니까? 활성화해야 합니까?
prompt_upsampling은 무엇을 합니까? 활성화해야 합니까?
prompt_upsampling=true는 prompt를 자동으로 확장하고 다듬어 줍니다(특히 짧은 prompt에 유용합니다). 하지만 원래 의도를 변경합니다. 브랜드 작업에는 끄고, 자유로운 탐색에는 켜 두십시오.제한 사항: FLUX.2 [klein]은 이를 지원하지 않습니다(전달해도 조용히 무시됩니다).grounding search는 어떻게 사용합니까?
grounding search는 어떻게 사용합니까?
flux-2-max만 이를 지원합니다. 별도의 파라미터는 필요하지 않습니다. prompt에 실시간 정보가 필요하면, 모델이 생성 전에 자동으로 웹을 검색합니다. 예:“2025년 12월 15일 NYC를 강타한 눈보라에 대한 뉴스 사진을 생성하세요”“어제 경기 스코어”, “실시간 날씨”, “역사적 사건 재현”, “최신 트렌드”에 적합합니다. 시간 민감한 내용이 없는 prompt는 검색을 트리거하지 않으며, 일반 생성으로 과금됩니다.
hex 색상을 가장 효과적으로 사용하는 방법은 무엇입니까?
hex 색상을 가장 효과적으로 사용하는 방법은 무엇입니까?
구조화된 JSON prompting이란 무엇입니까?
구조화된 JSON prompting이란 무엇입니까?
prompt 필드로 전달하십시오. 프로덕션 자동화와 템플릿 기반 배치 생성에 이상적입니다.이미지 편집에는 어떤 endpoint를 사용해야 합니까?
이미지 편집에는 어떤 endpoint를 사용해야 합니까?
- 옵션 A(권장): JSON +
input_image(~input_image_8)를/v1/images/generations에 전달 — 모든 FLUX 모델에서 동작하며 다중 참조 융합을 지원합니다 - 옵션 B:
multipart/form-data를/v1/images/edits에 전달 — 파일 필드 이름은image이어야 하며(단일 이미지), OpenAI SDK의client.images.edit()와 직접 호환되고, Kontext 시리즈에서 검증되었습니다
OpenAI 공식 SDK를 직접 사용할 수 있습니까?
OpenAI 공식 SDK를 직접 사용할 수 있습니까?
base_url를 https://api.apiyi.com/v1로 설정하십시오:openai 패키지도 동일합니다. 모든 FLUX 모델은 data[0].url를 포함한 OpenAI Images API 응답 형식을 따릅니다.실행 중인 작업을 취소할 수 있습니까?
실행 중인 작업을 취소할 수 있습니까?
요청 제한과 동시 실행 수 상한은 어떻게 됩니까?
요청 제한과 동시 실행 수 상한은 어떻게 됩니까?
flux-kontext-max는 별도로 6개로 제한됩니다.APIYI는 게이트웨이에서 풀링하므로, 엔터프라이즈 동시 실행 수는 계정별 상한에 묶이지 않습니다. 명시적인 SLA / RPM 약정이 필요하면, 전용 쿼터를 위해 저희 팀에 문의하십시오.webhook 콜백이 동작합니까?
webhook 콜백이 동작합니까?
webhook_url + webhook_secret를 지원하지만, APIYI의 OpenAI 호환 래퍼는 동기적으로 대기하며 webhook 필드를 그대로 전달하지 않습니다. 폴링은 필요하지 않으며, 요청-응답은 한 번에 끝납니다. 비즈니스상 정말로 webhooks가 필요하다면, 네이티브 비동기 채널을 활성화할 수 있도록 문의하십시오.실패한 요청도 과금됩니까?
실패한 요청도 과금됩니까?
400(파라미터 오류), 403(moderation 차단), 429(요청 제한됨)은 모두 오류를 반환하며 과금되지 않습니다. 실제로 생성 단계에 진입한 요청(200 + data[0].url)만 과금됩니다.관련 문서
- Text-to-Image Playground —
/v1/images/generations대화형 디버거 - Image Editing Playground — 다중 참조 융합 + 편집
- Historical Versions & Migration — FLUX.1 [pro] / [pro] 1.1 / Ultra / [dev]
- API Manual — 일반 사용 사양
- GPT-Image-2 Overview — OpenAI 플래그십, 4K 지원
- Seedream Overview — BytePlus 파트너십 채널