JVS Crew API 文档

接口描述

获取用户进行对话所需访问令牌（AccessToken），供后续调用 Chat 接口验证身份。

令牌格式：AccessToken 为 JWT，由 Header.Payload.Signature 三段经 Base64URL 编码后以 . 连接成一行；下表示例为脱敏示意，实际 RequestId、JWT 各段均更长。

令牌有效期：AccessToken 在一段时间内有效，过期后须重新调用本接口获取新令牌。

请求信息

• 认证方式：POP V1 签名（AK/SK），详见使用示例

• Action：GetAccessToken

请求参数

请求示例

params = {
    "Format": "JSON",
    "Version": "2026-03-11",
    "AccessKeyId": ak,
    "SignatureMethod": "HMAC-SHA1",
    "Timestamp": _now_utc(),
    "SignatureVersion": "1.0",
    "SignatureNonce": str(uuid.uuid4()),
    "Action": "GetAccessToken",
    "RegionId": "cn-shanghai",
    "ExternalUserId": "user-38764",
}
params["Signature"] = _sign_v1(params, sk)

响应参数

响应示例

成功：

{
  "Success": true,
  "Code": "200",
  "HttpStatusCode": 200,
  "RequestId": "EA12****-****-****-****-****E5C",
  "AccessToken": "eyJhbGc****.eyJ********.****TCk"
}

失败：

{
  "Success": false,
  "Code": "400",
  "Message": "Invalid ExternalUserId",
  "HttpStatusCode": 400
}

错误码

接口描述

与 JVS Crew 发起流式对话，采用 Server-Sent Events（SSE） 协议实时推送对话内容。

特性：

• 实时流式响应，降低首字延迟

• 支持多模态输入（文本、图片、文件）

• 会话保持，支持多轮对话

• 事件驱动，精确控制消息状态

请求信息

• 请求方法：POST

• Content-Type：application/json

• 响应 Content-Type：text/event-stream

Query 参数

请求头（Header）

请求参数

请求示例

curl -N -X POST \
  'https://wuyingai.cn-shanghai.aliyuncs.com/api/agent/chat?Authorization=Bearer%20<access_token>&TemplateId=<template_id>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: text/event-stream' \
  -H 'Cache-Control: no-cache' \
  -H 'Connection: keep-alive' \
  -H 'x-acs-version: 2026-03-11' \
  -H 'x-acs-action: Chat' \
  -H 'x-acs-date: 2026-03-18T06:21:31Z' \
  -d '{
    "Input": "[{\"Role\":\"user\",\"Content\":[{\"Type\":\"text\",\"Text\":\"你好\"}]}]",
    "ExternalUserId": "test-user",
    "SessionId": "test-session-001"
  }

响应参数（SSE 事件）

SSE 响应格式为 data: <JSON>\n\n，每行为一个 JSON 事件对象。服务端定期发送 :ping 心跳行（无 data: 前缀）以保持连接，客户端忽略即可。

SSE 响应示例

完整流程：

data: {"Object":"response","Status":"created","SequenceNumber":"0"}

data: {"Object":"response","Status":"in_progress","SequenceNumber":"1"}

: ping

data: {"Object":"message","Id":"msg_001","SessionId":"176405663****961","Type":"reasoning","Status":"in_progress","SequenceNumber":"2"}

data: {"Object":"content","Id":"msg_001","Type":"text","Status":"in_progress","Text":"用户在打招呼","SequenceNumber":"3"}

data: {"Object":"content","Id":"msg_001","Type":"text","Status":"in_progress","Text":"，我简单回复即可","SequenceNumber":"4"}

data: {"Object":"message","Id":"msg_001","Type":"message","Status":"in_progress","SequenceNumber":"5"}

data: {"Object":"content","Id":"msg_001","Type":"text","Status":"in_progress","Text":"您好","SequenceNumber":"6"}

data: {"Object":"content","Id":"msg_001","Type":"text","Status":"in_progress","Text":"！","SequenceNumber":"7"}

data: {"Object":"content","Id":"msg_001","Type":"text","Status":"completed","Text":"用户在打招呼，我简单回复即可","SequenceNumber":"8"}

data: {"Object":"message","Id":"msg_001","Type":"reasoning","Status":"completed","SequenceNumber":"9"}

data: {"Object":"message","Id":"msg_001","Type":"message","Status":"completed","Content":[{"Type":"text","Text":"您好！"}],"SequenceNumber":"10"}

data: {"Object":"response","Status":"completed","SequenceNumber":"11"}

接口描述

获取会话中文件上传 URL、沙箱内路径及 FileKey，用于将文件上传至 Agentbay 为用户提供的 Context 存储空间。文件上传分三步完成：

1. 调用本接口获取 UploadUrl 和 FileKey

2. 使用 HTTP PUT 请求将文件内容上传到 UploadUrl（直传至对象存储，无需额外签名）

3. 使用该 FileKey 调用 SyncContext 将文件同步到沙箱，同步后 Agent 才能使用该文件

请求信息

• 认证方式：POP V1 签名（AK/SK），与 GetAccessToken 相同

• Action：GetChatFileUploadUrl

请求参数

请求示例

params = {
    "Format": "JSON",
    "Version": "2026-03-11",
    "AccessKeyId": ak,
    "SignatureMethod": "HMAC-SHA1",
    "Timestamp": _now_utc(),
    "SignatureVersion": "1.0",
    "SignatureNonce": str(uuid.uuid4()),
    "Action": "GetChatFileUploadUrl",
    "RegionId": "cn-shanghai",
    "FileName": "report.pdf",
    "ExternalUserId": "user-38764",
    "TemplateId": "template-abc123",
}
params["Signature"] = _sign_v1(params, sk)

响应参数

响应示例

成功：

{
  "Success": true,
  "Code": "200",
  "HttpStatusCode": 200,
  "RequestId": "EA12****-****-****-****-****E5C",
  "UploadUrl": "https://oss-example.aliyuncs.com/upload/...",
  "UploadHeadersHint": "...",
  "SandboxPath": "/home/wuying/jvscrew/uploads/report_a1b2c3d4.pdf",
  "FileKey": "uploads/report_a1b2c3d4.pdf"
}

接口描述

同步指定用户的 Context 中指定文件内容到沙箱环境，使沙箱中的用户数据与 Context 保持同步。

请求信息

• 认证方式：POP V1 签名（AK/SK），与 GetAccessToken 相同

• Action：SyncContext

请求参数

请求示例

params = {
    "Format": "JSON",
    "Version": "2026-03-11",
    "AccessKeyId": ak,
    "SignatureMethod": "HMAC-SHA1",
    "Timestamp": _now_utc(),
    "SignatureVersion": "1.0",
    "SignatureNonce": str(uuid.uuid4()),
    "Action": "SyncContext",
    "RegionId": "cn-shanghai",
    "ExternalUserId": "user-38764",
    "FileKey": "uploads/report_a1b2c3d4.pdf",
    "TemplateId": "template-abc123",
}
params["Signature"] = _sign_v1(params, sk)

响应参数

响应示例

成功：

{
  "Success": true,
  "Code": "200",
  "HttpStatusCode": 200,
  "RequestId": "EA12****-****-****-****-****E5C"
}

接口描述

列举指定用户的会话列表。每个元素包含 SessionId，可用于查询历史、中止或删除会话。

请求信息

• 请求方法：GET（也接受 POST）

Query 参数

请求头（Header）

响应参数

Chats 数组元素：

响应示例

成功：

{
  "Success": true,
  "Code": "200",
  "HttpStatusCode": 200,
  "RequestId": "EA12****-****-****-****-****E5C",
  "Chats": [
    {
      "Id": "4bd0****02f",
      "Name": "你好",
      "SessionId": "curl-test-session-********",
      "UserId": "u-open-************",
      "Channel": "console",
      "CreatedAt": "2026-03-26T03:51:42.071603Z",
      "UpdatedAt": "2026-03-26T03:52:03.000000Z",
      "Meta": {}
    }
  ]
}

错误码

接口描述

根据 SessionId 获取指定会话的历史消息列表，包含用户消息和 AI 回复。

请求信息

• 请求方法：GET（也接受 POST）

Query 参数

请求头（Header）

响应参数

Messages 数组元素：

Content 数组元素：

响应示例

成功：

{
  "Success": true,
  "Code": "200",
  "HttpStatusCode": 200,
  "RequestId": "123***456",
  "Messages": [
    {
      "Id": "msg_5e8d****aa1d",
      "Role": "user",
      "Type": "message",
      "Object": "message",
      "Status": "completed",
      "Error": null,
      "SequenceNumber": null,
      "Content": [
        {
          "Object": "content",
          "Status": "completed",
          "Error": null,
          "MsgId": "msg_5e8d****aa1d",
          "Text": "你好",
          "Data": null,
          "SequenceNumber": null
        }
      ],
      "Metadata": {
        "OriginalId": "msg_20e8****8ff3",
        "OriginalName": "user"
      }
    },
    {
      "Id": "msg_8574****0563",
      "Role": "assistant",
      "Type": "message",
      "Object": "message",
      "Status": "completed",
      "Error": null,
      "SequenceNumber": null,
      "Content": [
        {
          "Object": "content",
          "Status": "completed",
          "Error": null,
          "MsgId": "msg_8574****0563",
          "Text": "你好，小伙伴！有什么我可以帮你的吗？",
          "Data": null,
          "SequenceNumber": null
        }
      ],
      "Metadata": {
        "OriginalId": "dXRT****MUV",
        "OriginalName": "JVSCrewAgent"
      }
    }
  ]
}

错误码

接口描述

中止正在执行的 Agent 对话任务。调用后 Agent 将立即停止推理和工具执行，不再产生新的 Token 输出。适用于主动取消长时间运行的任务，或需要立即终止 Agent 的场景。

中止机制：服务端取消 Agent 执行任务，断开与大模型的连接，确保不再产生 Token。已完成的对话历史保留不变，后续可在同一 SessionId 下继续对话。

请求信息

• 请求方法：POST（也接受 GET）

• Content-Type：application/json

Query 参数

请求头（Header）

请求参数

请求体示例

{
  "SessionId": "test-session-001"
}

响应参数

响应示例

成功（任务已中止）：

{
  "Success": true,
  "Code": "200",
  "HttpStatusCode": 200,
  "RequestId": "EA12****-****-****-****-****E5C",
  "Stopped": true
}

成功（当前无运行中任务）：

{
  "Success": true,
  "Code": "200",
  "HttpStatusCode": 200,
  "RequestId": "FA23****-****-****-****-****D4B",
  "Stopped": false
}

错误码

接口描述

根据 SessionId 删除对话记录，包括对话元数据和会话状态文件。删除后该会话的历史消息清空且无法恢复。

请求信息

• 请求方法：POST

• Content-Type：application/json

Query 参数

请求头（Header）

请求参数

请求体示例

{
  "SessionId": "test-session-001"
}

响应参数

响应示例

成功：

{
  "Success": true,
  "Code": "200",
  "HttpStatusCode": 200,
  "RequestId": "EA12****-****-****-****-****E5C",
  "Deleted": true
}

错误码

接口描述

获取当前用户沙箱会话状态与资源地址。可判断沙箱是否已激活，并获取沙箱的资源访问 URL 和会话标识。

请求信息

• 请求方法：GET（也接受 POST）

Query 参数

请求头（Header）

请求参数

无额外请求参数。用户身份通过 JWT 令牌自动携带。

响应参数

响应示例

成功（沙箱已激活）：

{
  "Success": true,
  "Code": "200",
  "HttpStatusCode": 200,
  "RequestId": "EA12****-****-****-****-****E5C",
  "ResourceUrl": "https://jvscrew.example.com/resource/...",
  "SandboxSessionId": "session-abc123",
  "SessionActive": "true"
}

成功（沙箱未激活）：

{
  "Success": true,
  "Code": "200",
  "HttpStatusCode": 200,
  "RequestId": "FA23****-****-****-****-****D4B",
  "ResourceUrl": null,
  "SandboxSessionId": null,
  "SessionActive": "false"
}

错误码

接口描述

获取租户当月计费概览，包含消耗积分、会话数和平均消耗等指标。

请求信息

• 认证方式：POP V1 签名（AK/SK），与 GetAccessToken 相同

• Action：GetBillingOverview

请求参数

无额外请求参数。租户身份通过 AK/SK 自动识别。

请求示例

params = {
    "Format": "JSON",
    "Version": "2026-03-11",
    "AccessKeyId": ak,
    "SignatureMethod": "HMAC-SHA1",
    "Timestamp": _now_utc(),
    "SignatureVersion": "1.0",
    "SignatureNonce": str(uuid.uuid4()),
    "Action": "GetBillingOverview",
    "RegionId": "cn-shanghai",
}
params["Signature"] = _sign_v1(params, sk)

响应参数

响应示例

成功：

{
  "Success": true,
  "Code": "ok",
  "HttpStatusCode": 200,
  "RequestId": "EA12****-****-****-****-****E5C",
  "MonthlyCredit": 125.50,
  "MonthlySessions": 42,
  "AvgCreditPerSession": 2.99,
  "CycleStart": "2026-04-01T00:00:00Z",
  "CycleEnd": "2026-04-30T23:59:59Z"
}

错误码

接口描述

按用户查询当月消耗明细，支持分页和按外部用户 ID 过滤。

请求信息

• 认证方式：POP V1 签名（AK/SK），与 GetAccessToken 相同

• Action：ListUserConsumption

请求参数

请求示例

params = {
    "Format": "JSON",
    "Version": "2026-03-11",
    "AccessKeyId": ak,
    "SignatureMethod": "HMAC-SHA1",
    "Timestamp": _now_utc(),
    "SignatureVersion": "1.0",
    "SignatureNonce": str(uuid.uuid4()),
    "Action": "ListUserConsumption",
    "RegionId": "cn-shanghai",
    "ExternalUserIds": "alice,bob",
    "PageSize": "20",
    "PageNumber": "1",
}
params["Signature"] = _sign_v1(params, sk)

响应参数

Users 数组元素：

响应示例

成功：

{
  "Success": true,
  "Code": "ok",
  "HttpStatusCode": 200,
  "RequestId": "EA12****-****-****-****-****E5C",
  "Users": [
    {
      "UserId": "u-open-abc123",
      "ExternalUserId": "alice",
      "InstanceId": "jvscrew-u-open-abc123",
      "MonthlyCredit": 28.50,
      "MonthlySessions": 12,
      "MonthlyDurationHours": 3.25,
      "MonthlyDurationMinutes": 195.00
    },
    {
      "UserId": "u-open-def456",
      "ExternalUserId": "bob",
      "InstanceId": "jvscrew-u-open-def456",
      "MonthlyCredit": 15.00,
      "MonthlySessions": 8,
      "MonthlyDurationHours": 1.50,
      "MonthlyDurationMinutes": 90.00
    }
  ],
  "TotalCount": 2,
  "PageSize": 20,
  "PageNumber": 1
}

错误码

接口描述

创建定时任务，支持 cron 表达式和固定间隔调度。

请求信息

• 认证方式：JWT 令牌（Authorization Query 参数）

• Action：CreateScheduledTask

Query 参数

请求头（Header）

请求参数

请求示例

curl -X POST \
  'https://wuyingai.cn-shanghai.aliyuncs.com/?Authorization=Bearer%20<access_token>' \
  -H 'Content-Type: application/json' \
  -H 'x-acs-version: 2026-03-11' \
  -H 'x-acs-action: CreateScheduledTask' \
  -H 'x-acs-date: 2026-04-22T06:00:00Z' \
  -d '{
    "Name": "每日技术简报",
    "Instruction": "帮我总结今天的技术新闻",
    "Schedule": {"Type": "cron", "Expr": "0 9 * * *", "Timezone": "Asia/Shanghai"},
    "Sinks": [{"Sink": "im_push", "Channel": "dingtalk", "ChannelInstanceId": "", "TargetUserId": "<user>", "TargetSessionId": "", "Meta": {}}]
  }'

响应参数（Task 对象）

所有返回 Task 的接口（Create / Update / Get）共用以下结构：

响应示例

{
  "TaskId": "bd0f7607-538c-47b4-9b1e-380e12947640",
  "TemplateId": "template-zc9ecvdf",
  "ExternalUserId": "verify-schedule-user",
  "Name": "每日技术简报",
  "Status": "active",
  "Instruction": "帮我总结今天的技术新闻",
  "Schedule": {"Type": "cron", "Expr": "0 9 * * *", "Timezone": "Asia/Shanghai"},
  "Sinks": [],
  "NextRunAt": "2026-04-22T09:00:00",
  "CreatedAt": "2026-04-21T23:32:53",
  "UpdatedAt": "2026-04-21T23:32:53"
}

接口描述

更新指定定时任务的配置。

请求信息

• 认证方式：JWT 令牌（Authorization Query 参数），与 CreateScheduledTask 相同

• Action：UpdateScheduledTask

Query 参数和请求头与 CreateScheduledTask 相同，x-acs-action 改为 UpdateScheduledTask。

请求参数

响应参数

同 CreateScheduledTask 响应（Task 对象）。

接口描述

根据 TaskId 查询定时任务详情。

请求信息

• 认证方式：JWT 令牌（Authorization Query 参数），与 CreateScheduledTask 相同

• Action：GetScheduledTask

Query 参数和请求头与 CreateScheduledTask 相同，x-acs-action 改为 GetScheduledTask。

请求参数

响应参数

同 CreateScheduledTask 响应（Task 对象）。

接口描述

分页列举当前用户的定时任务。

请求信息

• 认证方式：JWT 令牌（Authorization Query 参数），与 CreateScheduledTask 相同

• Action：ListScheduledTasks

Query 参数和请求头与 CreateScheduledTask 相同，x-acs-action 改为 ListScheduledTasks。

请求参数

响应参数

响应示例

{
  "Tasks": [
    {
      "TaskId": "bd0f7607-538c-47b4-9b1e-380e12947640",
      "Name": "每日技术简报",
      "Status": "active",
      "NextRunAt": "2026-04-22T09:00:00"
    }
  ],
  "TotalCount": 1,
  "PageNumber": 1,
  "PageSize": 20
}

接口描述

删除指定的定时任务。

请求信息

• 认证方式：JWT 令牌（Authorization Query 参数），与 CreateScheduledTask 相同

• Action：DeleteScheduledTask

Query 参数和请求头与 CreateScheduledTask 相同，x-acs-action 改为 DeleteScheduledTask。

请求参数

响应参数

响应示例

{"Deleted": true}

接口描述

查询定时任务的执行记录列表，支持游标分页。

请求信息

• 认证方式：JWT 令牌（Authorization Query 参数），与 CreateScheduledTask 相同

• Action：ListScheduledTaskRuns

Query 参数和请求头与 CreateScheduledTask 相同，x-acs-action 改为 ListScheduledTaskRuns。

请求参数

响应参数

Runs 数组元素：

响应示例

{
  "Runs": [
    {
      "RunId": "run-abc123",
      "TaskId": "bd0f7607-538c-47b4-9b1e-380e12947640",
      "TemplateId": "template-zc9ecvdf",
      "Status": "succeeded",
      "ResultPayload": "今日技术要闻：...",
      "PushStatus": "succeeded",
      "StartedAt": "2026-04-22T09:00:01",
      "FinishedAt": "2026-04-22T09:02:35",
      "CreatedAt": "2026-04-22T09:00:00"
    }
  ],
  "NextCursor": null
}

Schedule 对象

Type 与 Expr 对照表：

Sinks 对象

Run 状态流转

running → succeeded（执行成功）
        → failed（执行失败）

推送状态（PushStatus）

定时任务错误码