多模态内容

会话多模态数据

写入流程

会话多模态数据按两步写入：

1. 调用 POST /api/resources 上传文件，取得 gumem://resources/<hex>。
2. 调用 SDK 的 add_messages / addMessages，或 HTTP POST /api/sessions/{session_id}/messages，在 Message 中传入 resource_urls。

POST /api/resources 使用 multipart/form-data：

字段	必填	说明
Authorization	是	Header，格式为 Api-Key <api_key>。
user_id	是	业务系统中的用户 ID。
session_id	否	关联的 Session ID。为空或不传时使用 default。
content_type	是	上传文件的内容类型。
file	是	通过 multipart file 字段上传的二进制文件。

Message 中的 resource_urls 使用数组形式，只放内部资源 URL：

{
  "role": "user",
  "content": "User uploaded a receipt. OCR text: dinner at Bistro A, total 86.40 SGD.",
  "resource_urls": ["gumem://resources/<hex>"]
}

支持的文件类型

text、image、video 和 pdf 都通过 multipart 的 file 字段上传。上传时填写 content_type 表示资源类型。

类型	content_type
Text	text/plain
Image	image/png、image/jpeg、image/webp
Video	video/mp4
PDF	application/pdf

Images 接入示例

先上传图片资源：

curl -X POST "http://localhost:8000/api/resources" \
  -H "Authorization: Api-Key <api_key>" \
  -F "user_id=user_123" \
  -F "session_id=session_123" \
  -F "content_type=image/png" \
  -F "file=@./receipt.png"

从响应中取得资源 URL，例如 gumem://resources/<hex>，再写入会话 Message：

curl -X POST "http://localhost:8000/api/sessions/session_123/messages" \
  -H "Authorization: Api-Key <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "User uploaded a receipt image. OCR text: dinner at Bistro A, total 86.40 SGD, paid on 2026-04-24.",
        "resource_urls": ["gumem://resources/<hex>"]
      }
    ]
  }'

行为多模态数据

行为多模态数据与会话多模态数据使用相同的资源流程：先调用 POST /api/resources 上传资源，再写入行为数据。

区别在于写入方法使用 User Actions / ActionLog 方法，例如 Node SDK 的 gumem.userActions.create(...) 或 Python SDK 的 gumem.user_actions.create(...)。在 ActionLog input 中传入 resource_urls，用于关联行为发生时产生或引用的文件资源。

JavaScript

await gumem.userActions.create({
  user_id: "user_123",
  timestamp: new Date(),
  content: "User uploaded a signed contract PDF during onboarding.",
  session_id: "session_123",
  event_type: "document_upload",
  page: "onboarding",
  resource_urls: ["gumem://resources/<hex>"]
});

Python

from datetime import datetime, timezone

gumem.user_actions.create({
    "user_id": "user_123",
    "timestamp": datetime(2026, 4, 24, 12, 30, tzinfo=timezone.utc),
    "content": "User uploaded a signed contract PDF during onboarding.",
    "session_id": "session_123",
    "event_type": "document_upload",
    "page": "onboarding",
    "resource_urls": ["gumem://resources/<hex>"],
})

resource_urls 只表示 ActionLog 与资源之间的引用关系。若希望 GUMem 记住文件中的内容，请把摘要、转写、识别结果或人工描述写入 content。

文件大小限制

建议调用方在上传前按资源类型控制文件大小：

类型	推荐上限
Text	1 MB
Image	10 MB
PDF	25 MB
Video	100 MB

超过限制时上传会失败。调用方应在上传前压缩文件，或把长文本、长 PDF、长视频拆分为更小的资源后再上传。