HiAPI API로 grok-imagine/image-to-image를 호출하는 방법: curl 및 Python 가이드

grok-imagine/image-to-image가 개발자에게 제공하는 기능

grok-imagine/image-to-image는 이미지 변환 엔드포인트입니다. 참조 이미지와 프롬프트를 전달하면, 프롬프트를 따르면서도 시각적으로 참조 이미지와 연관성을 유지하는 새 이미지를 반환합니다. 처음부터 생성하는 것이 아니라 가이드된 생성이라고 이해하면 됩니다. HiAPI에서 호출하는 모델 id는 바로 grok-imagine/image-to-image이며, 요청의 나머지 부분은 원하는 변경 사항을 설명하기 위한 것입니다.

출력이 기존 소재의 일부를 반드시 보존해야 하는 경우—배경을 교체해야 하는 제품 사진, 렌더링해야 하는 캐릭터 스케치, 스타일을 바꿔야 하는 구도—에는 텍스트-이미지 호출 대신 이 엔드포인트를 선택해야 합니다. 텍스트-이미지는 소스 이미지 없이 설명만 있는 시나리오에 적합하고, image-to-image는 소스 이미지 자체가 사양의 일부인 시나리오에 적합합니다.

HiAPI가 이를 단일 통합 인터페이스로 노출하므로, 통합 작업은 하나의 요청 구조를 만들고 하나의 응답 구조를 처리하는 것으로 제한됩니다. 모델 계열마다 별도 SDK를 도입하거나 엔드포인트마다 인증 방식을 다시 배울 필요가 없습니다.

요청 분석: 모델, 참조 이미지, 프롬프트

모든 유효한 호출은 개념적으로 네 부분으로 구성됩니다. 코드를 작성하기 전에 각 항목을 제대로 맞춰 두면 이후 디버깅 작업 대부분을 줄일 수 있습니다.

모델 id

model 필드는 문자열 grok-imagine/image-to-image를 담습니다. 코드베이스 곳곳에 흩어진 하드코딩 리터럴이 아니라 클라이언트의 상수로 취급하세요. 나중에 다른 HiAPI 모델을 시도하게 되면 수정할 곳이 하나뿐이기를 원할 것입니다.

참조 이미지

참조 이미지는 앵커입니다. 제공 방식은 선택한 전송 방식에 따라 달라집니다. API가 가져올 수 있는 URL일 수도 있고, 즉석 생성이나 공개 접근이 불가능한 이미지에 적합한 인라인 base64 데이터일 수도 있습니다. 이미 호스팅 중인 소재에는 URL을, 아직 공개 위치에 저장되지 않은 사용자 업로드에는 인라인 데이터를 우선 사용하세요. 어떤 전송 방식을 쓰든 전송 전에 이미지를 검증하세요. 지원되는 형식인지, 크기가 0이 아닌지, 치수가 의미 있을 만큼 충분한지 확인해야 합니다.

프롬프트

프롬프트는 전체 장면이 아니라 변환을 설명합니다. 참조 이미지에 이미 주체가 포함되어 있다면 스타일, 조명, 배경, 재질 등 변경해야 할 내용을 설명하고 변하지 않는 부분은 암묵적으로 남겨 두세요. 참조 이미지에서 이미 보이는 내용을 과도하게 지정하면 도움이 되기보다는 이미지 조건화와 충돌하는 경우가 많습니다.

가로세로 비율 처리

남은 부분은 출력 크기가 어떻게 결정되는지이며, 이는 다음 절의 주제입니다. 요청을 구성하는 코드에서 이 네 부분을 분리하여 각각 독립적으로 검증하고 로그를 남길 수 있게 하세요.

auto aspect 옵션 사용

auto aspect 옵션은 너비와 높이를 직접 고정하는 대신 API가 출력 크기를 선택하게 합니다. 활성화하면 서비스는 요청 컨텍스트—가장 중요하게는 참조 이미지—를 기반으로 적절한 가로세로 비율을 도출하여, 출력 형태가 기본 프레임에 강제로 맞춰지는 대신 입력에 비해 더 합리적으로 만듭니다.

이는 들리는 것보다 중요합니다. 참조 이미지의 비율과 맞지 않는 크기를 고정하면 레터박스 같은 아티팩트, 주체의 어색한 잘림, 소스 이미지의 프레이밍을 무시하는 구도가 발생할 수 있습니다. auto aspect는 기하 구조가 입력을 따르게 하여 이러한 불일치를 피합니다.

auto를 켜 두어야 할 때

• 참조 이미지가 사용자로부터 오고 형태가 다양할 때.
• 프로토타이핑 중이라 어떤 크기가 해당 사용 사례에 적합한지 아직 모를 때.
• 출력이 어차피 다운스트림에서 잘리거나 크기 조정되는 파이프라인으로 들어갈 때.

크기를 명시적으로 고정해야 할 때

• UI나 인쇄 대상에 고정 슬롯이 있어 정확한 출력 기하 구조가 필요할 때.
• 크기가 시각적으로 일관되어야 하는 이미지 배치를 생성할 때.

실용적인 방법은 개발 중에는 auto aspect를 켜 두고, 실제 입력에 대해 API가 반환하는 크기를 확인한 다음, 프로덕션 환경에서 크기를 고정할지 결정하는 것입니다. 반환된 이미지 메타데이터를 요청과 함께 기록하여 이 결정이 추측이 아닌 증거에 기반하도록 하세요.

사용 가능한 curl 요청

아래 요청은 플레이스홀더를 제외하면 완전하며, 플레이스홀더는 꺾쇠괄호로 표시되어 있습니다. 자신의 값으로 바꾸면 바로 실행할 수 있습니다.

curl -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine/image-to-image",
    "prompt": "<describe the transformation you want>",
    "image": "<publicly reachable URL of your reference image>",
    "aspect_ratio": "auto"
  }'

교체해야 할 플레이스홀더

• $HIAPI_API_KEY —— 키를 명령에 붙여 넣지 말고 환경 변수에서 읽으세요. 변수가 설정되지 않으면 요청이 인증 오류로 실패하며, 키가 셸 기록에 남는 일도 없습니다.
• <describe the transformation you want> —— 스타일이나 배경 변경 등 짧고 구체적인 지시.
• <publicly reachable URL of your reference image> —— 서비스가 인증 없이 가져올 수 있는 URL. 소재가 비공개라면 인라인 base64 데이터를 대신 사용하세요.

응답 읽기

처음 실행할 때는 출력을 JSON 포매터로 처리하여 응답 구조를 명확히 확인하세요. 두 가지에 주목해야 합니다. 이미지 페이로드(응답 모드에 따라 URL 또는 인코딩된 데이터일 수 있음)와 호출이 비동기로 처리될 때의 작업 식별자입니다. 개발 중에는 전체 원본 응답을 로그에 보관하세요. 무언가 이상해 보일 때 "실제로 무엇이 반환되었는가"에 답하는 가장 빠른 방법입니다.

같은 요청을 Python으로

Python 버전은 curl 요청과 필드별로 대응해야 합니다. 두 버전을 정렬해 두는 가치는 한 버전에서 재현된 버그를 다른 버전에서 번역을 추측하지 않고도 확인할 수 있다는 점입니다.

import os
import requests

API_URL = "https://api.hiapi.ai/v1/images/generations"
MODEL = "grok-imagine/image-to-image"

def generate_from_reference(prompt: str, image_url: str) -> dict:
    payload = {
        "model": MODEL,
        "prompt": prompt,
        "image": image_url,
        "aspect_ratio": "auto",
    }
    response = requests.post(
        API_URL,
        headers={
            "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=120,
    )
    response.raise_for_status()
    return response.json()

오류 처리는 어디에 두어야 하는가

호출하는 쪽이 아니라 호출을 감싸는 곳에 두세요. response.raise_for_status()는 2xx가 아닌 응답을 예외로 변환하므로, generate_from_reference를 감싸는 단일 try/except가 전송 실패와 API 거부를 모두 포괄할 수 있습니다. 실패 원인에 대한 구조화된 로깅을 원한다면 예외를 발생시키기 전에 함수 내부에서 response.status_code와 오류 본문을 확인하세요.

클라이언트를 깔끔하게 유지하기

시작 시 API 키를 한 번 읽고, 명시적 타임아웃을 설정하며, 원본 응답 객체가 아닌 파싱된 JSON을 반환하세요. 호출자는 HTTP 세부 사항을 알 필요가 없어야 합니다. 테스트에서는 API_URL을 스텁 서버로 지정하여 실제 생성 호출 비용 없이 요청 구성 로직을 검증하세요.

동기 응답과 비동기 응답

일부 image-to-image 요청은 같은 HTTP 응답에서 결과를 반환할 만큼 충분히 빠르게 완료됩니다. 다른 요청은 작업으로 처리됩니다. 초기 호출은 식별자를 반환하고 이미지는 나중에 사용 가능해집니다. 클라이언트는 둘 중 하나를 가정해서는 안 됩니다.

둘을 구분하는 방법

매 호출 후 응답 본문을 확인하세요. 이미지 페이로드를 직접 포함하면 동기 경로에 있는 것이므로 추출하여 반환합니다. 작업 또는 태스크 식별자를 포함하면 비동기 경로에 있는 것이므로 작업이 종료 상태에 도달할 때까지 폴링해야 합니다.

둘 모두를 위해 구조 설계하기

작은 디스패치 함수가 두 경로를 비즈니스 로직 밖으로 밀어낼 수 있습니다.

def resolve_result(response_json: dict) -> dict:
    if "image" in response_json or "data" in response_json:
        return response_json
    job_id = response_json.get("id") or response_json.get("job_id")
    if job_id:
        return poll_until_done(job_id)
    raise RuntimeError(f"Unrecognized response shape: {response_json}")

문제를 피하는 폴링 규칙

• 타이트한 루프 대신 상한이 있는 지수 백오프를 사용하세요.
• 최대 총 대기 시간을 설정하고 초과하면 깔끔하게 실패하세요.
• 모든 비종료 상태를 "계속 대기"로 취급하고, 성공과 실패 두 상태만 최종 상태로 보세요.
• 매 폴링 시 작업 id를 기록하여 로그만으로 멈춘 작업을 추적할 수 있게 하세요.

디스패치 방식은 동기와 비동기 동작 사이를 전환할 때 resolve_result를 호출하는 코드가 절대 바뀔 필요가 없음을 의미합니다.

일반적인 오류 코드 디버깅

이 엔드포인트에서 실패하는 호출 대부분은 몇 가지 범주에 속합니다. 다음 체크리스트를 순서대로 점검하세요. 가장 흔한 원인부터 가장 드문 원인 순으로 나열되어 있습니다.

인증 실패

응답이 인증 문제를 나타내면 키가 누락되었거나, 형식이 잘못되었거나, 전송되지 않은 것입니다. 호출을 실행하는 프로세스에서 환경 변수가 실제로 채워져 있는지, 그리고 헤더가 정확히 Authorization: Bearer <key>인지 확인하세요. 셸에서는 키가 유효한데 서비스에서는 유효하지 않다면 보통 서비스의 환경이 셸 환경과 다르다는 뜻입니다.

참조 이미지 검증 오류

이미지 관련 거부는 보통 네 가지 중 하나를 의미합니다. URL을 공개적으로 가져올 수 없거나, 형식이 지원되지 않거나, 페이로드가 너무 크거나, 이미지가 너무 작거나 손상된 경우입니다. 브라우저에서 자격 증명 없이 해당 URL을 테스트하세요. 브라우저에서 로드되지 않으면 API도 가져올 수 없습니다. 인라인 base64의 경우 인코딩이 순수 base64이며 파라미터가 이를 기대하지 않는 한 data-URL 접두사가 없는지 확인하세요.

프롬프트 및 파라미터 오류

비어 있거나 지나치게 큰 프롬프트, 또는 알 수 없는 파라미터 값은 검증 응답을 낳습니다. 전송한 정확한 페이로드를 오류와 함께 기록하세요. 실패의 상당 부분은 값 문제가 아니라 필드 이름 오타입니다.

속도 제한

속도 제한 응답은 즉시 재시도가 아니라 백오프를 의미합니다. 응답 헤더의 재시도 안내를 따르고, 지터를 추가하며, 재시도 횟수를 제한하세요. 백오프 없는 재시도는 일시적 제한을 지속적 제한으로 바꿉니다.

서버 측 오류

5xx 응답은 서버 측에 속합니다. 백오프와 함께 제한된 횟수로 재시도하고, 지속되면 응답에서 요청 id와 타임스탬프를 캡처하고 조사하는 동안 동시성을 낮추세요.

출시 전 프로덕션 체크리스트

작동하는 요청은 시작일 뿐 끝이 아닙니다. 이 엔드포인트가 실제 트래픽을 처리하기 전에 다음 항목을 확인하세요.

경계에서 입력 검증

요청이 서비스를 떠나기 전에 참조 이미지 형식과 크기, 프롬프트 길이, 파라미터 값을 확인하세요. 잘못된 입력을 로컬에서 거부하는 것이 왕복 한 번보다 빠르고 비용이 적으며, 사용자에게 더 명확한 오류 메시지를 제공합니다.

안전하게 재시도 가능한 요청만 재시도

전송 실패, 속도 제한, 5xx 응답에는 지수 백오프와 지터를 사용하여 재시도하세요. 검증 오류나 인증 오류는 재시도하지 마세요. 같은 방식으로 실패할 뿐 부하만 증가합니다.

실패를 재구성할 만큼 기록

모델 id, 프롬프트의 해시 또는 잘린 형태, 참조 이미지 식별자(전체 페이로드가 아님), 응답 상태, 작업 id(있는 경우), 요청 id를 기록하세요. 이 정보 집합은 보통 민감한 내용을 저장하지 않고도 "무슨 일이 일어났는가"에 답하기에 충분합니다.

키를 코드 밖에 두기

API 키는 환경 또는 비밀 관리자에서 읽고, 소스 코드의 리터럴에서 절대 읽지 마세요. 정기적으로 키를 교체하고 유출이 의심되면 즉시 폐기하세요.

비용 동작 주시

이 엔드포인트의 과금은 생성에 의해 결정되므로 핵심 지렛대는 요청량, 재시도, 폴링 빈도입니다. 재시도 폭풍을 피하고, 폴링에 백오프를 적용하며, 동일한 변환이 반복 요청되는 시나리오에서는 프롬프트와 참조 이미지 기준으로 결과를 캐시하세요. 가정을 하드코딩하지 말고 HiAPI 가격 패널에서 현재 요금을 확인하세요.

순조롭지 않은 경로 테스트

유효하지 않은 이미지 URL, 속도 제한 응답, 절대 완료되지 않는 비동기 작업에 대한 테스트를 작성하세요. 이 세 가지가 프로덕션에 들키지 않고 들어갈 가능성이 가장 높은 실패를 커버합니다.

요청 구성, 응답 디스패치, 오류 처리를 갖추면 grok-imagine/image-to-image는 특별한 경우가 아니라 파이프라인의 일상적인 부분이 됩니다.