# Qwen Character API Alibaba의 Qwen Character 역할극 모델에 대한 전체 API 레퍼런스입니다. Qwen Character 모델은 Flaq AI chat completions 엔드포인트를 사용하지만, 장기 기억, 그룹 채팅 시뮬레이션, assistant 부분 이어쓰기를 위한 캐릭터 전용 필드도 지원합니다. ## 모델 변형 이 API는 두 가지 모델 변형을 지원합니다. | 모델 | ID | 설명 | |-------|----|-------------| | **Qwen Plus Character** | `qwen-plus-character` | 더 높은 품질의 캐릭터 역할극 | | **Qwen Flash Character** | `qwen-flash-character` | 더 빠르고 합리적인 캐릭터 역할극 | ## 빠른 비교 | 기능 | Qwen Plus Character | Qwen Flash Character | |---------|---------------------|----------------------| | 텍스트 입력 | 필수 ✅ | 필수 ✅ | | 이미지 입력 | 지원되지 않음 ❌ | 지원되지 않음 ❌ | | 장기 기억 | 선택 사항 | 선택 사항 | | `temperature` | 선택 사항 | 선택 사항 | | `seed` | 선택 사항 | 선택 사항 | | 스트리밍 응답 | SSE | SSE | ## 캐릭터 역할극 작동 방식 단일 캐릭터 역할극에는 일반 `system`, `user`, `assistant` 메시지를 사용합니다. 현재 요청에 대한 안정적인 페르소나 지시는 `system` 메시지에 넣습니다. 장기 기억을 활성화할 때는 재사용 가능한 캐릭터 프로필을 `profile`에 넣습니다. 그룹 채팅 시뮬레이션에서 Qwen Character는 `profile`에서 화자 이름을 자동으로 추론하지 않습니다. 호출자는 각 메시지 `content`의 시작 부분에 `Cheng Yi:` 또는 `Ling Lu:`처럼 화자 이름을 직접 작성해야 합니다. 모델이 특정 캐릭터로 이어서 말하게 하려면, 대상 화자 접두어를 `content`로 가진 마지막 assistant 메시지를 추가하고 `partial: true`를 설정합니다. `partial`은 마지막 assistant 메시지에 있는 메시지 수준 필드입니다. 최상위 요청 파라미터가 아닙니다. ## Qwen Plus Character ### 엔드포인트 ```http POST /api/v1/chat/completions ``` ### 요청 파라미터 #### 필수 | 파라미터 | 타입 | 설명 | |-----------|------|-------------| | `model` | string | `"qwen-plus-character"`여야 합니다 | | `messages` | array | `system`, `user`, 선택적 `assistant` 역할이 포함된 순서가 있는 메시지입니다. | | `stream` | boolean | SSE는 `true`, 단일 JSON 응답은 `false`입니다. | #### 헤더 | 헤더 | 필수 | 설명 | |--------|----------|-------------| | `Authorization` | 필수 | `Bearer YOUR_API_KEY` 형식의 API 키입니다. | | `Content-Type` | 필수 | `application/json`을 사용합니다. | | `Accept` | 필수 | `stream`이 `true`이면 `text/event-stream`을 사용하고, `stream`이 `false`이면 `application/json`을 사용합니다. | | `x-session` | 장기 기억이 활성화된 경우 필수 | 장기 기억 격리와 회상을 위한 사용자 정의 세션 ID입니다. 기억은 사용자 키별로 격리되므로, 서로 다른 사용자는 같은 세션 ID를 재사용해도 기억을 공유하지 않습니다. | #### 메시지 지원 | 필드 | 텍스트 | 파일 | 이미지 | |-------|------|------|-------| | `messages` | 필수 ✅ | 지원되지 않음 ❌ | 지원되지 않음 ❌ | #### 메시지 필드 | 필드 | 타입 | 필수 | 설명 | |-------|------|----------|-------------| | `role` | string | 필수 | `system`, `user`, `assistant`를 지원합니다. | | `content` | string | 필수 | 메시지 텍스트입니다. 그룹 채팅 시뮬레이션에서는 `Ling Lu:`처럼 화자 이름을 시작 부분에 직접 포함합니다. | | `partial` | boolean | 선택 사항 | 마지막 assistant 메시지에서만 사용합니다. `content`가 모델이 이어서 생성해야 하는 접두어일 때 `true`로 설정합니다. | #### 선택 사항 | 파라미터 | 타입 | 범위 | 설명 | |-----------|------|-------|-------------| | `max_tokens` | integer | `> 0` | 최대 출력 token 수입니다. | | `temperature` | number | `0.0` - `1.0` | 응답의 무작위성을 제어합니다. | | `seed` | integer | `0` - `2147483647` | 재현 가능한 출력을 위한 랜덤 시드입니다. 대화 컨텍스트 창과는 관련이 없습니다. | | `profile` | string | — | 캐릭터 프로필입니다. `enable_long_term_memory`가 `true`일 때 필수입니다. `profile`은 메시지에 화자 이름을 자동으로 추가하지 않습니다. | | `enable_long_term_memory` | boolean | — | 요청에 장기 기억을 활성화합니다. `profile`과 `x-session` 헤더가 필요합니다. | | `memory_entries` | integer | — | 세션에서 회상하거나 유지할 기억 항목 수입니다. 현재 공식 문서에는 고정 범위 제한이 공개되어 있지 않습니다. | | `skip_save_types` | string[] | `system`, `user`, `assistant`, `output` | 이 요청에서 저장을 건너뛸 기억 타입입니다. | 장기 기억이 활성화된 경우 다음을 제공해야 합니다. - `x-session` 요청 헤더 - 요청 본문의 `profile` - `enable_long_term_memory: true` `skip_save_types`는 다음 값을 지원합니다. | 값 | 의미 | |-------|---------| | `system` | 이 요청에서 추가된 `system` 메시지 저장을 건너뜁니다. | | `user` | 이 요청에서 추가된 `user` 메시지 저장을 건너뜁니다. | | `assistant` | 이 요청에서 추가된 `assistant` 메시지 저장을 건너뜁니다. | | `output` | 이 요청에서 생성된 assistant 메시지 저장을 건너뜁니다. | ### 기본 역할극 요청 ```javascript const response = await fetch('https://api.flaq.ai/api/v1/chat/completions', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Accept': 'application/json', 'Content-Type': 'application/json' }, body: JSON.stringify({ model: 'qwen-plus-character', stream: false, max_tokens: 1200, temperature: 0.8, messages: [ { role: 'system', content: 'You are Jiang Rang, a witty high-school Go prodigy. Stay playful, warm, and concise.' }, { role: 'user', content: 'Why are you reading Go records outside the milk tea shop again?' } ] }) }); ``` ### 장기 기억 요청 ```javascript const response = await fetch('https://api.flaq.ai/api/v1/chat/completions', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Accept': 'text/event-stream', 'Content-Type': 'application/json', 'x-session': 'your-session-id' }, body: JSON.stringify({ model: 'qwen-plus-character', messages: [ { role: 'system', content: 'You are a witty high-school student who speaks with humor and warmth.' }, { role: 'user', content: 'Remember that I prefer lightly sweet milk tea.' } ], stream: true, max_tokens: 1200, temperature: 0.8, seed: 12345, profile: 'You are a witty high-school student who remembers user preferences and stays in character.', enable_long_term_memory: true, memory_entries: 50, skip_save_types: [] }) }); ``` ### `partial`을 사용한 그룹 채팅 시뮬레이션 그룹 채팅 시뮬레이션은 메시지 텍스트로 구현됩니다. API는 화자 이름을 자동으로 할당하거나 이전하지 않습니다. 각 화자 이름을 `content` 시작 부분에 직접 작성한 다음, 대상 화자 접두어와 `partial: true`가 있는 마지막 assistant 메시지를 추가합니다. ```javascript const response = await fetch('https://api.flaq.ai/api/v1/chat/completions', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Accept': 'application/json', 'Content-Type': 'application/json' }, body: JSON.stringify({ model: 'qwen-plus-character', stream: false, max_tokens: 800, temperature: 0.8, messages: [ { role: 'system', content: 'In a musician group chat, Ling Lu is a 25-year-old gifted musician known for sharp humor and a regional accent. Cheng Yi is his music partner, Tao Le is his partner, and Ma Hui is a friend. Keep Ling Lu sarcastic but caring. Reply in one short message.' }, { role: 'user', content: 'Cheng Yi: Are you free this weekend? I want feedback on the new song.' }, { role: 'user', content: 'Tao Le: He is right, but do not stay up too late editing.' }, { role: 'user', content: 'Ma Hui: Let us grab dinner and talk. My treat.' }, { role: 'assistant', content: 'Ling Lu:', partial: true } ] }) }); ``` ### `partial`로 캐릭터 이어 말하기 사용자가 답장하지 않았지만 캐릭터가 계속 말하게 하고 싶을 때도 같은 `partial` 패턴을 사용합니다. 캐릭터 접두어가 포함된 마지막 assistant 메시지를 추가합니다. ```javascript { model: 'qwen-plus-character', stream: false, messages: [ { role: 'system', content: 'You are Jiang Rang, a high-school Go prodigy. Speak with humor and warmth.' }, { role: 'assistant', content: 'Class monitor, what are you doing?' }, { role: 'assistant', content: '(He waves at you.) Did being class monitor make you forget how to answer me?' }, { role: 'assistant', content: 'Jiang Rang:', partial: true } ] } ``` ## Qwen Flash Character ### 요청 파라미터 Qwen Plus Character와 동일한 프로토콜이며 차이점은 다음과 같습니다. | 파라미터 | Qwen Flash Character | |-----------|----------------------| | `model` | `"qwen-flash-character"`여야 합니다 | ### 요청 예시 ```javascript { model: 'qwen-flash-character', messages: [ { role: 'system', content: 'You are a calm library assistant who speaks briefly and vividly.' }, { role: 'user', content: 'Introduce yourself in three sentences.' } ], stream: true, max_tokens: 800, temperature: 0.7, seed: 12345 } ``` ## 응답 형식 Qwen Character LLM 모델은 OpenAI 호환 completion 응답을 반환합니다. `stream: true`이면 응답은 Server-Sent Events(SSE)이며, `stream: false`이면 단일 JSON 객체입니다. ## 모범 사례 - 요청 수준의 페르소나 지시는 `system` 메시지에 넣으세요. - 재사용 가능한 캐릭터 배경은 장기 기억이 활성화된 경우에만 `profile`에 넣으세요. - 장기 기억이 활성화된 경우 관련 대화에서 동일한 `x-session` 값을 재사용하세요. 365일 동안 사용되지 않은 세션은 삭제될 수 있습니다. - 유용한 경우 최근 대화 메시지를 계속 전송하세요. 장기 기억과 단기 컨텍스트는 함께 작동할 수 있습니다. - 그룹 채팅 시뮬레이션에서는 화자 이름을 `content`에 직접 작성하세요. API는 `profile`에서 이름을 추론하지 않습니다. - 모델이 접두어에서 이어서 생성해야 할 때만 마지막 assistant 메시지에 `partial: true`를 사용하세요. - 가벼운 역할극에는 Qwen Flash Character를, 더 풍부한 대화 품질에는 Qwen Plus Character를 사용하세요.