跳转至

推理接入点管理接口

本文档说明 MagikCloud开放平台 暴露的推理接入点性能及用量数据查询 HTTP 接口。

通用说明

  • 基础地址：https://openapi.magikcloud.cn/api/v1
  • 时间范围参数（start_time、end_time）使用 RFC3339 格式，例如 2025-11-10T00:00:00Z
  • 所有接口均返回结构一致，在响应体中通过 code 表示业务状态
  • 若需多值枚举（如 token_buckets），可重复使用查询参数：token_buckets=1&token_buckets=2

  • 统一响应结构：

    • code：业务状态码，见下方错误码表
    • message：对 code 的人类可读描述

    • data：具体业务数据，不同接口结构各自说明

    • 示例： { "code": "OK", "message": "ok", "data": { /* 业务数据 */ } }

错误码

HTTP 状态码 code 说明 处理建议
200 OK 请求成功 无需操作
400 BAD_REQUEST 参数缺失或格式错误 按提示修正请求参数
401 UNAUTHORIZED AccessKey 认证失败 重新获取并携带凭证
403 FORBIDDEN 权限不足 调整访问密钥或访问对象
404 TENANT_NOT_FOUND 租户不存在 确认 tenant
404 PROJECT_NOT_FOUND 项目不存在 确认 project
404 ENDPOINT_NOT_FOUND 接入点不存在 确认 endpoint
500 INTERNAL_SERVER_ERROR 服务内部错误 重试；若持续出现请联系支持

时间序列数据查询

  • HTTP 方法：GET
  • 路径：/metrics/timeseries
  • 目标：按时间聚合返回指定指标的时间序列数据

Query 参数

参数 类型 是否必填 说明
tenant_id string 三选一必填 租户 ID
project_id string 三选一必填 项目 ID
endpoint string 三选一必填 接入点标识
metric string 是 指标枚举值
token_buckets string[] 否 Token长度分桶的枚举列表
start_time string 是 查询开始时间（含）
end_time string 是 查询结束时间（不含）

参数优先级

接入点类型：预置接入点 preset endpoint，自定义接入点 custom endpoint

  • 仅 tenant_id：按租户过滤
  • 仅 project_id：按项目及其隐含项目所属过滤
  • 仅 custom endpoint：按自定义接入点及其隐含项目/租户所属过滤

同时提供时优先级：custom endpoint > project_id > tenant_id > preset endpoint

指标枚举（metric）

  • TIMESERIES_METRIC_RPM：接口 RPM
  • TIMESERIES_METRIC_TPM：Token 速率
  • TIMESERIES_METRIC_INTERFACE_DELAY：接口延时
  • TIMESERIES_METRIC_ERROR_RATE：错误率
  • TIMESERIES_METRIC_HTTP_4XX_RATE：4xx HTTP 状态码速率
  • TIMESERIES_METRIC_HTTP_5XX_RATE：5xx HTTP 状态码速率
  • TIMESERIES_METRIC_FIRST_TOKEN_DELAY：首 Token 延时，TTFT
  • TIMESERIES_METRIC_NON_FIRST_TOKEN_DELAY：非首 Token 延时，TPOT
  • TIMESERIES_METRIC_AVG_INPUT_TOKENS：单次请求 tokens 输入数量
  • TIMESERIES_METRIC_AVG_OUTPUT_TOKENS：单次请求 tokens 输出数量
  • TIMESERIES_METRIC_TOTAL_TOKENS：总 Token 数
  • TIMESERIES_METRIC_TOTAL_PROMPT_TOKENS：总 Prompt Token 数
  • TIMESERIES_METRIC_TOTAL_COMPLETION_TOKENS：总 Completion Token 数
  • TIMESERIES_METRIC_TOTAL_REQUESTS：总请求数

Token Bucket 枚举（token_buckets）

  • TOKEN_BUCKET_UNSPECIFIED：未指定
  • TOKEN_BUCKET_INPUT_0_32K_OUTPUT_LE_200：输入 ≤ 32k 且输出 ≤ 200
  • TOKEN_BUCKET_INPUT_0_32K_OUTPUT_GT_200：输入 ≤ 32k 且输出 > 200
  • TOKEN_BUCKET_INPUT_32K_128K：输入 32k–128k
  • TOKEN_BUCKET_INPUT_128K_256K：输入 128k–256k

示例响应

{
    "code": "OK",
    "message": "ok",
    "data": {
        "list": [
            {
                "tokenBucket": "TOKEN_BUCKET_UNSPECIFIED",
                "points": [
                    {
                        "timestamp": "2025-11-12T06:23:00Z",
                        "value": 207
                    },
                    {
                        "timestamp": "2025-11-12T06:24:00Z",
                        "value": 208
                    },
                    {
                        "timestamp": "2025-11-12T06:26:00Z",
                        "value": 207
                    },
                    {
                        "timestamp": "2025-11-26T11:37:00Z",
                        "value": 255
                    }
                ]
            },
            {
                "tokenBucket": "TOKEN_BUCKET_INPUT_0_32K_OUTPUT_LE_200",
                "points": [
                    {
                        "timestamp": "2025-11-12T06:23:00Z",
                        "value": 207
                    },
                    {
                        "timestamp": "2025-11-12T06:26:00Z",
                        "value": 207
                    },
                    {
                        "timestamp": "2025-11-26T11:37:00Z",
                        "value": 255
                    }
                ]
            }
        ]
    }
}

表格数据查询

  • HTTP 方法：GET
  • 路径：/metrics/table
  • 目标：返回指定指标的分布类数据（表格形态）

Query 参数

参数 类型 是否必填 说明
tenant_id string 三选一必填 租户 ID
project_id string 三选一必填 项目 ID
endpoint string 三选一必填 接入点标识
metric string 是 指标枚举值
start_time string 是 查询开始时间（含）
end_time string 是 查询结束时间（不含）

参数优先级

规则与时间序列数据查询接口一致

指标枚举（metric）

  • TABLE_METRIC_ERROR_DETAIL：错误详情
  • TABLE_METRIC_USAGE_DETAIL：用量详情

示例响应

{
    "code": "OK",
    "message": "ok",
    "data": {
        "headers": [
            "TotalRequests",
            "TotalTokens",
            "TotalPromptTokens",
            "TotalCompletionTokens"
        ],
        "rows": [
            {
                "columns": [
                    "987012364",
                    "3247987983214",
                    "633624454354",
                    "2614363528860"
                ]
            }
        ]
    }
}

headers 表示表头，rows 为每行数据，不同列值顺序与表头一致。