Grok Image 2.0 이미지 투 이미지 API 사용법은? 참조 이미지 한 장과 한 문장으로 이미지 편집하기

Grok Image 2.0 이미지 투 이미지 API 사용법은? 공개 접근 가능한 참조 이미지 한 장과 편집 지시문 한 문장을 전달하고 POST /v1/tasks로 제출한 뒤, 폴링하여 data.output[0].url을 받으면 그것이 편집된 이미지입니다. 이미지당 고정 $0.065이며 1K와 2K가 동일 가격이고, 마스크도 레이어도 필요 없습니다.

Grok Image 2.0은 HiAPI에 출시되었습니다. 이미지 투 이미지 모델 페이지 열기에서 이미지 한 장을 업로드하면 편집할 수 있으며, 신규 사용자 가입 시 200 크레딧을 지급하여 이미지 투 이미지 1장(130 크레딧)을 생성하기에 충분합니다.

TL;DR

• 무엇인가: grok-imagine-image-2.0/image-to-image, xAI 제작, 단일 참조 이미지에 자연어 지시문을 더해 이미지를 편집하며 배경 교체, 소품 추가, 재질·색상 변경이 모두 가능합니다.
• 얼마인가: 이미지당 $0.065, 1K / 2K, low / medium 가격 동일; 성공적으로 생성된 이미지 기준으로 과금되며 실패 시 자동 환불됩니다. $10으로 약 153장 생성.
• 가장 빠른 호출 방법: 필수 항목은 prompt와 image 두 개뿐이며, image는 URL 문자열 하나이지 배열이 아닙니다.

Grok Image 2.0 이미지 투 이미지에는 어떤 파라미터가 있나요?

필드	필수	값	설명
prompt	예	문자열	편집 지시문
image	예	문자열	공개 접근 가능한 JPG / JPEG / PNG / WebP URL 하나, 배열 아님
resolution	아니오	1k, 2k	기본값 1k
quality	아니오	low, medium	기본값 medium; medium은 디테일이 더 좋고 low는 더 빠름
aspect_ratio	아니오	텍스트 투 이미지와 동일한 14개 값	전달할 수 있지만 적용되지 않으며, 출력 화면 비율은 참조 이미지를 따름

한 번에 참조 이미지 한 장만 편집할 수 있고, 한 작업에 이미지 한 장이 출력됩니다. 여러 장은 여러 작업을 제출하여 동시에 실행하세요. 필드명과 값이 위 표에 없는 요청은 400을 반환합니다.

온라인 체험과 API 두 가지 경로

온라인 체험 (1분)

1. 이미지 투 이미지 모델 페이지를 열고 로그인한 뒤 참조 이미지를 업로드합니다.
2. 편집 지시문을 입력하고 해상도를 선택합니다.
3. 「실행」을 클릭하고 작업이 성공하면 참조 이미지와 결과 이미지를 비교합니다.

API 연동 (5분)

1. 콘솔에서 API Key를 생성합니다.
2. 참조 이미지를 공용 인터넷에서 접근 가능한 주소(자체 CDN 또는 오브젝트 스토리지)에 올립니다.
3. POST /v1/tasks로 작업을 제출하고 폴링하거나 콜백을 설정합니다.
4. 성공하면 즉시 data.output[0].url을 다운로드합니다.

Keep the elderly luthier exactly as he is: his face, expression, hands, seated pose, and the checked flannel shirt he's wearing, completely unchanged. Replace only the background environment: move him from the wood-shaving workshop into a sunlit outdoor market stall with hanging string instruments and warm afternoon light, matching the new environment's light direction so it falls naturally across his face and hands.

편집 프롬프트를 바로 사용해 보세요: 노인 악기 장인을 나무 부스러기 작업장에서 햇살 비치는 시장으로 옮기되 인물은 그대로 유지합니다. 이 프롬프트로 생성 → (링크는 프롬프트만 미리 채우며, 참조 이미지는 모델 페이지에서 직접 업로드하고 해상도는 2K를 선택하세요)

참조 이미지	결과 이미지

curl과 Python: 첫 이미지 편집 성공시키기

먼저 API Key를 설정합니다:

export HIAPI_API_KEY="sk-..."

모든 요청에는 Authorization: Bearer sk-<key>를 포함합니다. 이미지 편집은 비동기이며 HiAPI의 다른 모델과 동일한 작업 인터페이스를 공유합니다. 참조 이미지는 서버 측에서 가져오므로 로컬 파일 경로는 안 되고 반드시 공용 인터넷에서 접근 가능한 URL이어야 합니다.

1단계, 작업 생성:

curl --fail-with-body -sS -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-2.0/image-to-image",
    "input": {
      "prompt": "Change the mug on the table to matte black ceramic, keep everything else in the scene identical",
      "image": "https://your-cdn.example.com/source-photo.jpg",
      "resolution": "2k"
    }
  }'

즉시 taskId를 반환합니다:

{
  "code": 200,
  "message": "success",
  "data": { "taskId": "tk-hiapi-01M01JW1C9N3VHRZAEBFEESC5Q" }
}

2단계, 종료 상태까지 폴링:

curl --fail-with-body -sS https://api.hiapi.ai/v1/tasks/tk-hiapi-01M01JW1C9N3VHRZAEBFEESC5Q \
  -H "Authorization: Bearer $HIAPI_API_KEY"

data.status를 확인합니다: success는 성공, fail은 실패이며 그 외 상태는 계속 대기합니다. 성공 응답 예시:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M01JW1C9N3VHRZAEBFEESC5Q",
    "status": "success",
    "storage": "temp",
    "output": [
      {
        "type": "image",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M01JW1C9N3VHRZAEBFEESC5Q-0.jpg",
        "artifactId": "76711",
        "expireAt": 1787364206
      }
    ]
  },
  "message": "success"
}

storage: "temp"와 expireAt에 유의하세요: 결과 이미지 주소는 임시이므로 작업 완료 후 즉시 다운로드하거나 자체 오브젝트 스토리지로 전송하세요. 출력 화면 비율은 참조 이미지를 따르므로 예시에서는 적용되지 않는 aspect_ratio를 생략했습니다.

Python 버전:

먼저 requests를 설치하고(python3 -m pip install requests) 위의 HIAPI_API_KEY를 설정합니다. 스크립트는 최대 10분 동안 폴링하며, 초과 후에는 taskId를 보관하여 계속 조회하세요.

import os
import time
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def task_data(response):
    response.raise_for_status()
    body = response.json()
    if body.get("code") != 200:
        raise RuntimeError(f"HiAPI request failed: {body}")
    return body["data"]


def edit_image(prompt: str, image_url: str, resolution: str = "1k") -> str:
    create = requests.post(
        f"{BASE}/tasks",
        headers=HEADERS,
        json={
            "model": "grok-imagine-image-2.0/image-to-image",
            "input": {
                "prompt": prompt,
                "image": image_url,
                "resolution": resolution,
            },
        },
        timeout=30,
    )
    task_id = task_data(create)["taskId"]
    print(f"taskId: {task_id}", flush=True)
    deadline = time.monotonic() + 600

    while time.monotonic() < deadline:
        poll = requests.get(f"{BASE}/tasks/{task_id}", headers=HEADERS, timeout=30)
        data = task_data(poll)
        if data["status"] == "success":
            return data["output"][0]["url"]
        if data["status"] == "fail":
            raise RuntimeError(f"task {task_id} failed: {data}")
        time.sleep(2)
    raise TimeoutError(f"task {task_id} is still pending; query this ID instead of submitting again")


if __name__ == "__main__":
    url = edit_image(
        "Change the mug on the table to matte black ceramic, keep everything else identical",
        "https://your-cdn.example.com/source-photo.jpg",
        resolution="2k",
    )
    print(url)

출시 전에 무엇을 주의해야 하나요?

• 참조 이미지를 먼저 공용 인터넷에 올리세요. 사용자가 업로드한 이미지가 프라이빗 버킷이나 localhost에 있으면 플랫폼이 가져오지 못해 작업이 비동기로 실패합니다. 제출 전에 링크가 공개 접근 가능한지 확인하고, 만료되는 서명 링크가 아닌 장기 유효 주소를 사용하세요.

• 지시문은 "무엇을 유지하고 무엇만 바꿀지"로 작성하세요. 반드시 변하지 않아야 할 부분을 먼저 쓰고, 변경할 부분을 나중에 쓰며, 변경 범위가 좁을수록 안정적입니다. 더 많은 작성법은 이미지 투 이미지 프롬프트 템플릿을 참고하세요.

• 배치는 콜백을 사용하고 촘촘한 루프 폴링은 피하세요.

  {
    "model": "grok-imagine-image-2.0/image-to-image",
    "input": { "prompt": "...", "image": "https://your-cdn.example.com/source-photo.jpg" },
    "callback": { "url": "https://your-service.example.com/hooks/hiapi", "when": "final" }
  }
  

  when: "final"은 작업이 성공 또는 실패 종료 상태에 도달했을 때 알리며, 수신 측은 taskId로 중복을 제거합니다.

• 결과 이미지를 즉시 전송하세요. data.output[0].url은 임시 주소이며 expireAt에 따라 만료됩니다.

• 작업은 한 번만 제출하세요. 응답을 받으면 taskId와 비즈니스 작업의 대응 관계를 저장하세요. 중복 제출은 여러 작업을 생성하여 각각 과금될 수 있습니다. 생성 요청이 타임아웃되어 ID를 받지 못한 경우, 먼저 작업 기록을 확인한 뒤 재제출 여부를 결정하세요.

• resolution을 명시하세요. 기본값은 1k이며, 1K와 2K는 동일 가격($0.065)이므로 최종본에는 "2k"를 바로 전달하세요.

• 오류 처리. 먼저 HTTP 상태와 응답의 code, message를 확인한 뒤 data를 읽으세요. 파라미터나 인증 오류는 수정 후 다시 제출하고, 작업이 fail을 반환하면 오류를 기록하고 폴링을 중지하세요.

관련 읽기

• Grok Image 2.0 텍스트 투 이미지 모델 페이지: 같은 시리즈, 텍스트만으로 새 이미지 생성.
• Grok Image 2.0 API 가격은 얼마인가요?
• Grok Image 2.0 텍스트 투 이미지 API 연동
• Grok Image 2.0 이미지 투 이미지 프롬프트 템플릿
• 인증과 빠른 시작

자주 묻는 질문

image는 URL 하나인가요, 배열인가요? 문자열 URL 하나입니다. 배열을 전달하면 타입 오류가 발생합니다. 여러 이미지를 융합해야 할 때는 여러 참조 이미지를 지원하는 모델로 변경하세요.

"additional properties not allowed"가 발생하면 어떻게 하나요? input은 prompt, image, aspect_ratio, resolution, quality만 허용합니다. 다른 편집 모델에서 흔히 쓰는 image_urls, strength, mask, seed, negative_prompt는 여기서 사용할 수 없으므로 삭제하세요.

브라우저에서 참조 이미지가 열리는데 왜 작업이 여전히 실패할 수 있나요? 플랫폼은 서버 측에서 이미지를 가져오므로 참조 이미지는 로그인 없이 공용 인터넷에서 접근 가능해야 하며, 서명 링크는 가져오기가 완료될 때까지 유효해야 합니다. 접근 권한, 형식, 링크 유효 기간을 확인한 뒤 제출하세요.

한 번에 여러 이미지를 편집할 수 있나요? 아니요, 이미지 한 장이 입력되고 한 장이 출력됩니다. 배치는 여러 작업을 제출하여 동시에 실행하세요.

이미지 투 이미지가 텍스트 투 이미지보다 왜 비싼가요? 이미지 투 이미지는 $0.065, 텍스트 투 이미지는 $0.052로 25% 더 비싸며, "참조 이미지 한 장을 가지고 이미지를 편집"하는 기능에 해당합니다.

출력 주소는 얼마나 유효한가요? 임시 스토리지이며, 응답의 expireAt은 Unix 타임스탬프입니다. 작업 성공 후 즉시 다운로드하거나 전송하세요.

결과를 동기로 기다려야 하나요? 아니요. 생성 인터페이스는 작업이 대기열에 들어간 후 즉시 반환됩니다. 짧은 스크립트는 GET /v1/tasks/<taskId>로 폴링하고, 프로덕션 환경에서는 callback을 설정하세요.

지금 바로 첫 이미지를 편집하세요

먼저 HIAPI_API_KEY를 설정한 뒤 curl 및 Python 예제의 image 주소를 자신의 공용 이미지 URL로 교체하세요. 먼저 결과를 보고 싶다면 이미지 투 이미지 모델 페이지를 열고 이미지를 업로드한 뒤 위의 프롬프트를 붙여넣으세요.