튜토리얼

HiAPI API로 recraft-v4.1/text-to-image 사용하는 방법: curl 및 Python 가이드

Nov 3, 2026

이 엔드포인트가 제공하는 것

recraft-v4.1/text-to-image는 텍스트-이미지 모델 엔드포인트입니다. 요청 본문에 텍스트 프롬프트와 몇 가지 형태 지정 옵션을 보내면 생성된 이미지 데이터를 받습니다. 여러 단계의 파이프라인을 직접 구성하지 않고 한 번의 호출로 완성된 이미지를 얻고 싶을 때 매우 적합합니다.

HiAPI에서 이 모델은 집계 모드에 포함됩니다. 하나의 기본 URL, 하나의 인증 헤더, 그리고 엔드포인트 전반에 걸쳐 일관된 요청/응답 구조입니다. 평가하려는 이미지 모델마다 SDK와 자격 증명 세트를 각각 연결할 필요 없이, 클라이언트를 HiAPI의 recraft-v4.1/text-to-image 엔드포인트로 지정하기만 하면 나머지 코드는 그대로 유지됩니다. 이는 프로토타입 단계에서 특히 중요합니다. 매번 전송 계층을 다시 작성하지 않고도 프롬프트, 스타일, 모델을 비교할 수 있기 때문입니다.

이 호출을 이해하는 실용적인 방법:

Prompt —— 원하는 이미지에 대한 자연어 설명입니다.
Style —— 출력의 시각적 처리 방식을 안내하는 요청 본문 필드입니다.
Resolution —— 출력 크기를 결정하는 요청 본문 필드입니다.

세 가지 모두 동일한 JSON 본문으로 전송되므로, 프롬프트 엔지니어링과 출력 형태 지정이 한 번의 왕복으로 완료됩니다. 이 엔드포인트가 적합한지 판단 중이라면, 답은 대개 '그렇다'입니다. 동기식이며 프롬프트 기반 이미지 생성이 필요하고, 공급업체의 파이프라인 세부 사항을 애플리케이션 코드 밖으로 빼고 싶을 때 말입니다.

사전 조건 및 인증

첫 호출 전에 다음을 준비하세요:

HiAPI 계정과 API 키. 소스 제어에서 제외하고 환경 변수에서 불러오세요.
빠른 스모크 테스트용 curl, 그리고 requests가 설치된 Python 3(파이썬 예제를 사용할 경우).
실제로 렌더링하고 싶은 프롬프트 —— 조잡해도 연결이 올바른지 검증하기에 충분합니다.

HiAPI의 인증은 요청 헤더 기반입니다. API 키는 헤더로 전달되며, curl, Python 또는 다른 HTTP 클라이언트에서 호출하든 동일한 헤더 패턴을 사용합니다. 모델 선택은 엔드포인트 경로로 이루어지므로, 모델을 전환할 때 인증 헤더는 그대로 유지됩니다.

안전한 로컬 설정은 다음과 같습니다:

export HIAPI_API_KEY="your-key-here"

그런 다음 셸 명령에서는 $HIAPI_API_KEY를, Python에서는 os.environ["HIAPI_API_KEY"]를 참조하세요. 커밋될 수 있는 스크립트에 키를 하드코딩하지 말고, 로그나 오류 보고서에 붙여넣는 것도 피하세요. 키가 유출되면 기록에서 지우려 하지 말고 계정 설정에서 교체하세요.

다음 예제는 두 가지를 가정합니다. HiAPI API의 기본 URL, 그리고 recraft-v4.1/text-to-image의 모델 경로입니다. 구축에 연결하기 전에 계정의 API 참조에서 이 둘을 확인하세요. 정확한 호스트와 경로는 이 가이드에서 기억이 아닌 현재 문서에서 복사해야 하는 유일한 내용이기 때문입니다.

실행 가능한 curl 요청

키, 엔드포인트, 페이로드 구조가 모두 정상 작동하는지 확인하는 가장 빠른 방법은 curl 호출 한 번입니다. 이 요청은 프롬프트와 형태 지정 필드를 담은 JSON 본문을 보내고, 헤더로 API 키를 전달합니다:

curl -X POST "$HIAPI_BASE_URL/recraft-v4.1/text-to-image" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A minimalist isometric illustration of a developer workstation, soft pastel palette, clean background",
    "style": "illustration",
    "resolution": "1024x1024"
  }'

이 호출에 관해 몇 가지 짚을 점:

엔드포인트 경로. 모델 이름이 경로에 있습니다. 나중에 다른 모델로 바꿀 때는 요청을 재구성하는 것이 아니라 해당 경로 세그먼트만 변경합니다.
쿼리 문자열이 아닌 본문. prompt, style, resolution은 모두 JSON 본문에 있습니다. 이렇게 하면 URL이 안정적으로 유지되고 페이로드를 기록하고 재생하기 쉬워집니다.
헤더 인증. Authorization 헤더가 키를 전달하며, Content-Type은 application/json이어야 합니다.

첫 시도에서 200이 아닌 응답을 받았다면 다음 순서로 확인하세요. 셸에 키가 설정되어 있는지, 기본 URL에 중복된 후행 슬래시가 없는지, JSON 본문이 유효한지(후행 쉼표가 흔한 원인입니다). 호출이 성공하면 정확한 명령을 초안 파일에 저장하세요. 알려진 작동하는 curl 호출은 SDK와 클라이언트를 변경할 때마다 비교할 수 있는 기준입니다.

같은 요청을 Python으로

실제 코드에서는 재시도, 로깅, 모델 전환을 위한 통일된 위치를 갖도록 호출을 작은 함수로 감싸세요. requests 사용:

import os
import requests

HIAPI_BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]


def generate_image(prompt, style="illustration", resolution="1024x1024", timeout=120):
    url = f"{HIAPI_BASE_URL}/recraft-v4.1/text-to-image"
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    }
    payload = {
        "prompt": prompt,
        "style": style,
        "resolution": resolution,
    }
    response = requests.post(url, headers=headers, json=payload, timeout=timeout)
    response.raise_for_status()
    return response.json()

유지할 만한 설계 요점:

data=가 아닌 json=. json=에 dict를 전달하면 콘텐츠 유형을 설정하고 본문을 직렬화하므로, 페이로드가 curl 버전과 바이트 단위로 동일합니다.
명시적 타임아웃. 이미지 생성은 즉각적이지 않습니다. 넉넉한 타임아웃은 느리지만 정상인 요청으로 인한 잘못된 실패를 방지합니다. 클라이언트 기본값에 의존하지 마세요.
우선 raise_for_status(). 응답 본문을 읽기 전에 HTTP 오류를 예외로 변환하여, 4xx 또는 5xx가 이미지 데이터로 오인되지 않도록 하세요.
환경 기반 구성. 기본 URL과 키 모두 환경에서 오므로, 함수를 로컬, 스테이징, 프로덕션 환경 간에 이식 가능하게 합니다.

함수는 파싱된 JSON을 반환합니다. 이 JSON에서 이미지를 추출하는 방법은 다음 주제이며, 대부분의 통합이 실패하는 지점입니다.

동기 이미지 응답 처리

recraft-v4.1/text-to-image는 이미지 데이터를 동기적으로 반환합니다. 이미지가 요청과 동일한 HTTP 응답으로 반환되며, 폴링 루프도 추적할 작업 ID도 없습니다. 이는 클라이언트를 단순화하지만, 두 가지 책임을 당신의 코드로 이동시킵니다. 페이로드 디코딩과 실패의 명시적 처리입니다.

견고한 처리 경로는 다음과 같습니다:

파싱 전 상태 확인. 200이 아닌 모든 응답을 오류로 처리하고 응답 본문을 표시하세요. 이는 보통 문제를 설명해 줍니다.
의도적으로 이미지 필드 읽기. 응답 JSON은 이미지 데이터를 담고 있으며, 받은 필드에 따라 URL이거나 인코딩된 이미지 바이트일 수 있습니다. 하나를 가정하지 말고 두 경로 모두 처리하세요.
방어적 디코딩. 페이로드가 base64로 인코딩된 경우 디코딩하여 바이트를 파일에 쓰세요. 바이너리 데이터를 텍스트 전용 경로로 라우팅하거나 터미널에 출력하지 마세요.
페이로드 크기 제한. 동기 이미지 응답은 일반 JSON에 비해 매우 큽니다. 클라이언트가 지원하면 디스크로 스트리밍하고, 여러 응답을 동시에 메모리에 유지하지 마세요.

base64 페이로드에 대한 최소 저장 단계:

import base64

data = generate_image("A calm forest at dawn, soft light")
image_b64 = data["image"]  # adjust to the actual field name in the response
with open("out.png", "wb") as f:
    f.write(base64.b64decode(image_b64))

특별히 처리할 만한 두 가지 실패 모드가 있습니다. 타임아웃은 백오프를 사용해 재시도해야 하지만, 멱등성이 기대되는 경우에만 해당합니다. 이미지를 재생성하면 다른 결과가 나오므로, 시도할 때마다 프롬프트를 기록하세요. 클라이언트 오류(예: 잘못된 본문 형식이나 유효하지 않은 옵션 값)는 재시도로 스스로 해결되지 않습니다. 빠르게 실패하고 응답 텍스트를 기록하세요. 마지막으로, 디코딩 전에 이미지 필드가 존재하는지 검증하여, 스키마 변경이나 오류 페이로드가 혼란스러운 디코딩 오류 대신 명확한 예외를 발생시키도록 하세요.

사용 사례에 맞게 스타일과 해상도 조정

style과 resolution은 반환 결과에 가장 큰 영향을 미치는 두 요청 본문 필드이며, 프롬프트와 함께 전달되므로 반복 비용이 낮습니다.

Style

style은 출력의 시각적 처리 방식을 안내합니다. 일련의 이미지에서 스타일 일관성을 유지하는 데 사용하세요. 예를 들어 제품 일러스트 배치나 기사 헤더 이미지에서 동일한 스타일을 고정하여 한 세트처럼 보이게 할 수 있습니다. 결과가 이상하게 느껴지면 먼저 스타일이 콘텐츠와 맞는지 확인하세요. 일러스트용 스타일을 사실적 프롬프트에 적용하면 텍스트와 충돌합니다. 세부 사항을 추가하기 전에 고정 스타일로 간단한 프롬프트를 시도하여, 나쁜 결과가 스타일 때문인지 표현 때문인지 판단할 수 있게 하세요.

Resolution

resolution은 출력 크기를 결정합니다. 대상 용도에 맞게 설정하세요. 아바타와 썸네일에는 정사각형에 가까운 크기를, 배너와 히어로 이미지에는 더 넓은 크기를 선택하세요. 두 가지 실용 규칙:

요청할 수 있는 것은 확대하지 마세요. 작은 이미지를 생성한 뒤 확대하는 대신, 최종 표시 크기에 가까운 이미지를 직접 생성하세요.
종횡비에 주의하세요. 레이아웃이 특정 비율을 기대한다면, 사후에 자르는 대신 해당 비율에 맞는 해상도를 선택하세요.

예상치 못한 출력 디버깅

이미지가 잘못 보일 때는 한 번에 하나의 변수만 분리하세요. 프롬프트를 고정하고 style을 변경한 다음, 둘 다 고정하고 resolution을 변경하세요. 그래도 해결되지 않으면 형용사를 추가하는 대신 구체적인 명사와 명확한 구도 단서로 프롬프트를 다시 작성하세요. 또한 실수로 잘못된 값 유형을 보내고 있지 않은지 확인하세요. 허용되는 옵션과 일치하지 않는 스타일 문자열은 검증 로직에 따라 거부되거나 무시될 수 있습니다. 호출마다 정확한 요청 본문을 기록하세요. 이것이 어떤 이미지가 어떻게 생성되었는지에 대한 유일하게 신뢰할 수 있는 기록입니다.

프로덕션 환경을 위한 래핑

앞서 만든 작은 함수의 가치는 이를 견고하게 만들 때 드러납니다. 프로덕션급 래퍼는 네 가지를 해야 합니다:

전송 계층 캡슐화. 하나의 함수가 URL, 헤더, 페이로드 구조, 타임아웃을 소유합니다. 호출자는 프롬프트와 옵션만 전달하고 그 외에는 아무것도 전달하지 않습니다.
백오프를 포함한 재시도 추가. 타임아웃과 5xx 응답에 대해 제한된 횟수만큼 재시도하고, 4xx 오류는 절대 재시도하지 마세요. 이미지 생성은 멱등성이 없으므로 재시도 상한을 낮게 설정하고, 프롬프트를 각 시도와 연결해 유지하세요.
결과뿐 아니라 요청도 기록. 프롬프트, 스타일, 해상도, 상태, 소요 시간을 기록하세요. 누군가 이미지가 왜 이렇게 보이는지 물을 때 그 로그가 답입니다.
모델을 매개변수로. 모델 경로를 매개변수로 전달하고 기본값을 recraft-v4.1/text-to-image로 설정하세요. 이렇게 하면 다른 이미지 모델로 전환하는 것이 리팩터링이 아닌 구성 변경이 되어, 나란히 평가하는 비용이 저렴해집니다.

래퍼 계층은 얇게 유지하세요. 캐싱, 큐잉, 저장 정책을 그 안에 추가하는 것은 삼가세요. 그것들은 상위 계층에 속하여 API 호출과 독립적으로 발전할 수 있어야 합니다. 안정적인 인터페이스는 테스트가 전송 계층을 모의하고 전송할 페이로드를 검증할 수 있게 해주며, 이는 대부분의 통합 오류를 실제 요청에 도달하기 전에 잡아냅니다.

인증, 알려진 작동 요청, 명시적 응답 처리를 갖추었으므로, 이제 HiAPI에서 curl과 Python으로 recraft-v4.1/text-to-image를 호출하는 데 필요한 모든 것을 갖추었으며, 이후에는 나머지 코드를 건드리지 않고 모델을 전환할 수 있습니다.