---
title: "캐릭터 일관성 유지"
description: "PixAI API로 여러 이미지에서 애니 캐릭터를 같은 모습으로 유지합니다. Tsubaki.3에 참조 이미지를 최대 3장 보내고, 각 이미지에서 무엇을 가져올지 프롬프트에 적습니다."
canonical: "https://platform.pixai.art/ko/docs/quick-start/examples/consistent-characters"
last-updated: "2026-11-17"
---

# 캐릭터 일관성 유지

PixAI API로 여러 이미지에서 애니 캐릭터를 같은 모습으로 유지합니다. Tsubaki.3에 참조 이미지를 최대 3장 보내고, 각 이미지에서 무엇을 가져올지 프롬프트에 적습니다.





`POST /v2/image/create`의 `contextImages`에 참조 이미지를 보내면 Tsubaki.3가 이를 바탕으로 그립니다. 같은 캐릭터를 새로운 장면에 그리거나, 한 이미지의 캐릭터를 다른 이미지의 포즈로 그리거나, 마음에 드는 이미지를 조금만 수정할 수 있습니다.

기본 URL: `https://api.pixai.art/v2`. 모든 요청에 `Authorization: Bearer YOUR_API_KEY`를 추가하세요. API 키 발급 방법은 [PixAI API를 사용하려면?](/ko/docs/quick-start/enroll-in-api)을 참고하세요.

<Callout type="info">
  참조 이미지는 Tsubaki.3(`modelVersionId` `2024383379556065549`)에서만 사용할 수 있습니다. 최대 3장까지 보낼 수 있으며, 각 이미지는 가로와 세로 모두 4000px 미만이어야 합니다.
</Callout>

단계 [#단계]

<div className="fd-steps">
  <div className="fd-step">
    참조 이미지별 미디어 ID 준비 [#참조-이미지별-미디어-id-준비-step]

    `contextImages`에는 미디어 ID를 지정합니다. API로 생성한 이미지에는 작업의 `outputs.mediaIds`에 이미 미디어 ID가 있으므로, 캐릭터를 한 번 생성한 뒤 그 ID를 이후의 모든 이미지에 재사용하세요.

    직접 가진 파일을 사용하려면 업로드합니다. 업로드 URL을 요청하고, 바이트를 `PUT`한 뒤 등록합니다. 등록 응답의 `id`가 미디어 ID입니다.

    ```bash
    curl -X POST https://api.pixai.art/v2/media/image/upload-url \
      -H "Authorization: Bearer $PIXAI_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{}'
    # → {"uploadUrl": "...", "externalId": "..."}

    curl -X PUT "UPLOAD_URL" -H "Content-Type: image/png" --data-binary @character.png

    curl -X POST https://api.pixai.art/v2/media/image/register \
      -H "Authorization: Bearer $PIXAI_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"externalId": "EXTERNAL_ID"}'
    # → {"id": "MEDIA_ID", "type": "IMAGE", ...}
    ```
  </div>

  <div className="fd-step">
    프롬프트 작성 [#프롬프트-작성-step]

    참조 이미지는 `contextImages`의 순서대로 `image1`, `image2`, `image3`으로 부릅니다. 지시는 영어 문장으로 작성하세요. 무엇을 만들지, 각 이미지에서 무엇을 유지할지 적습니다.

    | 목적             | 프롬프트 예시                                                                                                                               |
    | :------------- | :------------------------------------------------------------------------------------------------------------------------------------ |
    | 같은 캐릭터, 새로운 장면 | `Draw the girl from image1 sitting in a café by the window on a rainy day. Keep her face, hair and outfit exactly as in image1.`      |
    | 다른 포즈의 캐릭터     | `Redraw the character in image1 in the pose shown in image2. Keep her outfit, hair color and face exactly as in image1.`              |
    | 일부만 수정         | `Change the girl's navy coat to a bright red coat. Keep everything else in image1 as it is: her face, hair, pose and the background.` |

    수정할 때는 바뀌면 안 되는 부분을 명시하세요. 프롬프트에 적지 않은 부분은 바뀔 수 있습니다.
  </div>

  <div className="fd-step">
    이미지 생성 [#이미지-생성-step]

    ```bash
    curl -X POST https://api.pixai.art/v2/image/create \
      -H "Authorization: Bearer $PIXAI_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "modelVersionId": "2024383379556065549",
        "contextImages": ["CHARACTER_MEDIA_ID", "POSE_MEDIA_ID"],
        "prompt": "Redraw the character in image1 in the pose shown in image2. Keep her outfit, hair color and face exactly as in image1. Anime illustration, soft cel shading.",
        "aspectRatio": "2:3"
      }'
    ```

    그다음 [첫 번째 API 호출](/ko/docs/quick-start/first-api-call)과 같이 `status`가 `completed`가 될 때까지 `GET /v2/task/{id}`를 폴링하고 `outputs.mediaUrls`를 다운로드합니다.

    존재하지 않는 미디어 ID를 지정하면 `404 FILE_NOT_FOUND`가 반환됩니다.

    <Callout type="warn">
      종횡비는 참조 이미지와 같게 지정하세요. 세로형 참조 이미지에 `"aspectRatio": "3:2"`를 지정한 테스트에서는 세로형 그림 좌우에 빈 띠가 붙었고, 띠가 너비의 절반 이상을 차지했습니다.
    </Callout>
  </div>

  <div className="fd-step">
    결과 이어서 사용하기 [#결과-이어서-사용하기-step]

    완료된 이미지마다 고유한 미디어 ID가 있습니다. 이 ID를 다시 `contextImages`에 넣으면 한 캐릭터로 시리즈를 만들 수 있습니다. 캐릭터 시트를 한 번 생성하고 모든 장면에서 참조하세요.
  </div>
</div>

전체 스크립트 [#전체-스크립트]

캐릭터를 생성한 뒤, 그 캐릭터를 참조 이미지로 두 장면을 더 생성합니다. 먼저 환경 변수 `PIXAI_API_KEY`를 설정하세요.

<Tabs items="['Python', 'JavaScript']">
  <Tab value="Python">
    `requests`를 설치한 상태에서 실행합니다.

    ```python
    import os
    import time

    import requests

    API = "https://api.pixai.art/v2"
    HEADERS = {"Authorization": f"Bearer {os.environ['PIXAI_API_KEY']}"}
    TSUBAKI_3 = "2024383379556065549"


    def generate(prompt, context_images=(), aspect_ratio="2:3"):
        """이미지를 생성하고, 완료될 때까지 기다린 뒤 작업을 반환합니다."""
        body = {"modelVersionId": TSUBAKI_3, "prompt": prompt, "aspectRatio": aspect_ratio}
        if context_images:
            body["contextImages"] = list(context_images)
        resp = requests.post(f"{API}/image/create", headers=HEADERS, json=body)
        resp.raise_for_status()
        task = resp.json()
        while task["status"] in ("waiting", "running"):
            time.sleep(2)
            resp = requests.get(f"{API}/task/{task['id']}", headers=HEADERS)
            if resp.status_code == 404:  # 생성 직후의 작업은 잠시 404를 반환할 수 있습니다. 계속 폴링합니다.
                continue
            resp.raise_for_status()
            task = resp.json()
        if task["status"] != "completed":
            raise SystemExit(f"Task ended as {task['status']}: {task.get('taskStatusMsgI18n')}")
        return task


    def save(task, name):
        url = task["outputs"]["mediaUrls"][0]
        with open(name, "wb") as f:
            f.write(requests.get(url).content)


    character = generate(
        "A full-body anime illustration of a girl with short silver hair and blue eyes, "
        "wearing a navy coat and a red scarf, standing on a plain white background."
    )
    save(character, "character.webp")
    ref = character["outputs"]["mediaIds"][0]

    scenes = {
        "cafe.webp": "Draw the girl from image1 reading a book in a café by the window on a rainy day. "
        "Keep her face, hair and outfit exactly as in image1.",
        "beach.webp": "Draw the girl from image1 walking along a beach at sunset, carrying her coat. "
        "Keep her face, hair and scarf exactly as in image1.",
    }
    for name, prompt in scenes.items():
        save(generate(prompt, context_images=[ref], aspect_ratio="2:3"), name)
    ```
  </Tab>

  <Tab value="JavaScript">
    Node.js 20 이상에서 `characters.mjs`로 저장해 실행합니다.

    ```js
    import { writeFile } from 'node:fs/promises';

    const API = 'https://api.pixai.art/v2';
    const HEADERS = {
      Authorization: `Bearer ${process.env.PIXAI_API_KEY}`,
      'Content-Type': 'application/json',
    };
    const TSUBAKI_3 = '2024383379556065549';

    async function call(path, init = {}) {
      const res = await fetch(`${API}${path}`, { headers: HEADERS, ...init });
      if (!res.ok) throw new Error(`${path}: ${res.status} ${await res.text()}`);
      return res.json();
    }

    // 생성 직후의 작업은 잠시 404를 반환할 수 있으므로 계속 폴링합니다.
    async function poll(taskId) {
      const res = await fetch(`${API}/task/${taskId}`, { headers: HEADERS });
      if (res.status === 404) return null;
      if (!res.ok) throw new Error(`/task/${taskId}: ${res.status} ${await res.text()}`);
      return res.json();
    }

    async function generate(prompt, contextImages = [], aspectRatio = '2:3') {
      const body = { modelVersionId: TSUBAKI_3, prompt, aspectRatio };
      if (contextImages.length) body.contextImages = contextImages;
      let task = await call('/image/create', { method: 'POST', body: JSON.stringify(body) });
      while (task.status === 'waiting' || task.status === 'running') {
        await new Promise((resolve) => setTimeout(resolve, 2000));
        task = (await poll(task.id)) ?? task;
      }
      if (task.status !== 'completed') {
        throw new Error(`Task ended as ${task.status}: ${JSON.stringify(task.taskStatusMsgI18n)}`);
      }
      return task;
    }

    async function save(task, name) {
      const res = await fetch(task.outputs.mediaUrls[0]);
      await writeFile(name, Buffer.from(await res.arrayBuffer()));
    }

    const character = await generate(
      'A full-body anime illustration of a girl with short silver hair and blue eyes, ' +
        'wearing a navy coat and a red scarf, standing on a plain white background.',
    );
    await save(character, 'character.webp');
    const ref = character.outputs.mediaIds[0];

    const scenes = {
      'cafe.webp':
        'Draw the girl from image1 reading a book in a café by the window on a rainy day. ' +
        'Keep her face, hair and outfit exactly as in image1.',
      'beach.webp':
        'Draw the girl from image1 walking along a beach at sunset, carrying her coat. ' +
        'Keep her face, hair and scarf exactly as in image1.',
    };
    for (const [name, prompt] of Object.entries(scenes)) {
      await save(await generate(prompt, [ref], '2:3'), name);
    }
    ```
  </Tab>
</Tabs>

캐릭터를 일관되게 유지하는 다른 방법 [#캐릭터를-일관되게-유지하는-다른-방법]

* **LoRA**: 캐릭터로 학습한 LoRA를 `loras`로 적용합니다. [모델과 LoRA 찾아서 사용하기](/ko/docs/quick-start/examples/models-and-loras)를 참고하세요.
* **같은 `seed`**: 프롬프트를 조금만 바꿔 같은 `seed`로 생성하면 구도는 비슷하게 유지되지만, 캐릭터의 세부까지 유지되지는 않습니다.
* **인페인팅**: 한 영역만 바꾸고 나머지는 그대로 둡니다. [인페인팅과 아웃페인팅](/ko/docs/quick-start/examples/inpainting-and-outpainting)을 참고하세요.

참고 [#참고]

* [이미지 생성 작업 생성](/ko/docs/api-v2/image/createImage)
* [이미지 업로드 URL 발급](/ko/docs/api-v2/media/getImageUploadUrl)
* [모델](/ko/docs/references/models)
