튜토리얼
HiAPI로 fibo-gen-1.5/text-to-image를 호출하는 방법: curl과 Python 가이드
이 페이지에서
curl로 동작하는 요청 구성하기
fibo-gen-1.5/text-to-image는 표준 HiAPI 요청 패턴으로 접근하는 호스팅형 텍스트-이미지 모델입니다. 이 세부 사항은 처음 보이는 것보다 중요합니다. 가중치를 다운로드하거나 GPU를 설정하거나 모델 전용 SDK를 배울 필요가 없습니다. 모델 식별자와 프롬프트를 담은 HTTP 요청을 보내면 이미지 결과를 받습니다. 통합 작업은 세 곳에 집중됩니다. 프롬프트를 어떻게 설계할지, 어떤 파라미터를 설정할지, 응답을 어떻게 처리할지입니다.
코드를 작성하기 전에 안심하고 받아들여도 되는 몇 가지 전제가 있습니다:
- 인증 방식은 통일되어 있습니다. 모든 HiAPI 호출은 요청 헤더에 API 키를 담습니다. 모델별 인증 절차는 존재하지 않습니다.
- 모델은 이름으로 선택합니다.
fibo-gen-1.5/text-to-image는 모델 필드로 요청 본문에 넣으며,/text-to-image접미사를 포함해 그대로 작성해야 합니다. - 호출자 관점에서 생성은 동기적입니다. 요청을 보내고, 기다리고, 출력을 받습니다. 타임아웃 예산은 즉시 반환된다고 가정하지 말고 실제 생성 지연을 반영해야 합니다.
- 응답은 구조화되어 있습니다. 원시 바이너리 덩어리가 아니라 JSON 래퍼를 받으므로, 사용하려면 먼저 파싱해야 합니다.
다른 HiAPI 모델을 통합해 본 적이 있다면 익숙하게 느껴질 것입니다. 이번이 처음이라면, 여기서 배우는 패턴은 플랫폼의 다른 모든 것에 그대로 이전됩니다. 정말로 모델 고유의 지식은 파라미터 선택에 있으며, 이 가이드의 뒤에서 다룹니다.
Python에서 동일한 호출 실행하기
성공하는 최소 호출부터 시작하세요. 키를 내보내 셸 기록에 평문으로 남지 않게 하세요:
export HIAPI_API_KEY="your_api_key_here"
그런 다음 요청을 보냅니다:
curl -sS -X POST "https://api.hiapi.ai/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "fibo-gen-1.5/text-to-image",
"prompt": "a weathered fisherman mending a net on a wooden dock at dawn, overcast light, 35mm photograph",
"size": "1024x1024",
"n": 1
}'
세 가지를 특히 짚을 만합니다. "복사-붙여넣기 운에 맡기기" 식 시도가 흔히 실패하는 지점이기 때문입니다:
- 모델 문자열은 정확해야 합니다.
fibo-gen-1.5/text-to-image이며,fibo-gen-1.5도, 대소문자 변형도 아닙니다. 조금만 어긋나면 조용히 대체되지 않고 모델을 찾을 수 없다는类 오류가 반환됩니다. - 키는 베어러 토큰으로
Authorization헤더에 넣습니다. 요청 본문이나 쿼리 문자열에 넣지 마세요. Content-Type: application/json은 필수입니다. 없으면 일부 프록시와 게이트웨이가 페이로드가 API에 도달하기 전에 훼손합니다.
정확히 무엇이 반환되는지(응답 헤더 포함) 확인하려면 curl 호출에 -i를 추가하세요. 응답이 비어 보일 때 가장 유용한 디버깅 습관입니다. 200이지만 본문 모양이 이상한지, 아니면 처리해야 할 비2xx 상태인지 알려줍니다. 탐색 중에는 jq . 파이프로 JSON 출력을 보기 좋게 만들 수 있습니다.
성공하면 프롬프트를 바꿔 다시 실행하세요. 호출의 나머지 부분을 그대로 두면 프롬프트 변경과 구조 변경을 분리할 수 있습니다.
프로덕션 환경에 투입하기
동작하는 스크립트에서 신뢰할 수 있는 통합으로 나아가는 일은 주로 지루한 부분에 달려 있습니다. 체크리스트:
- 키는 코드에 들어가지 않습니다. 환경 변수나 시크릿 관리자에서 로드하고, 절대 커밋하지 말고, 실제로 지킬 수 있는 주기로 교체하세요. 개발과 프로덕션에 서로 다른 키를 사용하면 개발 키 유출이 라이브 트래픽을 망가뜨리지 않습니다.
- 타임아웃은 명시적이고 근거가 있어야 합니다. 추측이 아니라 자체 워크로드에서 관찰된 생성 지연을 기준으로 상한을 정하세요. 호출마다 실제 소요 시간을 기록해 이 수치에 근거를 부여하세요.
- 재시도는 제한적이고 선택적이어야 합니다. 일시적 장애(타임아웃, 속도 제한 상황)에는 지수 백오프와 엄격한 시도 상한으로 재시도하세요. 잘못된 페이로드나 인증 실패는 절대 재시도하지 마세요. 매번 같은 방식으로 실패해 할당량만 낭비합니다.
- 출력은 신뢰하기 전에 검증하세요. 디코딩된 바이트 수가 합리적인지, 파일이 유효한 이미지로 열리는지 확인하세요. CDN에 도달한 0바이트나 잘린 파일은 생성 단계에서 바로 오류가 나는 것보다 더 나쁩니다.
- 모든 생성이 기록됩니다. 프롬프트, 파라미터, 응답, 타임스탬프를 함께 저장하세요. 이렇게 하면 나중에 재현성과 비용 귀속이 가능해집니다.
- 호출은 여기저기 흩어지지 않고 함수 뒤에 캡슐화하세요. 하나의
generate()로 통일하면 재시도 로직, 타임아웃, 로깅을 한 곳에서만 고치면 됩니다.
먼저 curl로 깔끔한 fibo-gen-1.5/text-to-image 요청을 보내고, Python으로 이식한 다음, 그 주위에 운영 계층을 추가하세요. 요청의 모양은 항상 동일합니다. 달라지는 것은 그 주위에 두는 보호 장치뿐입니다.