Text

Conversations

Chat completions powered by gpt-5.4-nano. Pass a single message per call — the API stores per-user history and (optionally) extracts durable memories so the assistant gets smarter about each end-user over time.

Endpoint

POST https://qaves.me/api/v1/text/conversations

Headers

Authorizationstringrequired

Bearer sk_qu_… — see Authentication.

Content-Typestringrequired

Must be application/json.

Body parameters

messagestringrequired

The new user turn (max 8000 chars). Send one message per request — history is managed server-side.

system_instructionsstringoptional

Persona / behavior for the assistant (max 8000 chars). Sent as a system message ahead of memory & history.

user_idstringoptional

Stable identifier for the human you are chatting with (e.g. a Discord ID, your internal user id). When provided, the API stores the turn and injects the most recent 10 messages on subsequent calls. Omit for a stateless one-off completion.

display_namestringoptional

Friendly name for the end-user. Surfaced to the model as "You are speaking with …".

attachmentsstring | string[]optional

One or more images to attach to the user turn. Pass either https:// URLs ordata:image/…;base64,… URLs (up to 8 total). The model sees every image alongside message and can describe, compare, reason about, or answer questions about them. When a user_id is also provided, images are automatically downloaded, re-hosted on permanent Qaves URLs, described by a fast vision model, and stored so the assistant can reference them again in future turns ("the photo of your dog…").

imagestringoptional

Legacy alias for a single attachment. If attachments is also present, both are merged.

use_memorybooleanoptional

When true and a user_id is supplied, the API:

Injects the most recent 30 stored memories about that user into the system prompt.
Runs a second-pass extraction after the reply to capture durable facts and behavioral directives.

Memories are scoped to your API key and that user_id. Defaults to false.

disable_searchbooleanoptional

When true, the API will never route the request to a web-search model, even if the router classifies the message as needing real-time internet access. The request always uses the standard chat model. Defaults to false.

What gets stored as a memory?

Extraction is intentionally strict. A turn produces memories only when the user explicitly asks to remember something ("remember that…"), reveals a stable durable fact (name, location, allergies, strong preferences), or gives a behavioral directive about how the assistant should act toward them (tone, language, persona). Most turns yield zero memories — that is by design.

Built-in tools the assistant can call

When a user_id is supplied, the assistant has tools it can invoke on its own based on what the end-user says — no extra parameters required:

reset_conversation — fires when the user clearly asks to reset, clear, wipe, or start over. Deletes all messages and memories for that user_id.
delete_memories — fires when the user asks the assistant to forget specific things ("forget that I live in Austin") or everything ("forget everything about me").
save_image_as_memory — fires when an attached image plus the user's words clearly identifies a long-term subject ("this is my dog Max"). The image is linked to the new memory.
generate_image — fires when the user asks for an image, illustration, or photo. If the user also attached an image and asks to edit, remix, restyle, or build on it, the attached image is automatically used as the source for the edit.
lookup_discord_user — fires when the user asks about a Discord account by numeric ID (17–20 digit snowflake). Returns public profile info including decoded badge names.

Tools that ran during a turn are returned in the response under tools_used.

Response

data.replystringoptional

The assistant's reply text.

data.modelstringoptional

Always gpt-5.4-nano today.

data.user_idstring | nulloptional

Echo of the user_id you sent.

data.display_namestring | nulloptional

Echo of display_name.

data.use_memorybooleanoptional

Echo of use_memory.

data.image_bucket_urlstring | nulloptional

Public URL to the end-user's image bucket when a user_id was supplied and the bucket is public. Returns "private" if the bucket exists but is not public, or null if no user_id was provided.

data.tools_usedstring[]optional

Names of any built-in tools the assistant invoked during this turn (e.g. generate_image, lookup_discord_user).

data.image_urlstring | nulloptional

When the assistant generated an image, the hosted URL of that image.

data.contains_imagebooleanoptional

Whether the reply includes a generated image.

data.usageobjectoptional

{ prompt_tokens, completion_tokens } as reported by upstream.

data.completion_msintegeroptional

Total server-side time in milliseconds.

{
  "data": {
    "reply": "Got it — orange it is. What can I help you build today?",
    "model": "gpt-5.4-nano",
    "user_id": "discord:123456789",
    "display_name": "Alex",
    "use_memory": true,
    "tools_used": [],
    "image_url": null,
    "contains_image": false,
    "image_bucket_url": "https://qaves.me/qu/p/usr_…/discord-123456789",
    "usage": { "prompt_tokens": 412, "completion_tokens": 18 },
    "completion_ms": 842,
    "created_at": 1778833800,
    "finished_at": 1778833801
  }
}

Examples

Stateless one-off completion

Omit user_id to get a single completion with no history or memory.

curl https://qaves.me/api/v1/text/conversations \
  -H "Authorization: Bearer sk_qu_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "system_instructions": "You are a terse senior engineer.",
    "message": "What is the difference between TCP and UDP in one line?"
  }'

Per-user chat with memory

Pass a stable user_id for every message from the same human. Enable use_memory so the assistant remembers stable facts and behavioral preferences across sessions.

{
  "system_instructions": "You are a friendly assistant inside a Discord bot.",
  "user_id": "discord:123456789",
  "display_name": "Alex",
  "use_memory": true,
  "message": "Just so you know, my favorite color is orange. Please remember that."
}

Sending images

Attach one or more image URLs to ask the model about their contents.

curl https://qaves.me/api/v1/text/conversations \
  -H "Authorization: Bearer sk_qu_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What is in this image? Be concise.",
    "attachments": "https://example.com/photo.jpg"
  }'

Pass up to 8 images as an array for comparison or multi-image reasoning:

curl https://qaves.me/api/v1/text/conversations \
  -H "Authorization: Bearer sk_qu_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Which of these looks better for a landing page?",
    "attachments": [
      "https://example.com/design-a.jpg",
      "https://example.com/design-b.jpg"
    ]
  }'

Steering behavior per-user

Behavioral directives ("always reply in Spanish", "be sarcastic with me") are extracted as memories and re-injected automatically on future turns, so each end-user gets their own version of the assistant.

Viewing & managing memory

Conversation history and memories for every end-user are visible in the dashboard at /qu/conversations. You can delete individual memories or wipe an entire conversation from there.

Limits

History50 messagesoptional

The most recent 50 messages per (key, user_id) are retained. Older messages are pruned automatically.

History injected10 messagesoptional

The 10 most recent messages are sent to the model on each call.

Memories injected30 entriesoptional

When use_memory is true, the 30 most recent memories about the user are included.

← Creating videos Rate limits →