API를 통해 AI 캐릭터의 일관성을 유지하는 방법: 저장된 레퍼런스 하나로 여러 장면 구현하기

이미지 모델을 사용하면 하나의 프롬프트만으로 멋진 캐릭터 이미지를 얻을 수 있습니다. 하지만 다음 10장의 이미지에서도 같은 캐릭터를 유지하는 것이 어렵습니다. 그녀를 말로 다시 묘사하면 안경 모양이 변하고, 머리카락 색상이 미세하게 바뀌며, 열 번째 게시물에는 아무도 그녀가 어떻게 생겼는지 말할 수 없게 됩니다.

해결책은 기발한 프롬프팅보다는 절차적인 접근 방식입니다. 즉, 이미지 하나를 선택하여 저장하고, 이후 모든 생성 작업이 텍스트가 아닌 이 저장된 이미지로부터 시작하도록 만드는 것입니다. 본 게시물에서는 순수 Node.js로 약 100줄 분량의 파이프라인을 구축하는 방법을 다룹니다. 여기에는 후보군(candidates), 저장된 레퍼런스, 사진 세트, 그리고 짧은 클립 생성이 포함됩니다.

파이프라인

1. 후보군 (Candidates). 텍스트-이미지 모델을 사용하여 평범한 배경에 어깨와 머리만 나온 인물 초상화 몇 장을 생성합니다.
2. 레퍼런스 (Reference). 마음에 드는 이미지를 영구적인 에셋 라이브러리에 저장합니다. 그러면 안정적인 URI를 받게 됩니다.
3. 사진 세트 (Photo set). 해당 URI를 레퍼런스 이미지로, 새로운 장면을 프롬프트에 넣어 이미지 편집(edit) 모델을 호출합니다. 이 과정을 각 장면에 대해 반복합니다.
4. 클립 (Clip). 생성된 사진 중 하나도 저장하고, 이를 이미지-비디오 모델의 시작 프레임으로 전달합니다.

가장 중요한 규칙은 3단계에 있습니다: 새로운 이미지는 항상 저장된 레퍼런스에서 시작해야 하며, 가장 최근 결과물에서 시작해서는 안 됩니다. 결과물을 연속적으로 연결(chaining result-to-result)하면 작은 변화들이 쌓여 큰 차이를 만듭니다.

아래 사용된 모델 정보 (작성 시점인 2026년 10월 기준 가격):

후보군 4장, 사진 3장, 그리고 5초짜리 클립 하나가 합쳐져 약 $0.70 정도의 비용이 발생합니다.

작은 클라이언트

SDK가 필요하지 않습니다. 이 API는 모든 응답을 { code, msg, data, request_id }로 감싸주며, 작업은 비동기적(asynchronous)이고, 쓰기는 Idempotency-Key를 받아 재시도 요청이 두 번째 작업을 생성하거나 청구하는 것을 방지합니다.

// spicy.mjs: SpicyAPI 작업 API를 위한 작은 헬퍼 (Node 18+, 의존성 없음)
import { randomUUID } from 'node:crypto';

...

알아두면 좋은 두 가지 세부 사항이 있습니다:

⚠️ [IMG:N] 형식 토큰은 이미지 placeholder 입니다. 번역하지 말고 원래 위치에 그대로 유지하세요.

• ?wait=60는 첫 번째 요청을 최대 60초 동안 대기시킵니다. 이미지 작업(Image jobs)의 경우 보통 이 한 번의 호출에서 완료되어 돌아오며, 그렇지 않을 때만 폴링(poll)합니다. 연결이 끊어져도 작업은 계속 실행됩니다.
• 저장(save) 호출은 결정론적(deterministic)의 중복 방지 키(idempotency key)(save-<task>-<index>)를 사용하므로 스크립트를 두 번 실행해도 동일한 이미지가 두 번 저장되지 않습니다.

스크립트

// character.mjs: candidates -> saved reference -> photo set -> one short clip
import { quote, run, saveAsset } from './spicy.mjs';

...

두 번 실행해 보세요. SPICY_API_KEY=sk-spicy-... node character.mjs를 실행하면 네 개의 후보(candidates)가 생성되고 각 작업 ID와 이미지 URL을 출력한 후 중지합니다. 해당 URL들을 열어 얼굴을 선택하고, 다시 PICK_TASK=<그 작업 ID>로 실행하여 레퍼런스를 저장하고 사진 세트 및 클립을 만듭니다. 위치(position)가 아닌 작업 ID로 선택하는 것이 중요합니다. 그렇지 않으면 두 번째 실행 시 네 개의 새로운 얼굴이 생성될 것입니다.

저장된 URI가 중요한 이유

output.assets[].url에 있는 출력 URL은 약 20분 후에 만료되는 서명된 링크(signed links)이며, 결과는 14일 동안 보관됩니다. 이는 다운로드에는 괜찮지만, 몇 달 동안 사용할 캐릭터에게는 적합하지 않습니다.

POST /api/v1/assets는 파일을 영구적인 라이브러리(persistent library)에 복사하고 spicy://a/ast_...와 같은 uri를 가진 에셋을 반환합니다. 이 URI는:

• 모델 입력의 모든 미디어 필드(image_urls, image_url 등)에서 작동하므로 레퍼런스를 다시 업로드할 필요가 없습니다.
• 동일한 워크스페이스(workspace)의 API 키에 대해서만 해결되므로 공개 링크가 아니며, 라이브러리를 파일 호스팅으로 사용할 수 없습니다.
• 에셋을 삭제할 때까지 유효합니다.

미리 보기 URL이 아닌 uri를 캐릭터 옆에 자체 데이터베이스에 저장하세요.

라이브러리는 계정의 평생 충전(lifetime top-ups)과 함께 잠금 해제됩니다 (작성 시점 기준, 총 $10로 500MB와 최대 200개의 저장된 에셋을 얻을 수 있습니다). 이것이 없으면 save 호출은 data.reason이 asset_library_locked으로 설정된 400 오류를 반환하며, 위에서 언급한 헬퍼가 이를 출력합니다. GET /api/v1/assets/usage는 현재 플랜과 제한을 보여줍니다.

편집 모델에 프롬프팅하기

참조 이미지는 얼굴을 담고, 프롬프트는 변화를 담아야 합니다. 도움이 되는 몇 가지 방법이 있습니다:

• 유지되어야 할 것을 명시합니다. 단순히 전체 설명을 반복하는 것보다 "그녀의 얼굴, 머리카락, 안경, 앞치마를 정확히 유지해 줘"라고 하는 것이 더 효과적입니다.
• 샷당 한 가지만 변경합니다: 장소, 활동 또는 의상 중 세 가지 모두가 아닌 하나만 바꿉니다.
• 시그니처 디테일을 보이게 합니다. 두세 가지(안경, 구리빛 머리카락, 노란 앞치마)를 골라 보여주는 방식으로 샷을 구성합니다. 이것들이 썸네일을 알아볼 수 있게 만듭니다.
• 나란히 비교합니다. 몇 주마다 최근 이미지 여섯 개를 참조 이미지 옆에 배치해 보세요. 낯선 사람이 그것들을 같은 사람이라고 부르지 못한다면, 최신 이미지 대신 참조 이미지로 돌아가야 합니다.

사용하기 전에 인용구

POST /api/v1/jobs/quote는 createTask와 동일한 본문을 사용하며 아무것도 실행하지 않고 estimatedCost를 반환합니다. 스크립트는 사진당 비용을 출력합니다. 실제 도구에서는 버튼이 어떤 행동을 하기 전에 사용자에게 이를 보여주거나, 예산을 초과하는 요청은 거부해야 합니다. 작업이 생성될 때, estimatedCost가 유지되며 최종 청구액은 절대 이 금액을 넘지 않습니다.

코딩 없이 실행하기

만약 이것을 어떤 것에 연결해 보기 전에 아이디어만 시험해 보고 싶다면, 동일한 흐름이 있는 페이지가 있습니다: AI 인플루언서 빌더에서는 사진 카드에서 특성을 선택하고, 클로즈업과 전신 사진을 유지하며 캐릭터를 저장한 다음, 4개, 8개 또는 12개의 사진 세트, 짧은 비디오 또는 입 모양에 맞춘 대화 클립을 만들 수 있습니다. 내부적으로는 위에서 설명한 참조 이미지 우선 접근 방식입니다.

페르소나 책임감 있게 운영하기

일관된 가상의 캐릭터는 브랜드 마스코트나 채널 진행자로서 운영할 만한 합리적인 것이며, 몇 가지 규칙이 있습니다:

• 표시하기(Label it). 많은 소셜 플랫폼이 AI 콘텐츠 라벨을 가지고 있으며 일부는 이를 요구합니다. 프로필에 해당 캐릭터가 AI로 생성되었음을 명시하세요.
• 실존 인물을 모방하지 마세요. 그리고 그 얼굴을 사용할 권리가 있는 경우에만 사진으로 시작하세요.
• 캐릭터를 가상의 성인으로 유지하고, 이를 페르소나 노트에 작성하세요.

다음 단계 (Where to go next)

• 모델 교체: 레퍼런스 이미지를 허용하는 모든 이미지 편집 모델이 3단계에 사용 가능하며, API 문서에는 각 모델이 무엇을 허용하는지 나열되어 있습니다.
• 말하는 클립 추가하기: 대사 한 줄에 대한 음성을 생성한 다음, 저장된 사진 중 하나에 말하는 아바타(talking-avatar) 모델을 실행합니다.
• 해상도 및 레퍼런스 이미지 제한 확인: Seedream 5.0 Pro의 모델 페이지에서 해상도 등급과 레퍼런스 이미지 한계(요청당 최대 10개까지)를 읽어보세요.

이 모든 트릭은 하나의 습관에 달려 있습니다: 레퍼런스를 한 번 저장하고, 이후 모든 요청을 그곳으로 지정하는 것입니다.