Qwen Character API

Complete API reference for Qwen Character roleplay models by Alibaba. Qwen Character models use the Flaq AI chat completions endpoint, but they also support character-specific fields for long-term memory, group-chat simulation, and partial assistant continuation.

Model Variants

This API supports two model variants:

Quick Comparison

How Character Roleplay Works

Use normal system, user, and assistant messages for single-character roleplay. Put stable persona instructions in a system message for the current request. When long-term memory is enabled, put the reusable character profile in profile.

For group-chat simulation, Qwen Character does not automatically infer speaker names from profile. The caller must write speaker names at the beginning of each message content, such as Cheng Yi: or Ling Lu:. To make the model continue as a specific character, append a final assistant message whose content is the target speaker prefix and set partial: true.

partial is a message-level field on the final assistant message. It is not a top-level request parameter.

Qwen Plus Character

Endpoint

httpCopy
POST /api/v1/chat/completions

Request Parameters

Required

Headers

Message Support

Message Fields

Optional

When long-term memory is enabled, you must provide:

• x-session request header
• profile in the request body
• enable_long_term_memory: true

skip_save_types supports these values:

Basic Roleplay Request

javascriptCopy
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?'
      }
    ]
  })
});

Long-Term Memory Request

javascriptCopy
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: []
  })
});

Group Chat Simulation with partial

Group-chat simulation is implemented through message text. The API does not automatically assign or migrate speaker names. Write each speaker name manually at the start of content, then append a final assistant message with the target speaker prefix and partial: true.

javascriptCopy
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
      }
    ]
  })
});

Continue as Character with partial

Use the same partial pattern when the user has not replied but you want the character to continue speaking. Add a final assistant message with the character prefix.

javascriptCopy
{
  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

Request Parameters

Same protocol as Qwen Plus Character, with these differences:

Example Request

javascriptCopy
{
  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
}

Response Format

Qwen Character LLM models return OpenAI-compatible completion responses. With stream: true, the response is Server-Sent Events; with stream: false, the response is a single JSON object.

Best Practices

• Put request-level persona instructions in system messages.
• Put reusable character background in profile only when long-term memory is enabled.
• Reuse the same x-session value across related conversations when long-term memory is enabled. Sessions unused for 365 days may be cleared.
• Continue sending recent conversation messages when useful; long-term memory and short-term context can work together.
• For group-chat simulation, manually write speaker names in content. The API will not infer names from profile.
• Use partial: true only on the final assistant message when the model should continue from a prefix.
• Use Qwen Flash Character for lightweight roleplay and Qwen Plus Character for richer dialogue quality.