Black Forest Labs튜토리얼
FLUX.1 Kontext [pro] API 사용법
Node.js, Python, cURL로 FLUX.1 Kontext [pro] API를 단계별로 사용하는 튜토리얼입니다. 텍스트 → 이미지 작업을 제출하고 상태를 폴링하거나 웹훅을 받은 다음 image을 다운로드하세요. 아래 예제 비용은 $0.035입니다.
- 엔드포인트
- 2
- 텍스트 → 이미지 · 이미지 편집
- 요청 예시
- $0.035
- 텍스트 → 이미지
- 언어
- 3
- Node.js · Python · cURL
- 실패한 생성
- $0
- 자동 환불
API 키 발급
계정을 만든 뒤 크레딧을 충전하고 Dashboard → API keys에서 키를 만드세요. 키를 CHEAPERGEN_API_KEY 서버에 보관하세요. 모든 요청에서 bearer token으로 전달합니다. 형식으로 저장하세요.
FLUX.1 Kontext [pro] 엔드포인트 선택하기
텍스트 → 이미지 작업 제출하기
이 프로그램은 작업을 제출하고 3초마다 폴링해 완료될 때까지 기다린 뒤 image URL을 출력합니다. 프롬프트와 설정을 바꿔 사용하세요.
const API = "https://cheapergen.com/api/v1";
const headers = {
Authorization: `Bearer ${process.env.CHEAPERGEN_API_KEY}`,
"Content-Type": "application/json",
};
// 1. Submit the job
let job = await fetch(`${API}/run/bfl/flux-kontext-pro/text-to-image`, {
method: "POST",
headers,
body: JSON.stringify({
"prompt": "비 내리는 바깥 풍경이 보이는 창가 좌석, 따뜻한 조명과 아늑한 독서 공간, 어린이 그림책 삽화 스타일",
"aspect_ratio": "1:1"
}),
}).then((r) => r.json());
// 2. Poll until it finishes (or pass webhook_url and skip polling)
while (job.status === "queued" || job.status === "running") {
await new Promise((r) => setTimeout(r, 3000));
job = await fetch(`${API}/generations/${job.id}`, { headers }).then((r) => r.json());
}
console.log(job.status === "succeeded" ? job.output.images[0].url : job.error);중요한 매개변수 설정하기
bfl/flux-kontext-pro/text-to-image 설정:
| 매개변수 | 형식 · 기본값 | 기능 | 가격 영향 |
|---|---|---|---|
| aspect_ratio | string (enum) · 1:1 | 출력 이미지 비율입니다. 1:1 · 4:3 · 3:4 · 16:9 · 9:16 · 3:2 · 2:3 · 21:9 · 9:21 | 예 |
| seed | integer | 같은 시드와 설정을 사용하면 결과를 재현할 수 있습니다. 비워 두면 무작위로 설정됩니다. | 없음 |
다른 FLUX.1 Kontext [pro] 엔드포인트도 각자 입력 필드만 다를 뿐 같은 요청 형식을 사용합니다:
POST /api/v1/run/bfl/flux-kontext-pro/edit
{
"prompt": "재킷을 빨간 가죽으로 바꾸고 밤으로 바꿔 주세요. 얼굴과 자세는 그대로 유지하세요.",
"image_urls": [
"https://cdn.cheapergen.com/samples/portrait.jpg"
],
"aspect_ratio": "1:1"
}결과 가져오기
작업 상태는 queued에서 running을 거쳐 succeeded, failed, canceled 중 하나가 됩니다. GET /api/v1/generations/{id}를 폴링하거나 제출 시 webhook_url을 전달하면 결과를 POST로 보내 드립니다. 출력 파일을 다운로드해 직접 저장하세요.
200 — 성공
{
"id": "gen_8c2QmX1nq0k4",
"object": "generation",
"model": "bfl/flux-kontext-pro",
"endpoint": "bfl/flux-kontext-pro/text-to-image",
"mode": "text-to-image",
"status": "succeeded",
"input": {
"prompt": "비 내리는 바깥 풍경이 보이는 창가 좌석, 따뜻한 조명과 아늑한 독서 공간, 어린이 그림책 삽화 스타일",
"aspect_ratio": "1:1"
},
"output": {
"images": [
{
"url": "https://cdn.cheapergen.com/outputs/gen_8c2Q-0.png",
"content_type": "image/png",
"width": 2048,
"height": 2048
}
]
},
"error": null,
"cost": {
"amount_usd": 0.2255,
"currency": "usd",
"estimated": false,
"official_usd": 0.264,
"list_price_source": "official",
"list_price_label": "Official",
"saved_usd": 0.0385
},
"source": "api",
"created_at": "2026-10-15T09:21:04Z",
"started_at": "2026-10-15T09:21:06Z",
"completed_at": "2026-10-15T09:22:31Z"
}실행 전 요청 가격 확인
견적 엔드포인트는 무료이며 API 키가 필요 없습니다. 전송한 입력값을 기준으로 가격, 공식 가격, 할인율을 반환합니다.
curl -X POST https://cheapergen.com/api/v1/quote/bfl/flux-kontext-pro/text-to-image \
-H "Content-Type: application/json" \
-d '{"prompt":"비 내리는 바깥 풍경이 보이는 창가 좌석, 따뜻한 조명과 아늑한 독서 공간, 어린이 그림책 삽화 스타일","aspect_ratio":"1:1"}'| 상태 | 코드 | 의미 |
|---|---|---|
| 400 | invalid_request | 매개변수가 누락되었거나 허용 범위를 벗어났습니다. 오류 메시지에 해당 항목이 표시됩니다. |
| 401 | unauthorized | API 키가 없거나 형식이 잘못되었거나 폐기되었습니다. |
| 402 | insufficient_balance | 견적 가격을 결제할 크레딧이 부족합니다. 충전하거나 자동 충전을 설정하세요. |
| 429 | rate_limited | 요청이 너무 많거나 진행 중인 생성이 너무 많습니다. 잠시 기다린 뒤 백오프를 적용해 다시 시도하세요. |
| 502 | upstream_error | 모델 제공업체 오류입니다. 보류 금액은 환불되며 다시 시도할 수 있습니다. |
| 503 | model_unavailable | 현재 정상 경로가 없습니다. 나중에 다시 시도하거나 다른 모델을 선택하세요. |
자주 묻는 질문
FLUX.1 Kontext [pro] API 관련 질문
아니요. API는 JSON을 사용하는 일반 HTTPS 방식이므로 이 페이지의 Node.js(fetch) 및 Python(requests) 예제만으로 실행할 수 있습니다. HTTP 요청을 보낼 수 있는 모든 언어를 사용할 수 있습니다.
네. 요청 본문에 "webhook_url"을 추가하면 CheaperGen-Signature 헤더(timestamp와 원본 본문의 HMAC-SHA256)로 서명해 완료된 생성 결과를 POST로 보냅니다. GET /api/v1/generations/{id}를 폴링해도 됩니다.
공개 URL을 "image_urls"에 전달하세요. 공개 URL이 없는 파일은 POST /api/v1/uploads로 먼저 업로드하면 요청에 사용할 URL이 반환됩니다.
텍스트 → 이미지의 시작 가격은 $0.0348 이미지당입니다. 이 페이지의 요청 예제는 $0.035공식 가격보다 공식 가격 낮게, 최대 13%입니다. 생성 실패는 자동 환불됩니다.