Memory Chat API

Version Requirement: Standard Edition or higher

Introduction

This API provides context-aware conversation capabilities. Unlike the regular Chat API, users don't need to maintain context memory through the messages parameter. Simply provide your question and identity identifier, and the system will manage conversation context for each user.

Key features:

1. Integrate with Applications or Workflows to leverage Knowledge Bases and Plugins
2. Automatically manage user-specific memory based on conversation turns and retention time settings
3. Seamlessly switch between all supported AI models
4. Support for both streaming and non-streaming output
5. Multimodal input/output capabilities - accept text input; generate text, images, videos, and files

Try it live: API Debug Console

API Specification

Endpoint

POST https://api.linkai.cloud/v1/chat/memory/completions

Request Headers

Parameter	Value	Description
Authorization	Bearer YOUR_API_KEY	See Authentication for creating API Keys
Content-Type	application/json	Indicates JSON format request

Request Body

Parameter	Type	Required	Description
question	string	Yes	User's current question
session_id	string	No	Session identifier for context storage. If not provided, system will assign a unique ID
app_code	string	No	Application or Workflow code. If omitted, the request goes directly to the model
model	string	No	Model code. Default is application's configured model. See Model List
temperature	float	No	Controls randomness (0-1). Higher values produce more creative responses
top_p	int	No	Controls sampling range. Default is 1
frequency_penalty	float	No	Penalizes frequent tokens (-2 to 2). Default is 0
presence_penalty	float	No	Penalizes repeated tokens (-2 to 2). Default is 0
stream	bool	No	Enables streaming output. Default is false
image_url	string	No	Image URL for vision tasks. Supports jpg, jpeg, png formats

Important Notes:

• When an application is specified via app_code, you can configure memory turns and retention time in the application management page. Conversation memory is isolated by Application+SessionID dimensions:

• When a workflow is specified via app_code, the system maintains memory for the entire workflow. You can enable memory in model or application nodes and specify memory turns:

Request Example:

{
    "app_code": "G7z6vKwp",
    "query": "Hello",
    "session_id": "123e4567-e89b-12d3-a456-426614174000"
}

Note:

• app_code: Replace with your application's code or a public app code
• session_id: Typically a unique user identifier, such as an encrypted user ID or phone number. If not provided, the system generates a unique ID that's returned in the response.

Response

Non-Streaming Response

By default, the API returns the complete response after content generation is complete:

{
    "session_id": "123e4567-e89b-12d3-a456-426614174000",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "Hello! How can I help you today?"
            }
        }
    ],
    "usage": {
        "prompt_tokens": 9,
        "completion_tokens": 17,
        "total_tokens": 26
    }
}

Note:

• The session_id is returned as provided, or auto-generated if not specified in the request.
• choices.message.content contains the AI's response, while the usage section shows token consumption details.

Token calculation for a conversation includes tokens from both request and response. The request includes tokens from application settings, conversation history, knowledge base content, and user question. Token limits for these components can be configured in Application Management.

Streaming Response

Set the stream parameter to true for real-time content generation, suitable for web, mobile apps, and mini programs:

data: {"choices": [{"index": 0, "delta": {"content": "Hello!"}, "finish_reason": null}], "session_id": "123e4567-e89b-12d3-a456-426614174000"}

data: {"choices": [{"index": 0, "delta": {"content": " I"}, "finish_reason": null}], "session_id": "123e4567-e89b-12d3-a456-426614174000"}

data: {"choices": [{"index": 0, "delta": {"content": " can"}, "finish_reason": null}], "session_id": "123e4567-e89b-12d3-a456-426614174000"}

data: {"choices": [{"index": 0, "delta": {"content": " help"}, "finish_reason": null}], "session_id": "123e4567-e89b-12d3-a456-426614174000"}

data: {"choices": [{"index": 0, "delta": {"content": " you."}, "finish_reason": null}], "session_id": "123e4567-e89b-12d3-a456-426614174000"}

data: {"choices": [{"index": 0, "delta": {}, "finish_reason": "stop", "usage": {"prompt_tokens": 9, "completion_tokens": 6, "total_tokens": 15}}], "session_id": "123e4567-e89b-12d3-a456-426614174000"}

data: [DONE]

Note: The output ends with "[DONE]", and each data line carries the session_id field.

Error Response

When an error occurs, the API returns:

{
    "error": {
        "message": "Invalid request: user message content is empty",
        "type": "invalid_request_error"
    }
}

Error types are determined by HTTP status codes and error messages:

HTTP Status Code	Description
400	Invalid request format
401	Authentication failed, check your API Key
402	Application doesn't exist, check app_code parameter
403	Access denied. For private apps, only the creator can access
406	Insufficient account credits
408	No API access privilege. This API requires Standard edition or higher
409	Content moderation failed. Questions, answers, or knowledge base may contain sensitive content
503	API call exception, contact support

Code Examples

Text Conversation

1. CURL Request

Non-Streaming

curl --request POST \
  --url https://api.linkai.cloud/v1/chat/memory/completions \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "app_code": "",
    "question": "Who are you",
    "session_id": "123e4567-e89b-12d3-a456-426614174000"
  }'

Streaming

curl --request POST \
  --url https://api.linkai.cloud/v1/chat/memory/completions \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "app_code": "",
    "question": "Who are you",
    "session_id": "123e4567-e89b-12d3-a456-426614174000",
    "stream": true
}'

Note: Replace YOUR_API_KEY with your created API Key and app_code with your application code.

2. Python Request Examples

Non-Streaming

import requests

url = "https://api.linkai.cloud/v1/chat/memory/completions"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
}
body = {
    "app_code": "",
    "question": "Hello"
}
res = requests.post(url, json=body, headers=headers)
if res.status_code == 200:
    res_json = res.json()
    reply_text = res_json.get("choices")[0]['message']['content']
    session_id = res_json.get("session_id")
    print(f"session_id={session_id}, reply={reply_text}")
else:
    error = res.json().get("error")
    print(f"Request failed, status={res.status_code}, error_type={error.get('type')}, message={error.get('message')}")

Streaming

import json
import requests

url = "https://api.linkai.cloud/v1/chat/memory/completions"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
}
body = {
    "app_code": "",
    "question": "Write a design document for a login module",
    "stream": True
}
res = requests.post(url, json=body, headers=headers, stream=True)
for i in res.iter_lines():
    st = str(i, encoding="utf-8")
    st = st.replace("data: ", "", 1)
    if st:
        if st == "[DONE]":                  # Output complete
            break
        chunk = json.loads(st)
        if not chunk.get("choices"):
            continue
        chunk_message = chunk["choices"][0]["delta"].get("content")
        if chunk_message:
            print(chunk_message, end="")    # Output each chunk

Note: Replace YOUR_API_KEY with your created API Key and app_code with your application code.

Image Recognition

The API supports image input for visual question answering. Requirements:

• For Applications: Enable the "Image Recognition" plugin
• For Workflows: Include the "Image Recognition" plugin in your workflow

curl --request POST \
  --url https://api.linkai.cloud/v1/chat/memory/completions \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "app_code": "",
    "question": "What is in this image?",
    "session_id": "123e4567-e89b-12d3-a456-426614174000",
    "image_url": "https://cdn.linkai.cloud/docs/vision-model-config.jpg"
}'

Note:

• Replace YOUR_API_KEY with your created API Key and app_code with your application or workflow code.
• The image URL must be publicly accessible on the internet.

For any questions or assistance, contact us at [email protected].