튜토리얼

hiapi API로 seedream-4.5/image-to-image 사용하는 방법: curl, Python 및 사용 가능한 요청

Jul 10, 2026

seedream-4.5로 이미지를 편집하려면 hiapi의 통합 작업 API에 POST 요청을 한 번 보내고, 짧게 폴링한 다음 결과를 다운로드하면 됩니다. 본 가이드는 seedream-4.5/image-to-image에 대해 실제로 동작하는 curl 요청과 전체 Python 스크립트, 정확한 입력 필드 설명(실제 API로 검증 완료), 다중 참조 이미지 사용법, 그리고 실제로 마주치게 될 오류들을 제공합니다.

구축할 내용과 필요한 조건

목표: 하나 이상의 소스 이미지에 편집 지시를 더해 seedream-4.5/image-to-image로 전송하고, 완성된 이미지 URL을 받아오는 것입니다.

사전 조건:

hiapi API 키 — 콘솔에서 발급받으세요. 아래 모든 요청에서 Bearer 토큰으로 사용합니다.
소스 이미지가 공개적으로 접근 가능한 URL에 호스팅되어 있어야 합니다. API가 서버 측에서 이미지를 가져오므로, 로컬 파일 경로나 비공개 URL은 사용할 수 없습니다.

이 모델은 비동기 작업 엔드포인트에서 실행됩니다: POST /v1/tasks로 작업을 생성하고, GET /v1/tasks/<taskId>로 상태를 확인하며, 완성된 이미지는 data.output[0].url에 나타납니다.

입력 필드 설명 (검증 완료)

seedream-4.5/image-to-image에는 필수 입력 필드가 네 개 있으며 다른 필드는 허용하지 않습니다 — 필드 스펙이 엄격하여 알 수 없는 필드는 400으로 거부됩니다:

필드	타입	제약
`prompt`	string	편집 지시
`image_urls`	문자열 배열	공개 URL, 최대 14장
`aspect_ratio`	string	`1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `2:3`, `3:2`, `21:9` 중 하나
`resolution`	string	`2K` 또는 `4K`만 가능

주목할 점 두 가지: n 파라미터가 없습니다(작업당 출력 하나 — 여러 변형이 필요하면 작업을 병렬로 여러 개 생성하세요). 또한 1K/2K를 받는 seedream-5.0-pro의 image-to-image와 달리, 4.5는 2K 또는 4K를 요구합니다. 여기에 1K를 보내면 유효성 검사 오류가 반환됩니다.

최소 동작 요청: curl

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-4.5/image-to-image",
    "input": {
      "prompt": "Turn this product shot into a clean studio photo on a seamless white background with soft shadows",
      "image_urls": ["https://your-cdn.example.com/source.jpg"],
      "aspect_ratio": "1:1",
      "resolution": "2K"
    }
  }'

생성에 성공하면 data.taskId에 작업 ID가 반환됩니다. 이를 폴링하세요:

curl -s https://api.hiapi.ai/v1/tasks/<taskId> \
  -H "Authorization: Bearer sk-<your-key>"

data.status가 success에 도달하면 이미지 URL은 data.output[0].url에 있습니다. fail이면 사유는 data.error에 있습니다.

전체 Python 스크립트

SDK는 필요 없습니다 — requests와 폴링 루프만 있으면 됩니다:

import time
import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
API_KEY = "sk-<your-key>"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

def edit_image(prompt: str, image_urls: list[str],
               aspect_ratio: str = "1:1", resolution: str = "2K") -> bytes:
    # 1. 작업 생성
    resp = requests.post(API_BASE, headers=HEADERS, json={
        "model": "seedream-4.5/image-to-image",
        "input": {
            "prompt": prompt,
            "image_urls": image_urls,   # 공개 URL, 최대 14장
            "aspect_ratio": aspect_ratio,
            "resolution": resolution,   # "2K" 또는 "4K"
        },
    }, timeout=60)
    resp.raise_for_status()
    task_id = resp.json()["data"]["taskId"]

    # 2. 최종 상태까지 폴링
    deadline = time.time() + 600
    while time.time() < deadline:
        task = requests.get(f"{API_BASE}/{task_id}",
                            headers=HEADERS, timeout=30).json()["data"]
        if task["status"] == "success":
            url = task["output"][0]["url"]
            # 3. 출력 URL은 만료됨 -- 즉시 다운로드할 것
            return requests.get(url, timeout=120).content
        if task["status"] == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(5)
    raise TimeoutError(f"task {task_id} did not finish in 600s")

png = edit_image(
    "Turn this product shot into a clean studio photo on a seamless white background",
    ["https://your-cdn.example.com/source.jpg"],
)
with open("edited.png", "wb") as f:
    f.write(png)

3단계 주석에 유의하세요: 출력 URL에는 만료 타임스탬프가 붙습니다. 작업이 성공하면 즉시 바이트를 자체 스토리지에 저장하세요 — 반환된 URL만 저장해 두고 내일도 쓸 수 있으리라고 기대하지 마세요.

다중 참조 이미지 편집

image_urls는 한 작업에서 최대 14장의 이미지를 받습니다. 스타일 전이와 구도 작업에 유용합니다: 편집할 이미지와 참조 이미지를 전달하고, prompt에서 이들을 어떻게 조합할지 설명하세요.

{
  "model": "seedream-4.5/image-to-image",
  "input": {
    "prompt": "Apply the color grading and lighting style of the second image to the first image, keep the subject unchanged",
    "image_urls": [
      "https://your-cdn.example.com/subject.jpg",
      "https://your-cdn.example.com/style-reference.jpg"
    ],
    "aspect_ratio": "3:2",
    "resolution": "2K"
  }
}

순서는 prompt에 의미가 있고 API에는 무관합니다 — 모델이 어느 이미지가 어느 것인지 알 수 있도록 위치로 이미지를 참조하세요("첫 번째 이미지", "두 번째 이미지").

프로덕션 환경 주의사항

폴링 대신 콜백을 사용하세요. 스크립트 외의 모든 상황에서는 작업 생성 시 루트 수준 callback 객체를 추가하고 폴링 루프를 완전히 건너뛰세요:

{
  "model": "seedream-4.5/image-to-image",
  "input": { "...": "..." },
  "callback": { "url": "https://yourapp.com/hooks/hiapi", "when": "final" }
}

작업이 완료되면 hiapi가 최종 상태를 귀하의 URL로 POST합니다. 폴링은 CLI 도구와 노트북에는 적합하지만, 웹 백엔드에서는 콜백이 올바른 선택입니다. 그렇지 않으면 2K 편집에 필요한 수십 초 동안 워커 프로세스를 계속 점유하게 됩니다.

멱등성. 작업 생성은 멱등하지 않습니다 — 네트워크 타임아웃 후 재시도하면 두 개의 작업이 생성(및 과금)될 수 있습니다. taskId를 받는 즉시 저장하고, 재시도 시 새 작업을 만들기 전에 이미 활성 작업이 있는지 먼저 확인하세요.

오류 처리. 가장 먼저 마주치게 될 두 가지 실패 유형:

401 permission_denied — 키가 잘못되었거나 해당 키에 이 모델에 대한 접근 권한이 없습니다. 응답 본문은 {"error": {"code": "permission_denied", "message": "This API key cannot use the selected model...", "request_id": "..."}}와 유사합니다. 지원팀에 문의할 때 request_id를 첨부하세요.
400 INVALID_REQUEST — 필드 스펙 위반으로 정확한 메시지가 제공됩니다: resolution 값 오류, image_urls가 14개 초과, 알 수 없는 필드, 또는 image_urls가 배열이 아님. 이들은 모두 작업 실행 전에 잡히므로 비용이 발생하지 않습니다.

실패한 작업은 작업 자체에 status: "fail"과 error 객체를 보고합니다 — 위 Python 스크립트에서처럼 HTTP 오류와는 다른 경우로 처리하세요.

가격

이미지당 비용은 해상도에 따라 다릅니다. 현재 요율은 가격 페이지에서 확인하세요. 검증 단계에서 거부된 요청(400)은 작업을 시작하지 않으므로, 통합 과정에서의 필드 스펙 오류는 무료입니다.

자주 묻는 질문

URL 대신 로컬 파일이나 base64 이미지를 전달할 수 있나요? 아니요. image_urls는 공개적으로 접근 가능한 URL 배열이어야 합니다 — 플랫폼이 서버 측에서 이를 가져와 정규화합니다. 먼저 자체 스토리지(S3, R2, 임의의 CDN)에 업로드한 뒤 URL을 전달하세요.

seedream-4.5 image-to-image는 참조 이미지를 몇 장까지 지원하나요? 작업당 최대 14장입니다. 초과하면 메시지에 image_urls: maxItems가 포함된 400이 반환됩니다.

resolution을 1K로 설정하면 왜 400이 반환되나요? 4.5 image-to-image 엔드포인트는 2K 또는 4K만 허용합니다. 1K 옵션은 seedream-5.0-pro의 image-to-image에 속합니다 — 티어 계열마다 열거형이 다릅니다.

한 요청에서 여러 변형을 생성할 수 있나요? 아니요 — 필드 스펙에 n 파라미터가 없으며 알 수 없는 필드는 거부됩니다. 변형마다 작업을 생성해 병렬로 실행하세요. 각 작업은 출력을 하나만 반환합니다.

결과 URL의 유효 기간은 얼마나 되나요? 출력 URL에는 서명과 만료 시간이 있습니다. 작업 성공 후 즉시 이미지를 다운로드해 직접 저장하고, 작업 출력을 핫링크하지 마세요.

HTTP 오류와 실패한 작업의 차이는 무엇인가요? HTTP 오류(400/401)는 요청이 작업이 되지 못했다는 뜻입니다 — 페이로드나 키를 수정해 다시 보내세요. status: "fail"로 끝난 작업은 수락되었으나 완료되지 못한 것입니다. 사유는 작업의 error 객체에 있으며, 일시적 실패의 경우 동일한 입력으로 재시도하는 것이 보통 올바른 방법입니다.