튜토리얼
HiAPI API로 flux-2/text-to-image 호출하기: curl 및 Python 튜토리얼
사용 가능한 요청 실습: 모델 식별자, 프롬프트 및 화면 비율 파라미터, 응답 필드, 오류 처리
이 페이지에서
flux-2/text-to-image가 API를 통해 노출하는 내용
첫 줄의 코드를 작성하기 전에, 당신이 정확히 무엇에 연결하고 있는지 파악하는 것이 도움이 됩니다. HiAPI에서 flux-2/text-to-image는 설치해야 하는 별도 SDK도 아니고, 별도 인증이 필요한 새 서비스도 아닙니다. 이것은 모델 식별자이며, 원하는 화면을 설명하는 프롬프트와 함께 공유 이미지 생성 엔드포인트로 전달됩니다.
이 사고 모델이 중요한 이유는 통합의 경계를 규정하기 때문입니다. 당신의 코드에 필요한 것은 세 가지입니다:
- HiAPI API용 인증 자격 증명.
- 이미지 생성 요청을 받는 엔드포인트.
model(값은flux-2/text-to-image)과prompt를 포함하는 JSON 페이로드.
그 외 모든 것—화면 비율, 출력 기본 설정, 그리고 모델이 노출하는 기타 조절 값—은 이 페이로드에 추가 필드로 존재합니다. 이것이 다른 텍스트-투-이미지 모델에서 flux-2/text-to-image로 전환할 때 보통 한 줄의 설정만 바꾸면 되는 이유이기도 합니다. 요청 봉투는 그대로 유지되고 model 값만 바뀝니다.
엔드포인트는 요청을 받아 모델을 통해 실행한 뒤, 생성된 이미지(보통 URL 또는 인코딩된 페이로드)와 작업 메타데이터를 포함한 구조화된 응답을 반환합니다. 기본 호출의 경우 별도의 작업 큐를 폴링할 필요가 없습니다—클라이언트 관점에서는 요청/응답 주기가 동기적이지만, 하부 생성에는 여전히 시간이 걸리므로 HTTP 클라이언트 타임아웃은 넉넉하게 설정해야 합니다.
이 그림을 기억하세요: 하나의 엔드포인트, 하나의 페이로드, 하나의 모델 문자열. 이 튜토리얼의 나머지 부분은 페이로드를 채우고 호출을 견고하게 만드는 과정을 다룹니다.
curl로 사용 가능한 요청 구성하기
자격 증명과 페이로드 구조가 올바른지 확인하는 가장 빠른 방법은 curl 호출 한 번입니다. Python을 건드리기 전에 터미널에서 먼저 성공 응답을 얻으세요—이것이 인증과 페이로드 문제를 언어 수준의 버그와 분리해 줍니다.
먼저 키를 환경 변수로 설정해, 셸 기록에 평문으로 남지 않게 하세요:
export HIAPI_API_KEY="your_api_key_here"
그런 다음 요청을 보냅니다:
curl -sS -X POST "$HIAPI_IMAGE_ENDPOINT" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "flux-2/text-to-image",
"prompt": "a weathered lighthouse on a granite cliff at dawn, soft fog, wide shot",
"aspect_ratio": "16:9"
}'
실행할 때 확인할 점:
- 엔드포인트와 키는 HiAPI 계정 대시보드에서 가져옵니다. 대시보드에서 엔드포인트를 복사하는 것이 다시 입력하는 것보다, 예상치 못한 곳으로 요청이 가는 가장 흔한 조용한 실패를 피할 수 있습니다.
-sS는 출력을 깔끔하게 유지하면서도 DNS나 TLS 실패 같은 curl 수준의 오류를 노출합니다.Authorization헤더는 표준 bearer 방식을 사용합니다. 변수 확장 주변에 후행 공백이나 따옴표가 없어야 합니다.Content-Type: application/json은 필수입니다. 이것이 없으면 요청 본문이 모델에 도달하기 전에 거부될 수 있습니다.
호출이 성공하면 터미널에 JSON 응답 본문이 보입니다. 포매터를 파이프로 연결해 가독성을 높이세요:
curl -sS -X POST "$HIAPI_IMAGE_ENDPOINT" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"flux-2/text-to-image","prompt":"a red fox in fresh snow, eye level","aspect_ratio":"1:1"}' \
| python3 -m json.tool
이것이 작동하면 알려진 양호한 기준선이 생깁니다. 이후 Python에서 발생하는 모든 실패는 이 유효하다고 확인된 호출과 비교할 수 있습니다.
프롬프트와 화면 비율 파라미터
출력에 가장 큰 영향을 미치는 두 가지 요청 필드는 prompt와 aspect_ratio입니다. 한 번에 하나씩만 조정하세요. 그렇지 않으면 보이는 변화가 어느 쪽 때문인지 판단할 수 없습니다.
프롬프트
프롬프트는 이미지에 대한 자연어 설명입니다. 키워드 목록이 아니라 간결한 장면 설명으로 작성하세요—대략 주제, 장면, 조명, 구도의 순서로. 비교해 보세요:
- 모호함:
a lighthouse - 구체적:
a weathered lighthouse on a granite cliff at dawn, soft fog, wide shot
실험할 때 표현을 명확하고 안정적으로 유지하세요. 같은 반복에서 프롬프트와 화면 비율을 모두 다시 쓰면 변수 두 개와 관찰 한 번을 갖게 됩니다. 프롬프트를 고정하고 한 번에 한 단어씩 조정하며 실제로 무엇이 바뀌는지 기록하세요.
실용적인 습관:
- 가장 중요한 주제를 문자열 앞부분에 배치하세요.
- 조명과 분위기를 추상적이지 않고 구체적인 단어로 묘사하세요.
- 코드베이스에 소규모 참조 프롬프트 세트를 유지하고, 다른 무엇이든 변경할 때마다 다시 실행해 모델 동작 변화와 프롬프트 변화를 구분하세요.
화면 비율
aspect_ratio는 출력의 형태를 제어합니다—풍경과 배너에는 넓은 비율, 아바타와 썸네일에는 정사각형, 포스터와 모바일 레이아웃에는 세로 비율. 모델은 16:9, 1:1 또는 세로 등가물 같은 비율 문자열을 받습니다. 임의로 만들어 내지 말고 모델 문서에 기록된 비율을 사용하세요.
화면 비율은 단일 이산 필드이므로 가장 쉽게 스캔할 수 있는 파라미터입니다. 프롬프트를 고정하고 세 가지 비율로 같은 이미지를 요청하는 루프를 작성한 뒤 구도를 나란히 비교하세요. 어떤 비율이 주제를 잘라내고 어떤 비율이 주제에 여백을 주는지 금방 알게 됩니다.
한 가지 주의사항: 화면 비율은 단순히 캔버스가 아니라 실질적인 구도를 바꿉니다. 넓은 샷을 위해 작성한 프롬프트는 정사각형 프레임에서 빈약해 보일 수 있습니다. 비율을 정한 후 보정을 위해 프롬프트를 한 번 재검토하세요.
호출을 Python으로 이식하기
curl 호출은 Python으로 곧바로 변환됩니다. 목표는 프롬프트와 화면 비율을 받아 환경에서 키를 읽고 파싱된 JSON을 반환하는 작은 함수를 작성하는 것입니다—일회성 스크립트가 아닌 프로덕션 형태로.
import os
import requests
IMAGE_ENDPOINT = os.environ["HIAPI_IMAGE_ENDPOINT"]
MODEL = "flux-2/text-to-image"
def generate_image(prompt: str, aspect_ratio: str = "1:1", timeout: int = 120) -> dict:
api_key = os.environ["HIAPI_API_KEY"] # fail fast if unset
payload = {
"model": MODEL,
"prompt": prompt,
"aspect_ratio": aspect_ratio,
}
response = requests.post(
IMAGE_ENDPOINT,
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json=payload,
timeout=timeout,
)
response.raise_for_status()
return response.json()
이렇게 작성한 이유에 대한 설명:
- 리터럴이 아닌 환경 변수를 사용하세요.
os.environ[...]는 변수가 없을 때 즉시KeyError를 발생시키는데, 빈 bearer 토큰을 보내고 나중에 혼란스러운 인증 오류를 디코딩하는 것보다 훨씬 낫습니다. json=payload는requests가 요청 본문을 직렬화하고Content-Type을 설정하게 합니다. JSON 문자열을 수동으로 만들지 마세요.- 명시적 타임아웃. 이미지 생성은 즉각적이지 않으며, 기본 클라이언트 타임아웃은 부하 상황에서 문제를 일으킵니다. 의도적으로 설정하세요.
raise_for_status()는 2xx가 아닌 응답을 데이터처럼 보이는 조용한 오류 본문이 아니라 포착하고 분류할 수 있는 예외로 변환합니다.
호출하기:
result = generate_image(
"a weathered lighthouse on a granite cliff at dawn, soft fog, wide shot",
aspect_ratio="16:9",
)
print(result)
httpx를 더 선호한다면 형태는 완전히 동일합니다—임포트만 바꾸고 동일한 헤더, json= 페이로드, 타임아웃 파라미터를 유지하세요. 중요한 것은 페이로드이며, curl 버전과 동일하게 유지됩니다.
응답 읽기
성공한 호출은 JSON 객체를 반환합니다. 필드명을 추측하지 말고 실제 응답을 먼저 검사한 뒤 실제로 본 내용을 바탕으로 파서를 작성하세요. 함수를 실행하고 최상위 키를 출력하세요:
result = generate_image("a red fox in fresh snow, eye level", "1:1")
print(result.keys())
일반적으로 사용하게 될 필드는 두 그룹으로 나뉩니다:
- 이미지 자체. 응답은 생성된 이미지를 담고 있습니다—보통 다운로드하거나 제공할 수 있는 URL, 때로는 인코딩된 이미지 데이터입니다. 자신의 응답에서 정확한 필드명을 읽고, 해당 값을 저장한 뒤 그 형태에 맞게 처리하세요. URL이라면 단기 유효로 간주하세요—링크를 데이터베이스에 저장하고 다음 달에도 해석 가능하다고 가정하지 말고, 즉시 다운로드하거나 자신의 스토리지로 복사하세요.
- 메타데이터. 생성 과정을 설명하는 동반 필드가 있을 것으로 예상됩니다—사용된 모델, 요청된 화면 비율이나 크기, 그리고 요청 식별자. 이미지와 함께 기록하세요. 사용자가 이미지가 "이상해 보인다"고 보고할 때, 메타데이터는 애플리케이션 상태에서 다시 추론할 필요 없이 어떤 프롬프트와 비율이 그것을 만들었는지 알려줍니다.
안전한 추출 패턴:
image_ref = result.get("image") or result.get("data")
if not image_ref:
raise ValueError(f"no image in response; keys={list(result.keys())}")
이것은 의도적으로 방어적인 방식입니다. 필드명은 모델 내에서 안정적이지만, 접근자를 실제 키 목록으로 크게 실패하는 형태로 작성하면 조용한 None이 UI로 전파되는 것을 막을 수 있습니다. 실제 응답에서 필드명을 확인한 후에는 코드를 좁혀 직접 읽으세요.
마지막으로, 원본 응답을 버리지 마세요. 통합이 안정될 때까지 저장하세요(또는 일부 요청에 대해 로그로 기록하세요)—다운스트림에서 이상이 발생할 때 이것이 사실의 근거입니다.
흔한 오류와 해결 방법
대부분의 첫 실행 실패는 몇 가지 범주에 속합니다. 예고 없이 변하는 문자열 메시지 텍스트 매칭이 아니라 HTTP 상태 범주로 처리하세요.
인증 실패(401 / 403)
키가 없거나, 형식이 잘못되었거나, 접근 권한이 없습니다. 순서대로 확인하세요: 프로세스가 볼 수 있는 환경에 HIAPI_API_KEY가 실제로 설정되어 있는지, 헤더가 정확히 Authorization: Bearer <key>이고 여분의 공백이나 감싸는 따옴표가 없는지, 실수로 다른 환경의 키를 보내고 있지는 않은지. curl은 되는데 Python은 안 된다면, 보내는 헤더를 출력해 문자 단위로 비교하세요.
페이로드 형식 오류(400)
요청 본문이 생성 전에 거부되었습니다. 흔한 원인: 유효하지 않은 JSON(수동으로 만든 문자열의 후행 쉼표), prompt 누락, 잘못된 Content-Type. 해결 방법은 Python에서 json=payload를 사용하고, curl에서 유효한 JSON과 함께 -d를 사용하는 것입니다. 로그에 보내려는 페이로드를 출력하고 사람이 읽듯이 읽어 보세요.
지원되지 않는 또는 유효하지 않은 파라미터(400 / 422)
모델이 받지 않는 필드명이나 값—오타 난 aspect_ratio, 모델에 기록되지 않은 비율, 또는 다른 모델 예시에서 복사한 추가 필드. 페이로드를 최소(model, prompt)로 줄인 뒤 필드를 하나씩 추가해 문제를 찾아내세요.
속도 제한(429)
계정 제한이 허용하는 속도보다 빠르게 요청을 보냈습니다. 일시적입니다. 촘촘한 루프에서 재시도하지 말고, 증가하는 지연과 시도 상한을 사용한 백오프를 적용하세요. 일괄 처리 중이라면 한꺼번에 모두 보내지 말고 호출 사이에 작은 지연을 추가하세요.
서버 측 오류(5xx) 및 타임아웃
이들은 일시적이며 당신의 통제를 벗어납니다. 백오프로 재시도하고, 느린 생성이 실패로 오분류되지 않도록 타임아웃이 충분히 길게 하세요. 모델이 아직 작업 중일 때 발생하는 읽기 타임아웃은 재시도를 만들어 요청 하나를 낭비합니다.
분류를 한 곳에 두면 유지 관리가 쉬워집니다:
def classify(status: int) -> str:
if status in (401, 403):
return "auth" # fix config, do not retry
if status in (400, 422):
return "payload" # fix request, do not retry
if status == 429:
return "rate_limit" # retry with backoff
if status >= 500:
return "server" # retry with backoff
return "other"
프로덕션을 위한 호출 래핑
위 함수는 작동하지만, 실제 통합에는 아직 없는 세 가지가 필요합니다: 일시적 실패와 영구적 실패를 구분하는 재시도, 현실을 반영하는 타임아웃, 무슨 일이 있었는지 재구성할 수 있게 해 주는 로그. 작은 래퍼가 이 세 가지를 모두 처리합니다.
import logging
import time
log = logging.getLogger(__name__)
def generate_with_retry(prompt, aspect_ratio="1:1", attempts=3):
delay = 1.0
for attempt in range(1, attempts + 1):
try:
return generate_image(prompt, aspect_ratio)
except requests.HTTPError as exc:
status = exc.response.status_code
kind = classify(status)
log.warning("flux-2 call failed", extra={
"attempt": attempt, "status": status,
"kind": kind, "aspect_ratio": aspect_ratio,
})
if kind in ("auth", "payload"):
raise # retrying will not help
if attempt == attempts:
raise
time.sleep(delay)
delay *= 2
각 부분이 가치 있는 이유:
- 재시도 가능한 것만 재시도하세요. 인증과 페이로드 오류는 결정적입니다—재시도는 시간을 낭비하고 진짜 버그를 가립니다. 속도 제한, 서버 오류, 타임아웃은 지수 백오프를 적용합니다.
- 산문이 아닌 구조화된 필드를 기록하세요. 시도 횟수, 상태, 오류 범주, 사용된 파라미터를 통해 나중에 실패를 그룹화할 수 있습니다. API 키는 절대 기록하지 마세요.
- 시도 횟수를 제한하세요. 무한 재시도 루프는 일시적 장애를 멈춘 작업 프로세스로 바꿉니다.
- 타임아웃을 명시적이고 넉넉하게 유지하세요. 설정에서 전달해, 알려진 느린 시간대에 코드를 수정하지 않고도 늘릴 수 있게 하세요.
보람 있는 두 가지 습관이 더 있습니다: 생성된 각 이미지에 대해 (model, prompt, aspect_ratio)의 해시를 영속화해 어떤 출력이든 재현할 수 있게 하세요; 테스트 스위트에 소규모 참조 프롬프트 세트를 유지하고 래퍼를 변경할 때마다 실행하세요. 두 가지를 결합하면 튜토리얼 조각이 운영 가능한 것으로 바뀝니다.
요청 형태가 확정되고 오류 처리가 자리 잡으면, 이후 모델 교체는 model 필드에 대한 한 줄 변경만 필요합니다—이것이 통합 인터페이스를 통해 flux-2/text-to-image를 호출하는 것의 전부입니다.