eroq API로 AI 캐릭터 채팅 앱 만들기

첫 캐릭터 제품을 출시할 때 있었으면 좋았을 튜토리얼이에요. 저녁 한나절의 작업, 제대로 돌아가는 패턴 하나. 페르소나를 넣으면 답장이 스트리밍으로 나오고, 비용은 예측할 수 있어요.

한 문단으로 보는 아키텍처

API 키, 캐릭터 시트, 대화 저장소는 백엔드가 가져요. 클라이언트는 오직 내 백엔드와만 통신해요. 매 턴마다 [system] + [windowed history] + [new user message]를 조립해 /v1/chat/completions로 보내고, 답장을 스트리밍으로 내려보내요. API는 상태를 저장하지 않아요. 즉 메모리는 내 제품의 몫이고, 그게 장점이에요.

1. 페르소나 프롬프트

행동 규칙과 정체성을 분리하세요. 정체성은 짧게, 행동 규칙은 엄격하게요.

function personaPrompt(character) {
  return [
    `You are ${character.name}. ${character.oneLineIdentity}`,
    character.voiceNotes,                    // "dry humor, short sentences, hates small talk"
    'Stay fully in character. Never mention being an AI or add out-of-character notes.',
    'Actions in *asterisks*. Advance the scene, then hand it back.',
  ].join(' ')
}

설정 자료를 쏟아붓고 싶은 유혹을 참으세요. 시스템 프롬프트에 넣은 2,000단어짜리 배경 이야기는 깊이가 아니라 캐릭터 이탈을 불러와요. 구체적인 사실은 장면이 그 부분에 닿을 때만 주입하세요.

2. 스트리밍으로 받는 턴

export async function characterReply(character, history, userMessage, onDelta) {
  const res = await fetch('https://eroq.ai/v1/chat/completions', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.EROQ_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'eroq-rp-mini',                 // 1 크레딧; rp-plus where it matters
      stream: true,
      messages: [
        { role: 'system', content: personaPrompt(character) },
        ...history.slice(-30),               // the window — see below
        { role: 'user', content: userMessage },
      ],
    }),
  })

  const reader = res.body.getReader()
  const decoder = new TextDecoder()
  let buffer = ''
  let full = ''
  while (true) {
    const { done, value } = await reader.read()
    if (done) break
    buffer += decoder.decode(value, { stream: true })
    const events = buffer.split('\n\n')
    buffer = events.pop() ?? ''
    for (const event of events) {
      const data = event.replace(/^data: /, '')
      if (data === '[DONE]') continue
      const chunk = JSON.parse(data)
      const delta = chunk.choices?.[0]?.delta?.content
      if (delta) { full += delta; onDelta(delta) }
    }
  }
  return full
}

onDelta를 자체 SSE나 WebSocket으로 UI에 연결하세요. 첫 토큰이 1초 안에 화면에 뜨는 것, 그게 캐릭터가 곁에 있다고 느끼게 만들어요.

3. 히스토리 윈도

최근 20~40턴만 보내고, 절대 전부 보내지 마세요. 오래된 맥락은 기억을 더하는 속도보다 이탈을 더하는 속도가 빨라요. 오래 이어지는 관계라면 N개 메시지마다 저렴한 요약 패스를 돌리고, 그 요약을 시스템 프롬프트 바로 뒤에 메모처럼 붙이세요. eroq-rp-mini 호출 한 번(1 크레딧)으로 오래가는 기억 한 줄을 살 수 있어요.

보내기 전에 윈도를 걸러 내세요. 모델이 캐릭터를 벗어난 턴이 다시 보내는 맥락에 들어가면, 그런 턴만 더 늘어나요.

4. 비용 계산

정액 가격의 핵심은 출시 전에 이 표를 만들 수 있다는 거예요.

사용자 유형	하루 호출 수	모델	하루 크레딧
가벼운 사용(메시지 20개)	20	rp-mini	20
적극적 사용(메시지 80개)	80	rp-mini	80
헤비 유저 + 고품질 장면	150	혼합	~250

팩 요율(크레딧당 ~$0.01 이하) 기준으로, 적극적인 사용자 한 명의 모델 비용은 하루 약 $0.80 정도예요. 구독 가격은 그에 맞춰 정하고, 이미지(10 크레딧)와 음성 대사는 기본 기능이 아니라 프리미엄 순간으로 더하세요.

5. 제대로 처리해야 할 두 가지 오류

• 402 insufficient_credits: 버그가 아니라 지갑 문제예요. 스스로에게 알림을 보내고, 충전하고, 기능을 부드럽게 낮추세요(메시지를 큐에 넣고, 사용자에게는 캐릭터가 "잠깐 자리를 비웠다"고 알려 주세요).
• 502 / 스트림 오류 이벤트: 자동으로 환불돼요. 백오프를 두고 한 번 재시도하세요. 사용자에게는 사과문이 아니라 입력 중 표시가 보여요.

나머지는 오류 가이드에 있는 표준적인 내용이에요.

자주 묻는 질문

긴 대화에서 캐릭터가 캐릭터를 유지하게 하려면 어떻게 하나요?

세 가지 습관이 대부분의 일을 해요. 인물의 이력이 아니라 행동 규칙을 명시하는 시스템 프롬프트, 대화 전체가 아니라 최근 20~40턴의 윈도, 그리고 약 30턴마다 갱신하는 롤링 요약(eroq-rp-mini 호출 한 번, 1 크레딧)이에요. 히스토리를 다시 보내기 전에 모델이 캐릭터를 벗어난 턴은 빼세요. 그래도 이탈이 보이면 그 대화를 RP+로 옮기세요. 깊은 대화에서도 페르소나를 유지하도록 튜닝된 모델이에요.

캐릭터 채팅 앱은 사용자당 비용이 얼마인가요?

답장 길이와 상관없이 응답 한 번에 RP mini는 1 크레딧, RP+는 3 크레딧이에요. 하루 메시지 80개를 보내는 적극적인 사용자는 하루 약 80 크레딧을 써요. $10에 1,000 크레딧이니 팩 요율로 약 $0.80 정도예요. 이미지는 장당 10 크레딧, 첨부 사진은 2크레딧이 추가되니, 지켜봐야 할 건 채팅 자체가 아니라 프리미엄 순간이에요.

eroq 채팅 API는 이전 메시지를 기억하나요?

아니요, 의도된 거예요. /v1/chat/completions는 상태를 저장하지 않아요. 매 호출마다 모델이 봐야 할 히스토리를 직접 보내는데, 그 말은 메모리를 내가 소유하고 들여다보고 다듬고 디버그할 수 있다는 뜻이에요. 캐릭터 시트와 세계관 상태는 messages 배열을 어지럽히는 대신 최상위 context 필드에 담아 보낼 수 있어요.

사용자가 캐릭터에게 사진을 보낼 수 있나요?

네. 사용자 턴의 content는 텍스트와 image_url 파트를 섞은 배열일 수 있어요. https URL이나 data URI를 요청당 최대 2장까지 넣을 수 있고, 응답 비용에 더해 이미지당 +2크레딧이 붙어요. 비전 워크스루에서 UX 패턴과, 여전히 여러분 몫으로 남는 모더레이션 책임을 다뤄요.

출시하세요

이게 정말 패턴의 전부예요. 행동 규칙 프롬프트, 윈도, 스트림, 예산. 키를 발급받고 2번 섹션을 붙여 넣으면, 퀵스타트의 5분 안에 첫 캐릭터가 말을 시작해요. 무료 50크레딧이면 저녁 내내 테스트하기에 충분해요.