튜토리얼
HiAPI API로 gpt-image-2.6-sunburst/text-to-image를 호출하는 방법: curl 및 Python 가이드
인증, 요청 구조, 실행 가능한 curl 및 Python 예제, 그리고 문제 해결
이 페이지에서
엔드투엔드로 보면 이 통합은 어떤 모습인가
HiAPI에서의 모든 텍스트-이미지 호출은 동일한 생명주기를 따르며, 코드를 작성하기 전에 이 생명주기를 이해하는 것은 가치 있는 일입니다. 애플리케이션은 대상 이미지를 설명하는 JSON 요청을 구성하고, 이를 API 자격 증명과 함께 gpt-image-2.6-sunburst/text-to-image에 해당하는 HiAPI 엔드포인트로 전송한 뒤, 생성된 이미지 데이터 또는 가져올 수 있는 URL을 포함한 응답을 받습니다. 이 세 단계를 이해하고 나면 이 가이드의 나머지 부분은 세부 사항을 채우는 것에 불과합니다.
각 단계를 나누면 다음과 같습니다:
- 인증——HiAPI API 키를 요청에 첨부하며, 보통 HTTP 요청 헤더 형태입니다. 호출마다 토큰 협상을 할 필요가 없습니다.
- 요청 구성——프롬프트를 포함하고 선택적으로 크기, 이미지 수 등의 매개변수를 포함하는 JSON 요청 본문을 조립합니다.
- 전송——요청 본문을 엔드포인트로 POST합니다. 호출은 동기식이므로 클라이언트는 이미지 생성이 완료될 때까지 기다립니다.
- 응답 처리——API는 구조화된 JSON을 반환합니다. 엔드포인트 구성에 따라 이미지 데이터가 URL 형태로 오거나, 인코딩된 이미지 콘텐츠 형태로 오며, 이를 디코딩하여 디스크에 기록해야 합니다.
일찍 주의해야 할 세부 사항이 하나 있습니다: 모델 식별자 gpt-image-2.6-sunburst/text-to-image에는 슬래시가 포함되어 있습니다. 이는 불투명 문자열로 취급하십시오. 제공자 이름과 모델 이름으로 분리하려 하지 말고, 임의로 URL 인코딩하거나 정규화하지 마십시오. 문서에 나온 그대로 정확히 복사하여 코드의 한 위치에 두면 나중에 다시 찾느라 고생할 필요가 없습니다.
다음 섹션들에서는 각 단계를 순서대로 하나씩 다룹니다. curl과 Python 부분은 의도적으로 동일한 요청 페이로드를 사용하여 줄 단위로 비교할 수 있게 했으며, 문제 해결 부분은 가장 마주치기 쉬운 오류를 수정해야 할 구체적인 요청 필드로 매핑합니다.
HiAPI 요청 인증
HiAPI는 API 키 기반 인증 방식을 사용합니다. 계정 대시보드에서 키를 얻어 매 요청마다 전송합니다. 표준 형태는 요청의 HTTP 헤더입니다:
Authorization: Bearer YOUR_API_KEY
일부 클라이언트는 키를 전용 헤더로 전송하는 것을 선호하지만, 계정 문서에서 달리 명시하지 않는 한 Authorization: Bearer 형식을 사용해야 합니다. 대부분의 HTTP 도구에서 기본적으로 호환되기 때문입니다.
키를 소스 코드 밖에 두기
첫 통합에서 가장 흔한 보안 실수는 키를 스크립트에 하드코딩하여 커밋하는 것입니다. 첫날부터 이를 피하십시오:
HIAPI_API_KEY와 같은 환경 변수에서 키를 읽고, 변수가 없으면 시작 시 빠르게 실패하도록 합니다.- 로컬
.env파일을 만들기 전에 먼저.gitignore에 추가합니다. - CI 또는 프로덕션 환경에서는 커밋된 파일에서 읽는 대신 플랫폼의 시크릿 저장소에서 키를 주입합니다.
키를 한 번 읽고 없으면 명확한 오류를 발생시키는 작은 도우미 함수 하나가 나중에 혼란스러운 디버깅 한 번을 덜어줄 것입니다:
import os
api_key = os.environ.get("HIAPI_API_KEY")
if not api_key:
raise RuntimeError("HIAPI_API_KEY is not set")
요청 시에도 키를 기밀 정보로 취급하기
실패한 호출을 조사할 때 헤더가 포함된 전체 요청 객체를 출력하고 싶은 유혹이 생깁니다. 대신 엔드포인트, 모델 식별자, 상태 코드를 기록하십시오. 디버깅을 위해 헤더를 반드시 캡처해야 한다면 먼저 Authorization 값을 마스킹하십시오. 로그 수집기로 유출된 키는 코드 저장소에 커밋된 키만큼이나 노출된 상태입니다.
키를 교체하면 이전 키는 교체 완료 즉시 무효화되므로, 교체를 긴급 작업이 아닌 정기 작업으로 일정에 넣으십시오.
텍스트-이미지 요청의 구조 분석
요청 본문은 JSON 객체입니다. gpt-image-2.6-sunburst/text-to-image의 경우 핵심 필드 수가 적으며, 바로 그렇기 때문에 요청 페이로드를 무작정 복사하는 대신 각 필드의 역할을 정확히 이해할 가치가 있습니다.
model 필드
"model": "gpt-image-2.6-sunburst/text-to-image"
이 필드는 모델을 선택하며 필수입니다. 문자열을 문서 식별자와 바이트 단위로 동일하게 유지하십시오. 슬래시가 빠지거나, 여분의 공백이 있거나, 대소문자가 바뀌면 요청이 알 수 없는 모델로 인해 거부됩니다.
prompt 필드
"prompt": "A sunlit alpine meadow at golden hour, wildflowers in the foreground, sharp focus"
이미지에 대한 자연어 설명이며 필수입니다. 프롬프트 자체에 대한 실용적인 조언:
- 먼저 주제를 쓰고, 그다음 장면, 마지막으로 스타일이나 조명 단서를 씁니다.
- 추상적 개념보다 구체적 명사를 선호하십시오. "나무 탁자 위의 빨간 도자기 머그컵"이 "멋진 컵 장면"보다 낫습니다.
- 여러 호출에서 일관된 출력을 유지해야 한다면 변하지 않는 부분의 표현을 안정적으로 유지하고, 변하는 부분만 프로그래밍 방식으로 교체하십시오.
선택적 매개변수
엔드포인트에 따라 출력 형태와 수를 제어하는 매개변수를 보낼 수 있으며, 가장 흔한 것은 다음과 같습니다:
- size——출력 크기로, 문서에 규정된 형식으로 표시합니다(예:
1024x1024). 생략하면 기본값이 적용되며, 지원되지 않는 값을 보내면 검증 오류가 발생할 것으로 예상하십시오. - n——하나의 프롬프트에 대해 생성할 이미지 수입니다. 생성된 이미지마다 별도로 청구되므로 워크플로에 필요한 최소값으로 유지하십시오.
실제로 필요한 매개변수만 보내십시오. 알 수 없는 필드는 엄격한 검증 오류를 유발할 수 있으며, 그 오류는 보낼 의도조차 없었던 필드를 가리킵니다.
완전한 요청 본문 예시
{
"model": "gpt-image-2.6-sunburst/text-to-image",
"prompt": "A sunlit alpine meadow at golden hour, wildflowers in the foreground, sharp focus",
"size": "1024x1024",
"n": 1
}
이것이 전부입니다. 이 가이드의 나머지 내용은 이 페이로드를 둘러싼 전송, 오류 처리, 생명주기 관리입니다.
curl로 실행 가능한 요청 보내기
Python 클라이언트를 구축하기 전에 먼저 curl로 엔드포인트와 자격 증명이 작동하는지 확인하십시오. 이렇게 하면 인증 문제와 코드 문제를 분리할 수 있습니다.
호출 명령
curl -sS -X POST "https://api.hiapi.ai/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2.6-sunburst/text-to-image",
"prompt": "A sunlit alpine meadow at golden hour, wildflowers in the foreground, sharp focus",
"size": "1024x1024",
"n": 1
}'
이 플래그들에 대한 몇 가지 설명:
-sS는 출력을 깔끔하게 유지하면서도 전송 오류는 표시합니다.-X POST는 메서드를 지정하며, 요청 본문은-d로 전달됩니다.- JSON 요청 본문을 감싸는 작은따옴표는 셸이 이를 훼손하지 않도록 방지합니다. Windows
cmd에서는 JSON 따옴표 규칙이 다르므로curl.exe와 큰따옴표를 사용하고 내부 따옴표를 이스케이프하거나, 셸 스크립트 또는 Python에서 호출을 실행하십시오.
계정 문서에 있는 정확한 엔드포인트 경로를 사용하는 경우 여기서 교체하십시오; 요청의 형태는 변하지 않습니다.
원시 응답 확인
문제가 발생하면 상태 코드와 응답 본문이 필요합니다. -i를 추가하여 응답 헤더를 포함하거나, -w "\nHTTP %{http_code}\n"을 추가하여 끝에 상태를 출력하십시오:
curl -sS -o response.json -w "HTTP %{http_code}\n" -X POST "https://api.hiapi.ai/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @payload.json
페이로드를 payload.json에 저장하고 @payload.json으로 참조하는 것이 좋습니다. 셸 따옴표 오류를 피할 수 있고, 명령을 다시 작성하지 않고도 프롬프트를 편집할 수 있기 때문입니다. 프롬프트에 민감한 텍스트가 포함되어 있으면 해당 파일을 버전 관리에서 제외하십시오.
Python으로 동일한 호출 수행하기
Python 버전은 JSON 요청 본문을 바이트 단위로 동일하게 유지합니다. 전송 방식만 바뀝니다. requests를 사용하면 의존성이 하나 추가되지만 코드를 읽기 쉽게 유지할 수 있으므로, 일회성 스크립트 이상의 용도라면 설치할 가치가 있습니다.
import os
import requests
api_key = os.environ["HIAPI_API_KEY"]
payload = {
"model": "gpt-image-2.6-sunburst/text-to-image",
"prompt": "A sunlit alpine meadow at golden hour, wildflowers in the foreground, sharp focus",
"size": "1024x1024",
"n": 1,
}
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
}
response = requests.post(
"https://api.hiapi.ai/v1/images/generations",
headers=headers,
json=payload,
timeout=120,
)
print(response.status_code)
response.raise_for_status()
data = response.json()
print(data)
data=json.dumps(payload) 대신 json=payload를 사용하는 이유: dict를 json 키워드 인수에 전달하면 이를 직렬화하고 Content-Type 헤더를 자동으로 설정합니다. 문자열을 data에 전달해도 되지만 헤더 설정을 잊기 쉬우며, 이는 나중에 혼란스러운 검증 오류로 나타납니다.
표준 라이브러리를 선호하는 경우
의존성을 피하려면 표준 라이브러리의 urllib.request를 사용할 수 있습니다. 페이로드 딕셔너리는 동일하게 유지됩니다:
import json, os, urllib.request
payload = {
"model": "gpt-image-2.6-sunburst/text-to-image",
"prompt": "A sunlit alpine meadow at golden hour, wildflowers in the foreground, sharp focus",
}
request = urllib.request.Request(
"https://api.hiapi.ai/v1/images/generations",
method="POST",
headers={
"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
"Content-Type": "application/json",
},
data=json.dumps(payload).encode("utf-8"),
)
with urllib.request.urlopen(request, timeout=120) as response:
data = json.loads(response.read().decode("utf-8"))
어느 쪽이든 이미지 생성은 일반적인 JSON API 호출보다 느립니다. 타임아웃을 넉넉하게 설정하십시오. 그렇지 않으면 곧 성공할 요청에서 타임아웃이 발생하고, 재시도할 때 그 비용을 두 번 지불하게 됩니다.
응답 처리 및 이미지 저장
성공한 응답은 JSON입니다. 이미지 출력은 보통 URL(별도로 가져와야 함) 형태로 오거나 페이로드에 인코딩된 이미지 콘텐츠 형태로 옵니다. 어느 형태가 적용되는지 엔드포인트 문서를 확인한 뒤, 매개변수가 바뀌면 정확한 형태가 달라질 수 있으므로 두 형태 모두 방어적으로 처리하십시오.
응답 구조 읽기
응답은 생성된 출력과 메타데이터를 포함하는 JSON 객체입니다. 파싱 코드를 작성하기 전에 한 번 대화식으로 확인하십시오:
print(json.dumps(data, indent=2)[:2000])
이미지가 있는 위치를 찾으십시오. URL 필드가 보이면 다운로드하십시오. base64 콘텐츠가 보이면 디코딩하십시오. URL이 영구적으로 유효하다고 가정하지 말고 단기적으로 유효한 것으로 간주하여 즉시 바이트를 자체 스토리지로 복사하십시오.
URL 기반 결과 저장
image_url = data["data"][0]["url"]
img = requests.get(image_url, timeout=60)
img.raise_for_status()
with open("output.png", "wb") as f:
f.write(img.content)
인코딩된 결과 저장
import base64
encoded = data["data"][0].get("b64_json") or data["data"][0].get("image")
if encoded:
with open("output.png", "wb") as f:
f.write(base64.b64decode(encoded))
실제 워크로드에서는 호출마다 다른 파일 이름을 사용하십시오. 타임스탬프, 요청 ID, 또는 프롬프트에서 파생된 슬러그를 쓰면 됩니다. 나중에 출력을 재생성하거나 감사할 계획이라면 프롬프트를 이미지와 함께 사이드카 JSON 파일에 저장하십시오.
성공 응답 처리를 한 곳에서
응답 파싱을 이미지마다 하나씩 바이트 문자열 목록을 반환하는 함수로 감싸십시오. 이렇게 하면 각 호출자가 바이트가 URL에서 왔는지 인코딩된 콘텐츠에서 왔는지 알 필요 없이 바이트를 쓰거나 업로드하기만 하면 됩니다. 나중에 모델을 전환할 때 이 추상화가 도움이 됩니다.
흔한 오류 진단
대부분의 첫 통합 실패는 몇 가지 범주에 속합니다. 다른 것을 변경하기 전에 상태 코드와 메시지를 아래 수정 방법과 일치시키십시오.
인증 실패
자격 증명이 없거나 유효하지 않아 요청이 거부되었다면 Authorization 헤더가 없거나, 형식이 잘못되었거나, 폐기된 키를 담고 있음을 의미합니다. 다음 순서로 확인하십시오:
- 헤더 이름과 값 형식을 확인하십시오. 리터럴 단어
Bearer뒤에 공백이 오는 것을 포함합니다. - 호출을 실행하는 셸 또는 프로세스에서 환경 변수가 실제로 채워져 있는지 확인하십시오. 한 터미널에서 설정한 키는 다른 터미널에 존재하지 않습니다.
- 키가 복사 중에 교체되거나 잘리지 않았는지 확인하십시오.
요청 본문 검증 오류
API는 필수 필드가 없거나 유효하지 않은 값을 포함한 요청 본문을 거부합니다. 메시지는 보통 문제가 있는 필드를 지목합니다:
- model 또는 prompt 누락——둘 다 필수입니다. 기본값에 의존하지 말고 매 호출마다 명시적으로 보내십시오.
- 알 수 없는 모델——슬래시와 대소문자를 포함하여 식별자
gpt-image-2.6-sunburst/text-to-image를 다시 확인하십시오. 그 주변에 공백 문자를 삽입하지 마십시오. - 유효하지 않은 크기——문서에 규정된 형식의 지원되는 크기 문자열을 사용하십시오. 의도적으로 size를 생략하는 경우
null을 보내지 말고 제거하십시오. - JSON 형식 오류——보통 curl의 셸 따옴표 문제이거나 Python의 문자열 인코딩 문제입니다. 전송 전에
json.dumps(payload)로 검증하고 실제로 전송되는 내용을 확인하십시오.
속도 제한 및 할당량
스로틀 응답을 받으면 즉시 재시도하지 말고 지터를 더한 백오프로 재시도하십시오. 메시지가 할당량 문제를 나타내면 요청 본문이 아니라 계정의 플랜과 사용량 패널을 확인하십시오. 페이로드는 대개 올바릅니다.
서버 오류
생성 중 발생하는 5xx는 보통 일시적입니다. 지수 백오프를 사용하여 한두 번 재시도하십시오. 서로 다른 프롬프트와 페이로드에서 지속적으로 발생한다면 문제는 여러분 쪽이 아니므로 응답 본문을 캡처하고 요청 시간과 모델 식별자를 가지고 지원팀에 문의하십시오.
콘텐츠 유형 오류
Content-Type: application/json을 설정하지 않고 요청 본문을 보내면 서버가 페이로드를 파싱할 수 없어 혼란스러운 검증 오류가 발생할 수 있습니다. curl에서는 헤더를 명시적으로 설정하고, Python에서는 json= 매개변수가 설정하도록 두십시오.
통합을 프로덕션 준비 상태로 만들기
첫 성공 호출은 쉬운 부분입니다. 다음 조정은 운영 비용과 변경 비용 모두를 낮게 유지합니다.
모델 식별자를 설정값으로 만들기
모델 식별자를 상수 또는 환경 기반 구성 값에 저장하고 여러 호출 지점에 인라인으로 두지 마십시오. 나중에 다른 모델을 평가할 때 값 하나만 변경하고 테스트를 다시 실행하면 됩니다. 로그에 각 요청의 필드를 남겨 어떤 모델이 각 이미지를 생성했는지 기록하면, 모든 것을 다시 실행하지 않고도 모델 전환 시 품질을 비교할 수 있습니다.
전략적으로 재시도하기
네트워크 오류, 타임아웃, 5xx 응답에는 지수 백오프와 지터를 사용하여 재시도하십시오. 검증 또는 인증 오류는 절대 재시도하지 마십시오. 요청은 동일하게 실패하며 속도 제한만 낭비하게 됩니다. 시도 횟수를 제한하고 각 시도의 번호와 최종 상태를 기록하십시오.
워크로드에 맞는 타임아웃 선택
이미지 생성은 느립니다. 너무 짧은 타임아웃은 성공할 수 있었던 요청을 실패하게 만들며, 재시도하면 이미 완료된 생성에 대해 비용을 지불할 수 있습니다. 요청별 타임아웃을 넉넉하게 설정하고, 임계값을 초과하는 타임아웃은 공격적 재시도 이유가 아니라 지연을 조사하라는 신호로 취급하십시오.
클라이언트를 계층화하기
세 부분을 분리하여 유지하십시오: 애플리케이션 입력을 요청 딕셔너리로 변환하는 페이로드 빌더, HTTP 호출을 수행하는 전송 함수, 응답을 바이트로 디코딩하는 핸들러. 빌더는 네트워크 호출 없이 테스트하기 매우 쉽고, 전송을 mock으로 교체하기도 매우 쉽습니다. 이 계층화는 또한 모델 변경을 코드베이스 곳곳을 뒤지는 일이 아니라 한 파일의 편집으로 만듭니다.
사고 시 필요할 정보 기록하기
타임스탬프, 엔드포인트, 모델 식별자, HTTP 상태, 프롬프트의 해시 또는 잘린 형태, 요청 지속 시간을 기록하십시오. API 키나 전체 헤더는 절대 기록하지 마십시오. 생성된 이미지를 저장하는 경우 요청 ID로 저장 경로를 구성하여 지원 티켓이 실제 호출로 추적될 수 있게 하십시오.
인증이 환경 변수로 처리되고 페이로드가 빌더 함수에 격리된 상태에서, gpt-image-2.6-sunburst/text-to-image를 통해 연습한 패턴은 동일한 HiAPI 엔드포인트의 다른 이미지 모델로도 그대로 이전됩니다.