튜토리얼
HiAPI API로 fibo-2.0/text-to-image를 호출하는 방법: curl과 Python 실전
이 페이지에서
이 튜토리얼에서 만드는 것
이 글은 HiAPI의 fibo-2.0/text-to-image로 실제 이미지를 하나 받아오는 실습 가이드입니다. 끝까지 읽으면 즉시 실행할 수 있는 두 가지를 얻게 됩니다. 유효한 이미지 생성 요청을 만드는 curl 명령 하나와, 같은 일을 하면서 결과를 반환해 이후 처리를 가능하게 하는 작은 Python 함수 하나입니다.
대부분의 개발자가 실제로 작업하는 순서를 따릅니다. 먼저 환경과 자격 증명이 준비되었는지 확인합니다. 그다음 요청 본문을 필드별로 읽어 각 부분이 무엇을 제어하는지 명확히 합니다. 이어서 curl로 호출을 보내 엔드포인트, 키, 요청 페이로드가 일치함을 증명합니다. 그다음에야 같은 요청을 Python으로 옮기는데, 바로 거기서 응답 파싱, 실패 처리, 함수로 감싸기라는 진짜 흥미로운 작업이 시작됩니다.
목표는 가능한 모든 파라미터를 나열하는 것이 아니라, 완전히 이해한 요청 형태를 주는 것입니다. 그래야 추측 없이 프롬프트, 출력 크기, 주변 코드를 자신의 사용 사례에 맞게 조정할 수 있습니다.
첫 요청을 보내기 전에
첫 호출이 성공하려면 세 가지 조건이 충족되어야 합니다.
HiAPI 계정과 API 키
fibo-2.0/text-to-image 요청에는 인증이 필요합니다. HiAPI 계정에서 API 키를 생성하고 소스 코드 관리에서 멀리 두세요. 아래 예제는 키를 하드코딩하지 않고 환경 변수에서 읽습니다. 나중에 키 처리를 붙이는 것은 번거로우므로 첫날부터 이렇게 하세요.
export HIAPI_API_KEY="your-api-key-here"
HTTP 요청을 보낼 수 있는 도구
curl 실습 부분을 위해서는 머신에 curl이 필요합니다. macOS와 대부분의 Linux 배포판에 기본으로 포함되어 있으며, Windows에서는 최신 버전과 Windows Terminal에서도 사용할 수 있습니다. Python 부분을 위해서는 Python 3와 requests 라이브러리가 필요합니다. 이는 스크립트에서 HTTP 호출을 보내는 가장 흔한 방법입니다. 아직 설치하지 않았다면:
pip install requests
무엇을 생성할지 명확히 하기
프롬프트를 준비하세요. 이미지 모델은 구체적이고 명확한 설명(피사체, 스타일, 조명, 구도)에 강하게 반응하므로 한 줄짜리 아이디어만으로도 테스트를 시작하기에 충분합니다. 첫 결과를 본 뒤 계속 다듬게 될 것입니다. 이는 정상적인 반복입니다.
이 세 가지가 준비되면 나머지는 모두 요청 본문에 관한 것입니다.
요청을 필드별로 분석하기
fibo-2.0/text-to-image 호출은 JSON 본문을 가진 POST 요청입니다. 본문은 작습니다. 프롬프트 하나와 출력을 형성하는 설정들입니다. 전체 페이로드를 외우기보다 각 필드를 이해하면 의도적으로 수정할 수 있습니다.
모델 식별자
엔드포인트 경로 자체가 모델을 가리킵니다: fibo-2.0/text-to-image. 대부분의 경우 모델 문자열을 따로 전달할 필요가 없습니다. 호출하는 라우트가 어떤 모델을 실행할지 결정합니다. 통합이 공유 엔드포인트 라우팅을 지원한다면 모델 이름을 구성 상수에 두어 호출 지점을 바꾸지 않고도 교체할 수 있게 하세요.
프롬프트
핵심 입력입니다. 원하는 이미지에 대한 텍스트 설명입니다. 소망이 아니라 사양서로 다루세요. 피사체, 시각적 스타일, 구도를 말하는 것이 추상적 개념보다 모델에 더 많은 유용한 정보를 줍니다. 프롬프트를 변수나 별도 파일에 두면 요청 코드를 다시 쓰지 않고 빠르게 반복할 수 있습니다.
출력 설정
이미지 요청은 보통 소규모 출력 제어 항목을 포함합니다. 가장 흔한 것은 생성 이미지의 크기 또는 종횡비, 그리고 여러 결과를 원할 때의 개수입니다. HiAPI 모델 참조에서 fibo-2.0/text-to-image에 문서화된 필드 이름을 사용하세요. 아래 예제 페이로드는 그 표준 이름을 사용합니다. 모델에 문서화되지 않은 설정은 추측하지 말고 생략하세요. 알 수 없는 필드는 검증 오류의 흔한 원인입니다.
요청 본문에 넣지 말아야 할 것
API 키를 JSON 본문에 넣지 마세요. 인증은 헤더에 속합니다. 자격 증명을 페이로드에서 멀리 두면 요청 본문을 디버깅 시 안전하게 기록하고 비교할 수 있으며, 첫 요청이 실패할 때 그 가치를 실감하게 됩니다.
사용 가능한 curl 요청
아래는 완전한 호출입니다. 자신의 프롬프트로 바꾸고 HIAPI_API_KEY가 설정된 셸에서 실행하세요.
curl -X POST "https://api.hiapi.ai/v1/models/fibo-2.0/text-to-image" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "새벽녘의 고요한 항구, 수면 위로 옅은 안개가 깔린 모습, 와이드 구도, 사진 스타일",
"size": "1024x1024",
"n": 1
}'
각 부분의 역할
-X POST는 HTTP 메서드를 설정합니다. 이미지 생성은 생성 작업이므로 GET이 아니라 POST입니다.- URL은 HiAPI API 호스트의
fibo-2.0/text-to-image라우트를 가리킵니다. 계정이 지역별 또는 프로젝트 전용 기본 URL을 사용한다면 해당 호스트로 바꾸고 경로는 유지하세요. Authorization: Bearer $HIAPI_API_KEY는 환경에서 키를 전달합니다. 셸이 변수를 확장하므로 키가 명령 기록에 리터럴 문자열로 남지 않습니다.Content-Type: application/json은 서버에 본문이 JSON임을 알립니다. 이것이 없으면 많은 게이트웨이가 요청이 모델에 도달하기 전에 거부합니다.-d '...'는 JSON 본문입니다. 프롬프트, 요청 크기, 이미지 한 장의 개수입니다.
결과 확인
명령을 실행하고 먼저 원시 출력을 보세요. 성공한 호출은 생성된 이미지를 설명하는 JSON 문서를 반환하고, 실패한 호출은 오류 객체를 반환합니다. 이 위에 무엇이든 만들기 전에 두 가지를 눈으로 구분할 수 있는지 확인하세요. 응답이 크다면 jq 같은 포매터로 처리해 구조를 읽을 수 있게 하세요:
curl -s -X POST "https://api.hiapi.ai/v1/models/fibo-2.0/text-to-image" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt":"새벽녘의 고요한 항구","size":"1024x1024","n":1}' | jq .
수동 호출이 성공하면 자격 증명과 페이로드를 용의선상에서 제외한 것입니다. 이후의 모든 문제는 당신의 코드 안에 있습니다.
Python에서의 동일한 호출
Python 버전은 셸 명령이 하는 일과 똑같은 일을 하지만 입력 검증, 재시도, 결과 저장을 할 자리를 제공합니다. 작고 명확하게 유지하세요.
import os
import requests
API_URL = "https://api.hiapi.ai/v1/models/fibo-2.0/text-to-image"
def generate_image(prompt: str, size: str = "1024x1024", n: int = 1) -> dict:
api_key = os.environ["HIAPI_API_KEY"]
payload = {
"prompt": prompt,
"size": size,
"n": n,
}
response = requests.post(
API_URL,
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json=payload,
timeout=60,
)
response.raise_for_status()
return response.json()
if __name__ == "__main__":
result = generate_image(
"새벽녘의 고요한 항구, 수면 위로 옅은 안개가 깔린 모습, 와이드 구도, 사진 스타일"
)
print(result)
이렇게 작성한 이유
- 키는 함수 내부에서 환경으로부터 읽으므로, 키가 없으면 호출이 인증되지 않은 요청을 보내는 대신 시작 시 크게 실패합니다.
json=payload는requests가 본문을 직렬화하고 콘텐츠 타입을 올바르게 설정하게 합니다. Python에서 JSON 문자열을 수작업으로 만들지 마세요. 런타임에야 발견되는 따옴표 오류를 초래합니다.timeout=60은 느린 실패를 명시적으로 만듭니다. 이미지 생성은 즉각적이지 않으므로 기꺼이 기다릴 시간 초과를 선택하되 반드시 설정하세요.raise_for_status()는 4xx와 5xx 응답을 예외로 바꿉니다. 바로 이 한 줄이 실패한 호출이 조용히 성공으로 처리되는 것을 막습니다.- 함수는
prompt,size,n을 파라미터로 받아 프로그램의 나머지 부분이 다른 라이브러리 함수처럼 호출할 수 있게 합니다.
파일을 실행하면 curl 호출이 반환한 것과 같은 JSON 구조를 보게 될 것입니다.
응답 읽기와 오류 처리
성공 응답은 생성된 출력을 설명하는 JSON 객체를 줍니다. 관심 있는 세부 정보는 생성된 이미지 자체(보통 다운로드하거나 저장할 수 있는 URL 또는 참조)와 API가 요청에 대해 반환한 메타데이터입니다. 응답을 데이터로 파싱하세요. 문자열 조작으로 긁어내지 마세요. 실시간 응답을 처음 검사할 때 모양이 예상과 다르면 파서를 조정하기 전에 모델 참조를 확인하세요. 필드 이름을 추측하는 것이 통합이 조용히 깨지는 방식이기 때문입니다.
실패 감지
의도적으로 처리할 가치가 있는 세 계층의 실패가 있습니다.
전송 오류. 요청이 완료되지 않았습니다. DNS 실패, 연결 재설정, 타임아웃 등입니다. Python에서는 requests.exceptions로 나타나며, 백오프와 함께 재시도해도 안전합니다.
HTTP 오류 상태. 서버가 응답했지만 요청을 거부했습니다. 401은 보통 키가 없거나 잘못되었음을 의미하고, 4xx 검증 오류는 보통 필드 이름이나 값이 잘못되었음을 의미하며, 429는 너무 빨리 보냈음을, 5xx는 서버 측 문제를 의미합니다. raise_for_status()는 이 모두를 하나의 예외로 잡으므로 무엇을 할지 결정하기 전에 응답 본문의 메시지를 확인하세요.
상태 코드 200이지만 예상 밖의 응답 본문. 이것이 구조를 가정하지 않고 검증해야 하는 이유입니다. 사용하기 전에 의존하는 필드가 존재하는지 확인하고, 상태 코드가 200이어도 이미지 참조가 없으면 실패로 간주하세요.
try:
result = generate_image("새벽녘의 고요한 항구")
image = result.get("data", [{}])[0]
except requests.HTTPError as exc:
print("request failed:", exc.response.status_code, exc.response.text)
중요한 습관은 오류를 조용히 삼키지 않는 것입니다. 최소한 상태 코드와 응답 본문을 기록하세요. 이 쌍이 페이로드를 고쳐야 할지, 기다렸다가 재시도해야 할지 알려주기 때문입니다.
프로덕션으로 나아가기
단일 호출이 작동하고 실패가 보이게 되면, 몇 가지 작은 습관이 실제 트래픽에서 통합을 견고하게 만듭니다.
안전한 재시도만 하기
전송 오류, 타임아웃, 429 및 5xx 응답은 지수 백오프와 시도 상한으로 재시도할 가치가 있습니다. 검증 오류와 401은 그럴 가치가 없습니다. 잘못된 형식의 요청을 재시도하면 할당량만 소모합니다. 오류 처리에서 이 두 범주를 명확히 구분하세요.
구성을 코드에서 멀리 두기
API 기본 URL, 모델 경로, 기본 크기, 타임아웃을 함수 곳곳에 흩어 두지 말고 구성에 두세요. 테스트 환경에서 다른 환경으로 이동하거나 나중에 유사한 모델을 시도할 때 한 곳만 바꾸면 됩니다.
요청과 응답을 기록하되 키는 제거하기
프롬프트, 파라미터, 상태 코드, 잘린 응답을 기록하세요. API 키는 절대 기록하지 마세요. 그래야 일주일 뒤에 재현 없이 "왜 이 이미지가 잘못 나왔지"라는 질문에 답할 수 있습니다.
보내기 전에 입력 검증하기
프롬프트가 비어 있지 않고 합리적인 길이인지 확인하고, size와 n이 모델의 문서화된 값과 일치하는지 확인하세요. 잘못된 값을 로컬에서 잡는 것이 왕복 한 번보다 빠르고 저렴합니다.
결과를 저장하고 단순히 출력만 하지 않기
생성된 이미지 참조는 임시일 수 있습니다. 같은 작업의 일부로 출력을 다운로드하거나 자신의 스토리지에 복사하고, 어떤 프롬프트와 파라미터가 그것을 만들었는지 기록하세요. 그 기록이 재생성과 감사를 가능하게 합니다.
fibo-2.0/text-to-image를 이 튜토리얼의 작은 generate_image 함수 뒤에 감싸고, 애플리케이션의 나머지 부분이 원시 HTTP 호출이 아니라 그 함수에 의존하게 하세요. 프롬프트를 대규모로 바꿀 준비가 되면, HiAPI 모델 참조는 인터페이스를 확장하기 전에 지원되는 파라미터를 확인하는 곳입니다.