튜토리얼
HiAPI API로 krea-3/text-to-image를 사용하는 방법: curl, Python 및 실행 가능한 요청
이 페이지에서
왜 집계 API를 통해 krea-3/text-to-image를 호출하는가
새로운 이미지 모델이 등장할 때마다 새로운 SDK, 새로운 인증 방식, 새로운 응답 특이점이 생깁니다. 이미지 기능을 하나만 출시한다면 이 비용은 감당할 만합니다. 하지만 여러 개를 출시하거나—나중에 모델을 자유롭게 교체하고 싶다면—이것이 작업의 주요 비용이 됩니다.
HiAPI를 통해 krea-3/text-to-image를 호출하면 이 비용이 사라집니다. 단일 엔드포인트 규약, 단일 자격 증명, 단일 응답 구조에 한 번만 통합하면 됩니다. 모델 식별자는 코드베이스의 분기가 아니라 요청 페이로드의 필드가 됩니다. 출력을 다른 이미지 모델과 비교하거나 워크로드를 마이그레이션하려면 통합이 아니라 문자열 하나를 바꾸면 됩니다.
이 특정 모델에서 실질적인 이점은 구체적입니다:
- 모든 요청이 동일한 구조를 공유합니다. 텍스트-이미지 호출은 플랫폼 전체에서 동일한 인증 및 페이로드 규약을 따르므로, 첫 호출에서 얻은 지식을 다음 모델로 바로 이전할 수 있습니다.
- 모델 독립적인 애플리케이션 코드. 모델 이름을 설정에 유지하세요.
krea-3/text-to-image로 프로토타이핑하고, 이후 다른 모델로 서비스할 때 HTTP 계층을 변경할 필요가 없어야 합니다. - 통합된 사용량 관측 지점. 과금, 요청 로그, 오류 응답이 N개의 공급업체 대시보드가 아닌 하나의 인터페이스에서 나옵니다.
- 더 적은 키. 호출하는 모델 수에 관계없이 하나의 키만 저장, 교체, 범위 제한하면 됩니다.
대가는 집계의 일반적인 대가입니다: 범용 인터페이스를 통해 작업하므로 모델 특유의 특이점이 정규화됩니다. 실제로 이것이 바로 원하는 바입니다—정규화된 입력, 예측 가능한 오류, 그리고 모델을 조정 가능한 매개변수로 취급하는 자유.
이 튜토리얼은 의도적으로 범위를 좁게 유지합니다. 실행 가능한 요청을 구성하고, 두 번 실행하며(먼저 curl, 그다음 Python), 프롬프트 표현이 사진 스타일과 일러스트 스타일 출력을 어떻게 유도하는지 관찰한 다음, 첫 호출 문제의 대부분을 차지하는 소수의 실패 사례를 디버깅합니다. 아키텍처 다이어그램도, 프레임워크 의견도 없습니다—다음 5분 안에 보낼 수 있는 요청과 문제가 생겼을 때 사용할 체크리스트만 있습니다.
전제 조건: HiAPI 계정이 있고, 대시보드에서 API 키를 읽을 수 있으며, 터미널과 Python 인터프리터에 익숙합니다. 그 외에는 필요하지 않습니다.
요청을 보내기 전에
첫 호출 전에 세 가지 조건을 충족해야 합니다. 이것들을 제대로 하면 나머지는 대부분 튜닝이고, 잘못하면 한 시간 동안 잘못된 계층을 디버깅하게 됩니다.
1. 계정과 API 키
HiAPI에 로그인하고 대시보드에서 API 키를 받으세요. 기밀 정보로 취급하세요: 환경 변수나 비밀 관리자에 보관해야 하며, 커밋된 파일에 절대 나타나서는 안 되고, 프롬프트나 지원 메시지에도 절대 나타나서는 안 됩니다. 아래 예제는 환경 변수에서 이를 읽습니다:
export HIAPI_API_KEY="your-key-here"
조직이 여러 키를 지원한다면 이 통합에 전용 키를 사용하여 다른 실행 항목과 독립적으로 교체할 수 있게 하세요.
2. 엔드포인트 규약과 인증 헤더
HiAPI 요청은 bearer token 인증을 사용합니다—다른 수백 개의 API에서 본 것과 동일한 패턴입니다:
Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json
HiAPI API 참조에서 계정 리전에 대해 표시된 base URL을 사용하고, 그 안에 문서화된 이미지 생성 경로를 추가하세요. 기억이나 블로그 글(이 글 포함)에서 경로를 추측하지 마세요—API 참조가 유일한 진실의 원천이며, 경로는 요청에서 예고 없이 바뀔 수 있는 유일한 부분입니다. 튜토리얼 조언: 참조를 한 번 확인하고, URL을 복사하고, 설정 값에 저장하세요.
3. 모델 식별자, 철자 정확히 일치
모델 식별자는 krea-3/text-to-image입니다. 네임스페이스 접두사와 하이픈을 표기 그대로 정확히 유지하세요—krea3/text2image 또는 단독 krea-3은 모델을 찾을 수 없음으로 실패합니다. 대소문자도 중요합니다. 상수로 저장하세요:
MODEL = "krea-3/text-to-image"
이 문자열이 통합을 모델 독립적으로 만드는 것이므로, 이름을 붙이고 각 호출 지점에서 하드코딩하지 말고 설정으로 취급하세요.
미리 파악할 필요가 없는 것
첫 호출 전에 이미지 크기, 시드, 스텝 필드의 이름을 알 필요는 없습니다. 최소 구성으로 시작하세요: 인증, 모델 식별자, 프롬프트. 200 응답을 받은 후 매개변수를 하나씩 추가하세요. 다섯 개 필드가 설정된 실패한 요청은 다섯 개의 용의자를 제공합니다. 최소화된 실패한 요청은 하나만 제공합니다.
curl로 실행 가능한 요청 구성하기
curl은 첫 호출의 두 가지 문제—자격 증명과 페이로드 구조—를 격리하는 가장 빠른 방법입니다. SDK 버전도, 가상 환경도, 비동기 런타임도 없습니다—그저 네트워크 위의 요청 하나일 뿐입니다.
최소 호출은 모델이 실제로 필요로 하는 것만 담습니다: 인증 헤더, 모델 식별자, 프롬프트.
curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "krea-3/text-to-image",
"prompt": "A weathered fisherman mending a net on a dock at dawn, overcast light, 35mm photograph"
}'
실행 전 두 가지 참고 사항. 첫째, $HIAPI_BASE_URL은 자리 표시자입니다—HiAPI API 참조의 base URL로 설정하고, 동일한 참조에서 경로 세그먼트를 확인하세요. 둘째, -sS 플래그는 출력을 조용히 유지하되 오류는 표시하며, 이는 디버깅 시 정확히 원하는 동작입니다.
정상 응답의 모습: 생성된 이미지 참조 또는 데이터와 요청 메타데이터를 포함하는 JSON 객체. 정확한 구조는 API 참조에 문서화되어 있으니 아직 관찰하지 않은 구조에 대해 파싱 코드를 작성하지 마세요. 실제 응답을 파일에 저장하여 기준 사실을 확보하세요:
curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"krea-3/text-to-image","prompt":"A neon-lit alley after rain, cinematic still"}' \
-o response.json
그런 다음 jq나 편집기로 확인하세요. 이 파일이 테스트 픽스처입니다: Python으로 이식할 때 출력을 비교하세요. Python 응답이 구조적으로 response.json과 다르다면 문제는 모델이 아니라 코드에 있습니다.
curl로 먼저 하는 이유는 진단 레버리지입니다. curl 호출이 성공하면 키가 정상이고, URL이 올바르고, 모델 식별자가 해석됩니다—따라서 이후의 모든 실패는 애플리케이션 코드에 있습니다. curl 호출이 실패하면 오류 본문이 이 세 가지 중 무엇이 문제인지 알려주며, 코드는 한 줄도 작성하지 않은 상태입니다.
최소 요청이 성공하면 매개변수를 한 번에 하나씩 추가하세요. 추가할 때마다 curl을 다시 실행하세요. 성공한 페이로드를 보관하세요. 테스트의 수용된 입력 픽스처가 됩니다.
Python에서의 동일한 요청
Python 버전은 의도적으로 지루하게 유지합니다: 동일한 URL, 동일한 헤더, 동일한 JSON 본문. 초점은 이식성입니다—curl에서 검증한 요청 구조가 재설계 없이 스크립트로, 다시 서비스로 이전되어야 합니다.
import os
import json
import requests
BASE_URL = os.environ["HIAPI_BASE_URL"].rstrip("/")
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "krea-3/text-to-image"
def generate(prompt: str) -> dict:
response = requests.post(
f"{BASE_URL}/v1/images/generations",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json={"model": MODEL, "prompt": prompt},
timeout=120,
)
response.raise_for_status()
return response.json()
if __name__ == "__main__":
result = generate(
"A weathered fisherman mending a net on a dock at dawn, overcast light, 35mm photograph"
)
print(json.dumps(result, indent=2))
몇 가지 의도적인 선택:
- 리터럴 대신 환경 변수 사용. 키는 소스 코드에 절대 나타나지 않습니다. 변수가 없으면
os.environ["HIAPI_API_KEY"]가 시작 시 크게 실패하며, 이는 세 계층 아래에서 혼란스러운 401이 발생하는 것보다 낫습니다. - 파싱 전에
raise_for_status()호출. HTTP 오류가 예외로 드러나야 하며, 정확히 JSON인 오류 본문에서 필드를 읽으려다KeyError가 발생해서는 안 됩니다. - 넉넉한 타임아웃. 이미지 생성은 즉시 응답 엔드포인트가 아닙니다. 이를 반영한 타임아웃을 설정하고 프로덕션에서 명시적으로 처리하세요(프로덕션 섹션 참조).
- 수동 문자열 구성 대신
json=사용. 라이브러리가 직렬화하게 하세요. 수동 JSON 조합은 후행 쉼표와 따옴표 오류의 원천입니다.
한 번 실행하고 출력을 이전에 캡처한 response.json과 비교하세요. 구조가 일치해야 합니다. 응답이 반환하는 것에 따라 이미지 참조를 출력하거나 이미지 데이터를 디코딩하세요—마찬가지로 가정된 구조가 아닌 관찰된 구조에 대해 코드를 작성하세요.
MODEL이 상수이므로 동일한 generate() 함수가 플랫폼의 모든 이미지 모델에 적용됩니다. 이것이 집계 모델의 보상입니다: 서비스로 옮기거나, 두 번째 모델을 추가하거나, 출력을 A/B 테스트하는 것은 재작성이 아니라 매개변수 변경입니다.
사진 스타일과 일러스트 스타일 제어하기
스타일은 스위치가 아닙니다. 모델을 밀어가는 방향이며, krea-3/text-to-image는 사진작가나 일러스트레이터와 협업할 때 사용하는 것과 동일한 레버에 반응합니다: 주제, 매체, 조명, 공예 어휘.
사진 스타일로 밀어가기
사진 출력은 주로 장비와 그 결과를 명명하는 데 달려 있습니다. 카메라, 렌즈, 필름, 실제 빛을 설명하는 단어가 "사실적"이라는 단어보다 더 효과적입니다.
- 매체와 촬영 방식 명명: "35mm photograph", "editorial portrait", "documentary still".
- 조명 명명: "overcast daylight", "golden hour backlight", "single softbox at camera left".
- 불완전함 명명: "slight motion blur", "visible grain", "shallow depth of field".
"a fisherman on a dock"와 "a weathered fisherman mending a net on a dock at dawn, overcast light, 35mm photograph, visible grain"을 비교하세요. 두 번째 프롬프트는 모델을 일반적인 묘사가 아닌 사진의 질감과 조명으로 제약합니다.
일러스트 스타일로 밀어가기
일러스트는 전통, 선의 품질, 색상 팔레트를 명명하는 것—그리고 보통 방금 배운 사진 단서를 제거하는 것—에 달려 있습니다.
- 스타일 명명: "flat vector illustration", "ink and watercolor", "mid-century editorial illustration", "isometric line art".
- 선 명명: "clean uniform strokes", "loose gestural linework".
- 팔레트 명명: "restrained two-color palette", "muted pastels".
프리셋이 아닌 반복
프롬프트를 조정 가능한 설정으로 취급하세요. 한 번에 하나의 차원만 변경하세요—매체 구문만 교체하고 주제와 조명은 유지—그러면 각 토큰의 역할을 알 수 있습니다. 프롬프트 변형과 그 출력의 짧은 로그를 유지하세요. 이 로그는 어떤 프리셋 라이브러리보다 가치 있습니다. 왜냐하면 당신의 모델과 콘텐츠에 맞게 보정되었기 때문입니다.
요청이 프롬프트 외의 매개변수—크기, 시드 또는 유사한 것—를 노출한다면, 프롬프트를 확정한 후에 조정하고 그 전에는 하지 마세요. 프롬프트와 세 매개변수를 동시에 변경하면 어떤 변경이 효과를 냈는지 알 수 없습니다.
흔한 오류 문제 해결
대부분의 첫 호출 실패는 네 가지 범주로 분류됩니다. 체크리스트를 순서대로 실행하세요. 각 단계가 하나의 계층을 배제합니다.
인증 실패
증상: 자격 증명이나 권한에 관한 메시지와 함께 401 또는 403.
- 명령을 실행하는 셸에
HIAPI_API_KEY가 실제로 설정되어 있나요?echo $HIAPI_API_KEY—빈 문자열은 잘못된 키와 매우 비슷하게 보입니다. - 헤더가 정확히
Authorization: Bearer <key>인가요?Bearer누락, 여분의 따옴표, 키에 붙은 줄바꿈은 모두 실패를 야기합니다. - 키가 취소되었거나 다른 환경으로 범위가 제한되어 있나요? 의심스러우면 재생성하고 curl 호출로 다시 테스트하세요.
잘못된 형식의 요청 페이로드
증상: 본문, 필드 또는 JSON 파싱에 관한 메시지와 함께 400.
- 전송 전에 JSON을 검증하세요. curl에서 프롬프트 내 이스케이프되지 않은 따옴표 하나가 본문을 깨뜨립니다. Python에서는
json=이 이를 처리합니다—이를 선호하는 또 다른 이유입니다. Content-Type: application/json이 있는지 확인하세요.- 필드 이름을 API 참조와 확인하세요. 맞게 철자된 값이 잘못된 필드 이름 아래에 있으면 여전히 400입니다.
- 최소 페이로드—모델과 프롬프트만—로 돌아가 유효함을 확인한 후 필드를 하나씩 추가하세요.
잘못된 모델 식별자
증상: 404, 또는 모델을 알 수 없거나 사용할 수 없다는 400.
- 문자열을
krea-3/text-to-image와 문자 단위로 비교하세요. 네임스페이스 접두사, 하이픈, 경로 세그먼트 모두 중요합니다. - 문서에서 복사-붙여넣기로 예기치 않은 공백이나 스마트 따옴표가 들어가지 않았는지 확인하세요.
- 코드 어딘가의 설정 기본값이 값을 덮어쓰지 않는지 확인하세요.
속도 및 할당량 응답
증상: 429, 또는 제한이나 잔액 부족에 관한 메시지.
- 엔드포인트를 두드리지 말고 백오프하여 짧은 지연 후 재시도하세요.
- 대시보드에서 사용량과 잔액을 확인하세요.
- 개발 중에 발생한다면 예상보다 빠르게 트리거하는 재시도 루프를 찾으세요—
try블록 내 실패한 요청에 공격적인 재시도를 더하면 한도를 빠르게 소진합니다.
위의 어느 것도 해결하지 못하면 응답에서 전체 요청 ID와 오류 본문을 캡처하여 지원팀에 보내세요. 집계 API의 오류 본문은 보통 문제를 지시할 만큼 구체적입니다. 잘못은 이를 붙여넣지 않고 바꿔 말하는 데 있습니다.
프로덕션에 투입하기
지금의 요청은 프로토타입입니다. 네 가지 실천이 이를 지속적으로 실행 가능한 것으로 만듭니다.
문자열이 아닌 범주로 오류 처리
HTTP 상태 코드를 동작에 매핑하세요: 인증 오류는 누군가를 호출해야 하는 설정 결함이고, 4xx 페이로드 오류는 요청을 크게 실패시켜야 하는 코드 결함이며, 429와 5xx는 지수 백오프와 지터로 재시도해야 하는 일시적 오류입니다. 400은 절대 재시도하지 마세요—동일한 결함을 확인하느라 할당량만 낭비합니다. 명시적 타임아웃을 설정하고 타임아웃을 일시적 오류로 취급하세요.
if response.status_code == 429 or response.status_code >= 500:
raise TransientError(response.status_code)
response.raise_for_status()
프롬프트 기록 및 버전 관리
생성된 모든 이미지는 이를 생성한 정확한 프롬프트로 추적 가능해야 합니다. 프롬프트, 모델 식별자, 매개변수, 응답 요청 ID를 함께 저장하세요. 프롬프트 텍스트를 버전 관리되는 설정으로 취급하세요—함수에 묻힌 리터럴이 아닌 설정 파일에 체크인된 prompt_v3 문자열. 출력 품질이 변할 때 프롬프트, 매개변수, 모델 중 무엇이 변했는지 알아야 합니다.
모델 이름을 설정에 유지
krea-3/text-to-image는 상수나 설정 항목에 한 번만 나타나야 합니다. 이것이 집계 모델의 보상입니다: 모델 교체, 비교 실행, 롤백이 새로운 코드 경로 배포가 아닌 설정 변경이 됩니다. 또한 나중에 다른 워크로드를 다른 모델로 라우팅하는 것을 매우 쉽게 만듭니다.
픽스처에 대해 테스트
이 튜토리얼에서 캡처한 성공 응답을 픽스처로 저장하세요. 파싱 코드가 이를 처리하는지 검증하고, 기록된 오류 본문을 사용하여 오류 매핑을 테스트하세요. 사용자보다 먼저 응답 구조 변화를 발견하게 됩니다.
최소 curl 호출로 시작하고, 응답 구조를 확인하고, 그대로 Python으로 이식한 다음, 프롬프트를 한 차원씩 반복하세요—그리고 변할 수 있는 엔드포인트 세부 사항은 HiAPI API 참조를 확인하세요.