튜토리얼

AI로 이미지 스타일 바꾸는 방법: hiapi API의 이미지 투 이미지 스타일 전이 가이드

Sep 4, 2026

AI로 사진 스타일을 바꾸는 것—즉흥적으로 찍은 사진을 애니메이션 프레임, 스튜디오 제품 사진, 수채화 일러스트로 바꾸는 것—은 특별한 "스타일 전이" 엔드포인트가 아닙니다. 그저 평범한 이미지 투 이미지 호출일 뿐입니다: 원본 이미지와 목표 스타일을 지정하는 텍스트 지시를 보내면 모델이 새 이미지를 반환합니다. 깔끔한 스타일 변경이 되는지, 아니면 반쯤 새로 생성되는지를 실제로 결정하는 것은 조정 가능한 파라미터가 아니라 이 지시를 어떻게 작성하느냐입니다. 이 가이드에서는 hiapi 통합 tasks API의 요청 메커니즘, 스타일 변경이 새 이미지 생성으로 벗어나는 것을 막는 프롬프트 패턴, 그리고 원하는 창작 자유도에 따라 두 가지 검증된 이미지 투 이미지 모델 중에서 선택하는 방법을 다룹니다.

준비해야 할 것

hiapi API 키—대시보드에서 발급받으세요. 모든 요청의 Authorization: Bearer sk-... 헤더에 들어갑니다.
공개적으로 접근 가능한 원본 이미지 URL. hiapi 서버가 이미지를 직접 가져오므로 localhost 경로나 서명 URL이 없는 프라이빗 버킷은 사용할 수 없습니다. 미리 서명된 S3/R2/GCS URL은 괜찮습니다.

아래의 모든 모델 id와 필드는 게시 전에 라이브 API를 대상으로 다시 검증되었으며, 현재의 열거 값을 확인하기 위한 강제 오류 프로브도 포함되었습니다.

스타일 변경에 "보존 조항"이 필요한 이유

이 가이드의 두 모델 모두 숫자 형태의 강도나 세기 파라미터를 제공하지 않습니다—하나라도 보내면(strength: 0.5) additional properties 'strength' not allowed 오류와 함께 바로 거부됩니다. 스타일 강도는 전적으로 프롬프트 문구로 제어되며, 이는 "make this a Studio Ghibli anime frame" 같은 지시가 모델에게 무엇을 추가할지만 알려주고 무엇을 그대로 둘지는 알려주지 않는다는 뜻입니다—피사체 정체성, 포즈, 구도가 모두 모델에 의해 자유롭게 재해석될 수 있습니다.

해결책은 프롬프트에 항상 두 개의 절을 쓰는 것입니다:

목표 스타일을 구체적인 시각적 참조(매체, 예술 사조, 특정한 느낌—"anime cel-shading", "1970s film photography", "clean studio product shot on white")로 명시하되, "cooler" 같은 모호한 형용사는 쓰지 않습니다.
명시적인 보존 조항—바뀌면 안 되는 것을 지목합니다: "keep the same subject, pose, and composition", "keep the text and logo unchanged", "keep the camera angle".

"Restyle this photo as a woodblock print. Keep the subject's pose, framing, and the position of every object in the scene." 같은 프롬프트는 한 지시 안에서 모델에게 목표와 제약을 동시에 주며, 이것이 재생성이 아닌 스타일 변경을 얻는 가장 큰 지렛대입니다.

최소 동작 예시: curl

이 예시는 seedream-5.0-pro/image-to-image를 사용하며, 스타일 변경 효과가 좋고 엄격하게 완전 검증된 스키마를 가집니다:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-pro/image-to-image",
    "input": {
      "prompt": "Restyle this portrait as a watercolor painting with visible brush texture and soft bleeding edges. Keep the subject'\''s pose, expression, and framing exactly as in the source.",
      "image_urls": ["https://your-bucket.example.com/portrait.jpg"],
      "aspect_ratio": "3:4",
      "resolution": "2K"
    }
  }'

aspect_ratio는 필수이며 고정 열거 값에서 선택합니다—현재 1:1, 4:3, 3:4, 16:9, 9:16, 2:3, 3:2, 21:9입니다. 이 엔드포인트에는 "원본에 맞추기" 옵션이 없으므로 원본 이미지의 실제 비율에 가장 가까운 값을 선택하세요(세로 사진 → 3:4 또는 9:16, 16:9가 아님). 그래야 모델이 맞추기 위해 구도에 여백을 추가하거나 잘라내지 않습니다.

성공적으로 생성되면 data.taskId에 작업 id가 반환됩니다:

{ "data": { "taskId": "<your-task-id>" } }

종료 상태가 될 때까지 폴링합니다:

curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

data.status는 최종적으로 success(출력은 data.output[0].url) 또는 fail(상세는 data.error)이 됩니다.

전체 Python 스크립트: 생성, 폴링, 다운로드

표준 라이브러리만 사용합니다:

import json
import time
import urllib.request

API = "https://api.hiapi.ai/v1/tasks"
KEY = "sk-YOUR_KEY"


def call(url, payload=None):
    req = urllib.request.Request(
        url,
        data=json.dumps(payload).encode() if payload is not None else None,
        headers={
            "Authorization": f"Bearer {KEY}",
            "Content-Type": "application/json",
        },
        method="POST" if payload is not None else "GET",
    )
    with urllib.request.urlopen(req) as resp:
        return json.load(resp)


# 1. Create the restyle task
create = call(API, {
    "model": "seedream-5.0-pro/image-to-image",
    "input": {
        "prompt": (
            "Restyle this street photo as a 1980s film-grain photograph with warm, "
            "faded colors. Keep the same subject, pose, and every object in the "
            "same position in the frame."
        ),
        "image_urls": ["https://your-bucket.example.com/street.jpg"],
        "aspect_ratio": "16:9",
        "resolution": "2K",
    },
})
task_id = create["data"]["taskId"]
print("task created:", task_id)

# 2. Poll until terminal state
while True:
    task = call(f"{API}/{task_id}")["data"]
    if task["status"] == "success":
        break
    if task["status"] == "fail":
        err = task.get("error") or {}
        raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
    time.sleep(5)

# 3. Download immediately -- output URLs expire
image_url = task["output"][0]["url"]
urllib.request.urlretrieve(image_url, "restyled.png")
print("saved restyled.png")

원하는 창작 자유도에 따라 모델 선택하기

두 모델 모두 온라인에서 다시 검증되었고 strength 파라미터를 받지 않지만, 원본 이미지의 영향력을 얼마나 세밀하게 제어할 수 있는지에서 차이가 있습니다:

	`seedream-5.0-pro/image-to-image`	`grok-imagine-quality/image-to-image`
참조 이미지	공개 URL 1–10개	공개 URL 1–3개
`resolution`	`1K` / `2K` (대문자)	`1k` / `2k` (소문자)—선택 사항
구도 제어	고정된 8값 `aspect_ratio` 열거, 자동 맞춤 없음	`aspect_ratio: "auto"`가 입력 화면을 따름
최적 용도	정확한 단일 참조 이미지 스타일 변경이며 목표 비율을 이미 아는 경우	빠른 스타일 변경, 출력이 원본의 정확한 구도를 물려받길 원하며 직접 비율을 선택하고 싶지 않은 경우

보존 조항에 "same framing"이 포함되어 있고 원본 이미지의 화면 비율을 수동으로 계산하고 싶지 않다면, grok-imagine-quality/image-to-image를 사용하고 aspect_ratio: "auto"로 설정하는 것이 더 직접적인 경로입니다—위 요청에 그대로 바꿔 넣고, image_urls는 최대 3개, resolution은 소문자 2k로 설정하세요.

프로덕션 환경 주의사항

서버에서는 폴링보다 콜백을 우선 사용하세요. 요청 시 callback 객체를 추가하면 hiapi가 종료 상태가 되었을 때 한 번 POST하므로 폴링할 필요가 없습니다:

{
  "model": "seedream-5.0-pro/image-to-image",
  "input": { "...": "..." },
  "callback": { "url": "https://your-server.example.com/hiapi-hook", "when": "final" }
}

콜백 페이로드는 진실의 원천이 아니라 신호로 취급하세요—그로부터 작업 id를 얻고, 행동하기 전에 직접 GET /v1/tasks/<id>로 다시 가져오세요. 스크립트와 노트북에서는 5초마다 폴링하면 충분합니다.

재시도를 멱등하게 만드세요. 작업 생성 시 자신의 원본 이미지 → taskId 매핑을 저장하세요. 프로세스가 폴링 도중에 죽으면 재시작 후 재제출하지 말고 저장된 taskId를 다시 연결해야 합니다—재제출은 두 번째 과금 작업입니다.

실제로 마주치게 될 오류:

401 permission_denied—키 형식이 잘못되었거나 누락되었습니다. 헤더는 반드시 Authorization: Bearer sk-...여야 합니다.
400 INVALID_REQUEST—스키마 위반입니다. 예: aspect_ratio: value must be one of '1:1', '4:3', ... 또는 additional properties 'strength' not allowed. 두 모델의 스키마는 모두 엄격합니다—모델 계열 간에 파라미터를 섞어 쓰지 마세요.
image_urls must be an array—참조 이미지가 하나뿐이어도 목록이 아닌 순수 문자열을 전달한 경우입니다.

자주 묻는 질문

스타일 전이에 강도나 세기 슬라이더가 있나요? 없습니다. 이 가이드의 두 모델 모두 strength 필드를 받지 않습니다—보내면 인식되지 않는 속성으로 간주되어 거부됩니다. 스타일 강도는 전적으로 프롬프트의 스타일 설명이 얼마나 구체적이고 강한지로 제어됩니다.

모델이 피사체의 포즈나 정체성을 바꾸지 않게 하려면 어떻게 하나요? 프롬프트에 명시적인 보존 조항을 추가해 반드시 그대로 유지해야 할 것—포즈, 표정, 구도, 물체 위치—을 지목하세요. 제약이 암시가 아니라 명시적으로 적혀 있을 때 모델은 스타일을 더 보수적으로 바꿉니다.

원본 이미지의 정확한 화면 비율을 자동으로 유지할 수 있나요? grok-imagine-quality/image-to-image에서는 가능합니다—aspect_ratio: "auto"로 설정하세요. seedream-5.0-pro/image-to-image에는 자동 옵션이 없습니다; 고정 열거에서 원본 이미지의 실제 비율에 가장 가까운 값을 선택하세요.

원본 이미지가 반드시 공개 URL이어야 하나요? hiapi 서버가 HTTPS로 가져올 수 있어야 합니다. 프라이빗 버킷의 미리 서명된 URL은 괜찮습니다; localhost나 인증되지 않았고 접근 불가능한 경로는 안 됩니다.

한 사진에서 여러 스타일 변형을 병렬로 생성할 수 있나요? 가능합니다—각 변형은 독립적인 작업입니다. 동일한 image_urls와 서로 다른 스타일 지시로 여러 번 POST /v1/tasks를 호출한 뒤 각 taskId를 개별적으로 폴링하거나 콜백을 사용하세요.

스타일 변경과 인페인팅 또는 객체 제거의 차이는 무엇인가요? 스타일 변경은 내용을 그대로 유지하면서 전체 이미지의 렌더링 방식을 바꾸고, 인페인팅/객체 제거는 렌더링 스타일을 그대로 유지하면서 특정 영역을 바꿉니다. 이들은 같은 종류의 이미지 투 이미지 엔드포인트 위에서 서로 다른 프롬프트 패턴일 뿐입니다—실제로 필요한 것이 인페인팅과 객체 제거라면 인페인팅 및 객체 제거 가이드를 참고하세요.

핵심 요점

스타일 변경 프롬프트는 두 부분으로 작성하세요: 먼저 목표 스타일, 그다음 바뀌면 안 되는 것(포즈, 구도, 물체 위치)을 지목하는 명시적 보존 조항.
검증된 두 모델 모두 강도/세기 파라미터가 없습니다—스타일 강도는 전적으로 프롬프트의 스타일 설명이 얼마나 강한지에서 나옵니다.
seedream-5.0-pro/image-to-image의 aspect_ratio는 고정된 8값 열거이며 자동 맞춤 옵션이 없습니다; 원본 이미지에 가장 가까운 비율을 직접 선택하세요.
grok-imagine-quality/image-to-image는 aspect_ratio: "auto"를 지원해 입력 이미지 자체의 구도를 따릅니다—비율을 수동으로 계산하고 싶지 않을 때 유용합니다.
서버에서는 폴링 대신 callback.url과 when:"final"을 사용하고, 충돌 재시도 시 재제출하지 않고 다시 연결할 수 있도록 자신의 원본 이미지 → taskId 매핑을 저장하세요.