튜토리얼
HiAPI API로 flux-3 사용하는 방법: curl, Python 및 실행 가능한 요청 예제
이 페이지에서
HiAPI를 통해 flux-3를 사용하면 얻을 수 있는 것
flux-3는 텍스트-이미지와 이미지-이미지를 모두 처리할 수 있는 이미지 생성 모델입니다. 제품 기능, 디자인 도구 또는 내부 파이프라인을 구축하고 있다면, 정말 흥미로운 부분은 종종 모델 자체가 아니라—그것을 안정적이고 예측 가능한 인터페이스 뒤에 얼마나 깔끔하게 배치하고, 요구 사항이 변할 때 그 상태를 유지하는가입니다.
바로 여기에 집계형 API 플랫폼의 가치가 있습니다. HiAPI를 통해 flux-3를 호출한다는 것은 다음을 의미합니다:
- 한 번만 통합하면 됩니다. 단일 기본 URL, 단일 인증 방식, 그리고 사용하는 모델 간에 일관된 요청 및 응답 구조. 이후 모델을 교체하거나 비교하는 것은 코드를 다시 작성하는 것이 아니라 설정을 바꾸는 일입니다.
- 인프라 작업이 필요 없습니다. 모델 호스팅, GPU 용량 계획, 또는 자체 측 콜드 스타트 관리가 필요 없습니다. HTTP 요청을 보내고 응답을 처리하면 됩니다.
- 자격 증명을 중앙에서 관리합니다. 각 업스트림 제공자와 별도로 관계를 맺을 필요 없이, 발급하고 교체하며 권한을 제한할 API 키 하나만 있으면 됩니다.
- 통일된 오류 의미 체계를 얻습니다. 호출 뒤에 어떤 모델이 있든 상태 코드와 오류 래퍼가 동일하므로, 재시도 및 경보 로직을 재사용할 수 있습니다.
flux-3에 특정하자면, 노트북의 프로토타입에서 프로덕션 엔드포인트로 클라이언트 코드 구조를 바꾸지 않고 바로 이전할 수 있습니다. 두 가지 생성 모드—텍스트-이미지와 이미지-이미지—는 동일한 요청 구조를 공유하므로, 둘 모두를 지원하는 것은 어떤 SDK를 가져오느냐가 아니라 어떤 필드를 채우느냐에 달려 있습니다.
이 글 전체에서 다음 규칙을 사용합니다:
- 기본 URL: 계정 콘솔에 기록된 HiAPI API 엔드포인트.
- 인증:
Authorization헤더에 bearer 토큰을 담습니다. - 콘텐츠 유형: 요청 본문은
application/json을 사용하고, 이미지 입력은 페이로드 크기 제한에 따라 URL 또는 base64 인코딩 데이터 형태로 제공합니다.
키는 환경 변수에 두세요—절대 소스 관리에 커밋하지 마세요. 아래 예제는 HIAPI_API_KEY에서 키를, FLUX_MODEL에서 모델 식별자를 읽으므로 코드를 수정하지 않고도 조정할 수 있습니다.
준비가 끝났으니, 다음 섹션에서는 요청 본문 자체를 분석합니다.
요청 구조 분석: 텍스트-이미지와 이미지-이미지
하나의 flux-3 호출은 논리적으로 세 부분으로 나뉩니다: 엔드포인트 경로, 인증 헤더, 그리고 JSON 요청 본문. 요청 본문이 두 모드가 달라지는 지점이며, 이 차이를 이해하면 하나의 클라이언트를 둘 모두에 재사용할 수 있습니다.
공유 골격
모든 요청은 다음 중 일부 형태의 필드를 포함합니다:
- model — 호출할 모델; 여기서는 flux-3 식별자입니다.
- input — 생성 지시를 담는 객체.
- input.prompt — 원하는 내용을 자연어로 설명합니다. 두 모드 모두에서 필수입니다.
- 선택적 생성 설정 — 출력 크기, 종횡비 또는 스텝 수 등, 모델이 노출하는 능력에 따라 다릅니다. 필요한 것만 설정하세요; 기본값은 보통 충분히 합리적입니다.
- 선택적 비동기 제어 — 작업 실행 및 전달 방식을 바꾸는 플래그 또는 콜백(다음 섹션에서 자세히 설명).
텍스트-이미지
텍스트-이미지 모드에서 prompt는 유일한 실질적 필드입니다. 이미지를 설명하고, 선택적으로 출력 기하 구조를 제한한 뒤 제출합니다. 소스 이미지가 없으므로 모델은 최대한의 자유를 가지며—이는 프롬프트 품질이 출력 품질을 지배한다는 뜻이기도 합니다.
유용한 습관 하나: 인간 일러스트레이터에게 요구 사항을 전달하듯 프롬프트를 작성하세요. 피사체, 구도, 조명, 스타일, 그리고 모든 하드 제약(예: '이미지에 텍스트가 나타나지 않게', '피사체를 중앙에 배치') 순서로 작성합니다. 모호한 프롬프트는 스텝 수가 아무리 많아도 결과가 평범합니다.
이미지-이미지
이미지-이미지 모드에서는 프롬프트 외에 소스 이미지 필드를 추가하며, 이때 프롬프트는 처음부터 구성하는 장면이 아니라 해당 입력에 대한 변환을 설명합니다. 모델 인터페이스에 따라 이미지 URL 또는 인코딩된 이미지 페이로드를 제공하고, 출력이 소스 이미지에서 벗어나는 정도를 제어하는 강도 또는 가이던스 파라미터를 추가하는 것을 의미할 수 있습니다.
API 클라이언트 입장에서 실질적 영향은 작습니다: 동일한 엔드포인트, 동일한 인증, 동일한 input 객체—필드 하나만 더 추가됩니다. 이것이 바로 설계 목표입니다. generate() 함수는 선택적 소스 이미지를 받아 내부에서 분기를 처리하므로, 호출자는 자신이 어떤 모드를 트리거했는지 알 필요가 없습니다.
응답 구조
응답에는 작업 식별자가 포함되어야 하며, 완료 시 생성된 이미지의 위치를 담습니다. 해당 위치는 불투명한 값으로 취급하세요: 가져오거나 저장할 수는 있지만 그 내용에 대해 파싱 가정을 하지 마세요. 일부 응답은 즉시 반환되고, 일부는 작업 핸들이므로—비동기 처리를 첫날부터 설계에 포함해야 하는 이유입니다.
파라미터와 비동기 모드
생성 설정 선택
생성 설정은 품질, 지연 시간, 비용 사이의 균형입니다. 다음 원칙은 대부분의 이미지 모델, flux-3에도 적용됩니다:
- 해상도와 종횡비는 출력의 실용성과 연산 소모 모두에 영향을 미칩니다. 실제로 전달하는 크기로 생성하세요; 큰 이미지를 줄이는 것은 예산 낭비이고, 작은 이미지를 확대하는 것은 렌더링 낭비입니다.
- 스텝 수 또는 품질 제어는 충실도를 어느 지점까지 높인 뒤 평탄해집니다. 고정 프롬프트로 실측하여 이 변곡점을 찾고 거기서 멈추세요.
- 결정성 제어(사용 가능한 경우)는 재현성에 중요합니다. QA나 사용자 지원을 위해 동일 결과를 다시 렌더링해야 한다면, 설정을 출력과 함께 기록하세요.
파라미터 이름이나 허용 범위를 추측하지 마세요—콘솔의 모델 문서에서 읽고 그것을 기준으로 삼으세요. 어떤 필드가 거부되면 오류 응답이 구체적으로 어느 것인지 알려줍니다.
동기 vs. 비동기
이미지 생성은 순간적인 작업이 아닙니다. 두 가지 실행 모드가 있습니다:
동기(블로킹). 요청을 보내고 이미지가 준비될 때까지 연결을 유지합니다. 간단하며 짧은 작업, 스크립트, 사용자가 로딩 애니메이션을 바라보는 대화형 도구에 적합합니다. 하지만 취약하기도 합니다: 서버리스 함수, 로드 밸런서, 모바일 클라이언트에는 모두 시간 제한이 있어 긴 렌더링은 반드시 그중 하나에 걸립니다.
비동기(작업 기반). 요청을 제출하고 즉시 식별자를 받은 뒤, 상태 엔드포인트를 폴링하거나 콜백을 받아 작업이 완료를 보고할 때까지 기다립니다. 다음 상황에서는 이 모드를 선택하세요:
- 엄격한 실행 시간 상한이 있는 서버리스 및 엣지 런타임.
- 대량의 렌더를 병렬로 제출해야 하는 배치 작업.
- 즉시 제어권을 반환하고 진행 상황을 스트리밍으로 푸시하려는 모든 사용자 상호작용 흐름.
클라이언트를 비동기 중심으로 설계하고, 간단한 시나리오는 동기 편의 메서드로 감싸세요. 반대로 하면—비동기를 블로킹 클라이언트에 억지로 밀어 넣으면—좋은 결과가 거의 나오지 않습니다.
폴링할 때는 고정된 긴밀한 루프 대신 상한이 있는 지수 백오프를 사용하고, 총 대기 시간 상한을 설정하며, 결코 종료 상태에 도달하지 않는 작업은 경보할 가치가 있는 오류로 취급하세요.
실행 가능한 curl 요청
터미널에서 시작하세요; 원시 HTTP 교환이 명확해지면 코드 버전은 간단합니다.
1. 환경 설정
export HIAPI_API_KEY="your-key-here"
export FLUX_MODEL="your-flux-3-model-id"
export HIAPI_BASE="https://your-hiapi-endpoint"
모델 식별자를 변수에 두세요—나중에 모델을 바꾸는 것은 한 줄만 수정하면 됩니다.
2. 텍스트-이미지 요청 보내기
curl -sS -X POST "$HIAPI_BASE/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "'"$FLUX_MODEL"'",
"input": {
"prompt": "A minimal studio photograph of a ceramic mug on a concrete surface, soft side light, shallow depth of field"
}
}'
-sS 플래그는 출력을 깔끔하게 유지하면서도 오류를 표시합니다. 실행 전에 콘솔에 기록된 엔드포인트와 정확한 경로를 확인하세요—경로에는 버전이 있으므로 문서를 기준으로 삼으세요.
3. 반환 내용 읽기
응답을 포매터로 출력하여 읽기 쉽게 만드세요:
... | python -m json.tool
두 가지에 주목하세요: 작업 식별자, 그리고 이미지 위치 또는 작업이 아직 실행 중임을 알려주는 상태 필드. 상태가 보이고 이미지가 보이지 않는다면 비동기 경로에 있으므로—식별자를 기록하고 폴링으로 전환하세요.
4. 이미지-이미지 시도
input 객체에 소스 이미지를 추가하고 나머지는 그대로 두세요:
curl -sS -X POST "$HIAPI_BASE/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "'"$FLUX_MODEL"'",
"input": {
"prompt": "Reinterpret as a watercolor painting, keep the composition and shadows intact",
"image": "https://example.com/source.jpg"
}
}'
요청이 필드 하나만 다르므로, 첫 성공 호출만으로 통합의 대부분을 검증한 셈입니다. 나머지—재시도, 저장, UI—는 평범한 애플리케이션 작업입니다.
Python에서의 동일한 요청
curl 호출은 그대로 번역할 수 있습니다. 아래는 일회성 스크립트가 아닌 작고 재사용 가능한 클라이언트입니다.
import os
import time
import requests
BASE = os.environ["HIAPI_BASE"]
MODEL = os.environ["FLUX_MODEL"]
HEADERS = {
"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
"Content-Type": "application/json",
}
def generate(prompt, image=None, timeout=60):
"""Submit a flux-3 generation job. Pass image= for image-to-image."""
payload = {"model": MODEL, "input": {"prompt": prompt}}
if image:
payload["input"]["image"] = image
resp = requests.post(
f"{BASE}/v1/images/generations",
headers=HEADERS,
json=payload,
timeout=timeout,
)
resp.raise_for_status()
return resp.json()
몇 가지 의도적인 선택:
- 하나의 함수, 두 가지 모드.
image파라미터가 동작을 전환하므로 호출자는 분기할 필요가 없습니다. - 명시적 시간 제한.
requests의 기본 동작—무한 대기—은 작업자 스레드 풀을 망가뜨리는 방식입니다. raise_for_status(). HTTP 계층 실패를 예외로 드러내어 한 곳에서 잡을 수 있게 합니다.
폴링 도우미 추가
응답이 완료된 이미지 대신 작업 식별자를 담고 있을 때, 기다리세요:
def wait_for(job_id, timeout=300, initial=1.0, factor=1.6, cap=15.0):
deadline = time.monotonic() + timeout
delay = initial
while time.monotonic() < deadline:
r = requests.get(
f"{BASE}/v1/jobs/{job_id}", headers=HEADERS, timeout=30
)
r.raise_for_status()
data = r.json()
if data.get("status") in ("succeeded", "failed"):
return data
time.sleep(delay)
delay = min(delay * factor, cap)
raise TimeoutError(f"job {job_id} did not finish in {timeout}s")
문서에 기록된 응답 구조에 맞춰 상태 필드 이름을 조정하세요. 구조 자체—상한이 있는 백오프, 하드 마감 시간, 종료 상태 확인—가 핵심이며, 모델을 교체해도 그대로 적용됩니다.
조합하기
if __name__ == "__main__":
result = generate(
"A minimal studio photograph of a ceramic mug, soft side light"
)
if "id" in result and not result.get("output"):
result = wait_for(result["id"])
print(result)
다음으로 자체 재시도 및 로깅 계층으로 generate를 감싸면, 통합이 프로덕션 수준의 형태를 갖추게 됩니다.
비용 관리와 일반적인 오류
지출을 예측 가능하게 유지하기
이미지 생성은 요청당 과금되며, 구체적 금액은 모델과 설정에 따라 다릅니다—가정을 하드코딩하지 말고 콘솔의 실시간 가격 패널을 확인하세요. 예산을 지키는 열쇠는 엔지니어링 규율입니다:
- 자체 코드에서 사용자별 및 작업별 상한을 설정하세요. 플랫폼은 계정 수준 제한을 시행합니다; 애플리케이션은 제품 수준 제한을 시행하여 단일 폭주 클라이언트가 계정을 고갈시키지 않도록 해야 합니다.
- 적극적으로 캐시하세요. 정규화된 프롬프트에 설정을 더한 값을 해시하여 저장된 출력을 재사용하세요. 편집기와 미리보기 시나리오에서는 동일 요청이 흔합니다.
- 전달 해상도로 생성하세요. 표시할 크기로 렌더링하고, '큰 이미지로 렌더링 후 축소'라는 고비용 패턴을 피하세요.
- 재생성은 명시적 사용자 작업 뒤에 두세요. 프롬프트 입력 상자에서 키를 칠 때마다 자동 재생성하는 것은 가장 흔한 의도치 않은 비용 배증 요인입니다.
- 모든 호출의 모델, 설정, 지연 시간을 기록하세요. 이것이 없으면 어떤 기능이 비용이 높은지 판단할 수 없습니다.
- 제출 전에 입력을 검증하세요. 빈 프롬프트나 비정상적으로 긴 프롬프트를 클라이언트에서 거부하여 반드시 실패할 요청에 비용을 지불하지 않도록 하세요.
실제로 마주칠 장애 디버깅
다음 체크리스트를 순서대로 하나씩 확인하세요; 대부분의 사고를 해결할 수 있습니다.
- 401 / 403 — 인증. 키가 요청이 실제로 실행되는 환경에 로드되었나요? 셸에서 사용 가능한 키가 컨테이너에는 없을 수 있습니다.
Bearer접두사와 헤더 이름이 정확한지 확인하세요. - 404 — 경로 또는 모델 오류. 버전이 붙은 경로와 모델 식별자는 모두 변합니다. 문서에 기록된 엔드포인트와 문자 단위로 대조하세요.
- 422 / 400 — 페이로드 거부. 오류 본문이 문제가 된 필드를 지시합니다. 흔한 용의자: 유형 오류,
prompt누락 또는 지원되지 않는 파라미터. 선택적 설정을 제거하고 다시 보내 문제를 격리하세요. - 429 — 속도 제한 발생. 지터를 더한 백오프로 재시도하세요; 루프에서 즉시 재시도하지 마세요. 재시도가 무의미한 계정 수준 할당량 고갈과 구분해야 합니다.
- 시간 초과. 요청이 너무 오래 걸린다면 폴링해야 할 곳에서 블로킹한 것입니다. 비동기 흐름으로 전환하고 의도적으로 클라이언트 시간 제한을 설정하세요.
- 작업이 pending에 멈춤. 마감 시간을 두고 폴링하고, 시간 초과는 무한 대기가 아니라 경보할 가치가 있는 실패로 취급하세요.
전체 체크리스트를 하나로 묶는 습관: 상태 코드만이 아니라 전체 오류 본문을 기록하세요. 오류 본문은 보통 어떤 필드나 제한이 문제인지 정확히 알려주므로, 30분의 조사를 한 줄 수정으로 바꿉니다.
먼저 curl 호출을 통과시키고, 위 클라이언트로 이식하고, 폴링과 오류 처리를 한 곳에 모으세요—나머지 통합은 평범한 애플리케이션 코드입니다. 현재 모델 능력과 가격에 대해서는 HiAPI 콘솔의 flux-3 문서와 가격 패널을 참고하세요.