new-api 接入 io.net 集群部署pkg/ionet 客户端库与 API 交互实战指南【免费下载链接】new-apiAI模型聚合管理中转分发系统一个应用管理您的所有AI模型支持将多种大模型转为统一格式调用支持OpenAI、Claude、Gemini等格式可供个人或者企业内部管理与分发渠道使用。 A Unified AI Model Management Distribution System. Aggregate all your LLMs into one app and access them via an OpenAI-compatible API, with native support for Claude (Messages) and Gemini formats.项目地址: https://gitcode.com/QuantumNous/new-api本指南以仓库文档 docs/ionet-client.md 为核心骨架围绕 io.net 集群重命名这一具体 API 调用展开并结合 pkg/ionet 的完整客户端实现系统讲解如何在 QuantumNous/new-api 中集成 io.netapi.io.solutions的容器集群部署能力包括客户端初始化、认证与统一请求封装、集群与部署生命周期管理、容器运维、硬件与位置查询、价格估算以及前端模型部署设置中的真实接线方式。读者读完可掌握 io.net 客户端库的全部公开方法、参数语义、返回结构与调用注意事项并能直接将其用于接入新的渠道或自动化运维脚本。一、文档定位一次真实的集群重命名调用仓库中与 io.net 客户端相关的说明文档 docs/ionet-client.md 记录了一次真实的 HTTP 调用示例原文如下Request URL https://api.io.solutions/v1/io-cloud/clusters/654fc0a9-0d4a-4db4-9b95-3f56189348a2/update-name Request Method PUT {status:succeeded,message:Cluster name updated successfully}这段内容展示了 io.net API 的典型交互特征请求方式PUT幂等更新语义用于修改集群名称URL 结构https://api.io.solutions/v1/io-cloud/clusters/{cluster_id}/update-name其中654fc0a9-0d4a-4db4-9b95-3f56189348a2是集群的唯一 IDUUID 格式成功响应返回 JSON 对象{status:succeeded,message:Cluster name updated successfully}注意该响应没有data包装层与大多数 io.net 端点返回{data: ...}的格式不同。这段文档中的 URL 与响应体在仓库源码 pkg/ionet/deployment.go 中得到了精确的对应实现——UpdateClusterName方法正是向/clusters/{clusterID}/update-name发送PUT请求并直接以UpdateClusterNameResponsestatusmessage两个字段解析响应体。这为理解整个 io.net 客户端库提供了一个真实的、可对照的样本。二、客户端库总览pkg/ionet 包结构与能力地图io.net 客户端被封装在 pkg/ionet 目录下共 6 个源文件各自职责清晰文件职责client.go客户端构造、HTTP 客户端抽象、统一请求封装、查询参数构建types.go全部请求/响应/错误的数据结构定义deployment.go部署Deployment与集群Cluster生命周期管理container.go容器Container查询、日志、重启/停止/执行hardware.go硬件类型、位置、可用性与余量查询jsonutil.go响应解析辅助data解包与宽松时间解析从整体能力看该客户端覆盖了 io.net 平台的核心操作域可以划分为五大类集群/部署生命周期创建、列表、详情、更新、延长、删除、改名容器运维容器列表/详情、日志获取与流式跟踪、重启、停止、执行命令硬件与位置硬件类型、单卡最大 GPU 数、位置列表、实时可用性价格估算按位置、硬件、时长、副本数估算成本并返回明细拆分连接自检测试 API Key 有效性并返回硬件与余量统计供前端测试连接使用。三、客户端初始化与认证3.1 三个构造函数在 pkg/ionet/client.go 中定义了三个构造入口// 面向公有 API默认 base URL func NewClient(apiKey string) *Client { return NewClientWithConfig(apiKey, DefaultBaseURL, nil) } // 面向企业 API func NewEnterpriseClient(apiKey string) *Client { return NewClientWithConfig(apiKey, DefaultEnterpriseBaseURL, nil) } // 全参数构造可自定义 base URL 与 HTTP 客户端 func NewClientWithConfig(apiKey, baseURL string, httpClient HTTPClient) *Client对应的常量定义pkg/ionet/client.goconst ( DefaultEnterpriseBaseURL https://api.io.solutions/enterprise/v1/io-cloud/caas DefaultBaseURL https://api.io.solutions/v1/io-cloud/caas DefaultTimeout 30 * time.Second )注意NewClientWithConfig中baseURL为空时回退到DefaultBaseURLhttpClient为 nil 时使用带 30 秒超时的默认 HTTP 客户端NewDefaultHTTPClient(DefaultTimeout)。HTTPClient是一个可插拔接口便于测试时注入 mock。3.2 认证方式X-API-KEY 头所有请求统一在makeRequestpkg/ionet/client.go中注入认证头headers : map[string]string{ X-API-KEY: c.APIKey, Content-Type: application/json, }即通过X-API-KEY请求头传递 API Key而非 Bearer Token 或查询参数。makeRequest还统一负责请求体 JSON 序列化、拼接BaseURL endpoint、错误响应处理。3.3 统一错误处理当响应状态码 400时makeRequest会优先尝试解析 io.net 常见的错误格式{detail: message}构造APIError{Code, Message}解析失败则回退为APIError{Code, Message: API request failed with status N, Details: 原始响应体}。APIError实现了error接口pkg/ionet/types.go调用方可通过类型断言判断具体错误。四、集群/部署生命周期管理4.1 创建部署DeployContainerfunc (c *Client) DeployContainer(req *DeploymentRequest) (*DeploymentResponse, error)请求体结构pkg/ionet/types.go及其必填校验pkg/ionet/deployment.go字段类型说明校验规则resource_private_namestring资源私有名称必填非空duration_hoursint租用时长小时≥ 1gpus_per_containerint每容器 GPU 数≥ 1hardware_idint硬件类型 ID 0location_ids[]int目标位置 ID 列表非空container_configContainerConfig容器配置副本数、环境变量、入口命令、流量端口、参数replica_count≥ 1registry_configRegistryConfig镜像仓库配置image_url必填可选用户名/密钥image_url必填其中ContainerConfig支持env_variables普通环境变量与secret_env_variables敏感环境变量两组键值Entrypoint与Args均为字符串数组TrafficPort用于声明对外流量端口。成功时端点POST /deploy直接返回{status: ..., deployment_id: ...}。4.2 查询部署列表与详情列表ListDeployments(opts *ListDeploymentsOptions)请求GET /deployments支持status、location_id、page、page_size、sort_by、sort_order等过滤与分页参数pkg/ionet/types.go这些参数会经过buildQueryParams转为查询字符串。返回的DeploymentList中每个Deployment还额外派生GPUCount与Replicas两个字段当前按HardwareQuantity1:1 映射见 pkg/ionet/deployment.go。详情GetDeployment(deploymentID)请求GET /deployment/{id}返回的DeploymentDetail包含完整的计费与运行信息AmountPaid已支付金额、CompletedPercent完成度、TotalGPUs、ComputeMinutesServed/Remaining已服务/剩余算力分钟、Locations等。4.3 更新、延长与删除更新配置UpdateDeployment(deploymentID, req)通过PATCH /deployment/{id}修改环境变量、入口命令、镜像等UpdateDeploymentRequestpkg/ionet/types.go。延长租期ExtendDeployment(deploymentID, req)通过POST /deployment/{id}/extend追加duration_hours≥ 1响应为最新的部署详情。删除部署DeleteDeployment(deploymentID)通过DELETE /deployment/{id}删除活跃部署。4.4 集群名称管理对应文档示例这正是 docs/ionet-client.md 记录的核心操作源码实现位于 pkg/ionet/deployment.go// 先校验名称可用性 func (c *Client) CheckClusterNameAvailability(clusterName string) (bool, error) // GET /clusters/check_cluster_name_availability?cluster_name... // 再更新集群名称 func (c *Client) UpdateClusterName(clusterID string, req *UpdateClusterNameRequest) (*UpdateClusterNameResponse, error) // PUT /clusters/{clusterID}/update-name其中UpdateClusterNameRequest的 JSON 字段为cluster_name响应结构UpdateClusterNameResponse{Status, Message}与文档中的{status:succeeded,message:Cluster name updated successfully}完全对应。两个方法均有空值校验集群 ID 非空、名称非空。文档中的完整请求 URL 与源码端点拼装一致PUT https://api.io.solutions/v1/io-cloud/clusters/{cluster_id}/update-name。五、容器运维与日志容器相关方法集中在 pkg/ionet/container.go方法HTTP 端点说明ListContainers(deploymentID)GET /deployment/{id}/containers列出部署下全部容器含public_url、uptime_percent、事件流GetContainerDetails(deploymentID, containerID)GET /deployment/{id}/container/{cid}单容器详情GetContainerJobs(deploymentID, containerID)GET /deployment/{id}/containers-jobs/{cid}容器任务列表GetContainerLogs(deploymentID, containerID, opts)GET /deployment/{id}/log/{cid}归一化日志把\r\n归一为\n逐行转为LogEntryGetContainerLogsRaw(...)同上原始文本日志StreamContainerLogs(...)同上 follow参数轮询式流式日志每 2 秒轮询一次支持 cursor 续传RestartContainer(...)POST /deployment/{id}/container/{cid}/restart重启容器StopContainer(...)POST /deployment/{id}/container/{cid}/stop停止容器ExecuteInContainer(...)POST /deployment/{id}/container/{cid}/exec在容器内执行命令返回output日志查询选项GetLogsOptionspkg/ionet/types.go支持start_time/end_time*time.Time、level、streamstdout/stderr、limit、cursor分页游标与follow流式跟踪。StreamContainerLogs采用轮询实现将follow置为 true不断拉取并以回调函数逐条投递日志条目遇到has_morefalse且无next_cursor时结束每次轮询间隔 2 秒以降低 API 压力源码注释也提示真实场景可用 SSE 或 WebSocket 做更高效的流式日志见 pkg/ionet/container.go。六、硬件、位置与价格估算6.1 硬件与位置查询pkg/ionet/hardware.goGetMaxGPUsPerContainer()请求GET /hardware/max-gpus-per-container返回每种硬件的max_gpus_per_container、available余量、硬件/品牌名称ListHardwareTypes()基于上述端点把MaxGPUInfo映射为HardwareType名称缺失时回退为Hardware {id}并计算总的可用数量Total为 0 时按各硬件available求和GetAvailableReplicas(hardwareID, gpuCount)请求GET /available-replicas返回各位置可用的副本数量ListLocations()/GetLocation(id)位置列表与详情ISO2国家码会被统一转为大写GetLocationAvailability(locationID)请求GET /locations/{id}/availability返回该位置各硬件的实时可用数量AvailableCount与单卡上限MaxGPUs。6.2 价格估算pkg/ionet/deployment.goGetPriceEstimation(req)请求GET /price是参数最复杂的端点之一。请求参数PriceEstimationRequestpkg/ionet/types.go与默认值逻辑currency默认usdcduration_type支持hour/day/week/month大小写不敏感含复数形式默认hour内部会换算为hourly/daily/weekly/monthly传给 API并据此计算总时长小时数日 ×24、周 ×24×7、月 ×24×30duration_qty时长数量缺省回退到duration_hourshardware_qty硬件数量缺省回退到gpus_per_container必填校验location_ids非空、hardware_id非 0、replica_count≥ 1。响应解析遵循 io.net 文档给出的data包装格式{ data: { replica_count: 0, gpus_per_container: 0, available_replica_count: [0], discount: 0, ionet_fee: 0, ionet_fee_percent: 0, currency_conversion_fee: 0, currency_conversion_fee_percent: 0, total_cost_usdc: 0 } }内部将其转换为统一的PriceEstimationResponseEstimatedCost取total_cost_usdcPriceBreakdown拆分为ComputeCost总成本扣除 io.net 手续费与货币转换费、TotalCost与HourlyRate总成本 ÷ 时长小时数Currency转为大写如USDC。七、响应解析的鲁棒性设计io.net API 存在两类显著的不一致性客户端通过 pkg/ionet/jsonutil.go 做了统一兼容data包装层不一致多数端点返回{data: ...}如价格估算、部署列表而部分端点直接返回裸对象如集群改名响应、部署创建响应。客户端据此分为两组使用decodeData/decodeDataWithFlexibleTimes自动解包data与直接json.Unmarshal裸解析。这也是UpdateClusterName特意注释根据 API 文档直接解析响应、不做 data 包装pkg/ionet/deployment.go的原因。时间戳时区缺失部分端点返回不带时区的本地时间字符串如2006-01-02T15:04:05直接time.Time反序列化会失败。decodeWithFlexibleTimes先解析为interface{}递归遍历所有字符串值尝试按RFC3339Nano、RFC3339及多种无时区布局解析成功则统一规范为 UTC 的RFC3339Nano后再反序列化pkg/ionet/jsonutil.go。部署详情、容器列表、日志等端点均走该路径。八、查询参数构建规则buildQueryParamspkg/ionet/client.go是所有 GET 请求的参数引擎规则如下nil值跳过string 空值跳过int/int64 为 0 跳过bool 为 false 跳过time.Time为零值跳过time.Time格式化为 RFC3339*time.Time判空后同样处理[]int、[]string非空时以 JSON 数组形式编码如location_ids[1,2]其余类型使用fmt.Sprint兜底最终以?url.Values.Encode()拼接。这套规则保证了零值不传参的语义例如ListDeployments不设置任何过滤项时不会携带无意义参数。九、在 new-api 中的真实接线模型部署设置io.net 客户端并非孤立库它已被 new-api 的模型部署Model Deployment功能集成入口为 controller/deployment.go开关与密钥通过全局配置项model_deployment.ionet.enabledtrue才启用与model_deployment.ionet.api_key控制controller/deployment.go配置缺失或未启用时返回io.net model deployment is not enabled or api key missing客户端选择getIoClient使用公有 APIionet.NewClient(apiKey)getIoEnterpriseClient使用企业 APIionet.NewEnterpriseClient(apiKey)controller/deployment.go对应上一节的两种 base URL连接自检TestIoNetConnection优先使用请求体中的api_key否则回退到已存储的配置密钥随后调用client.GetMaxGPUsPerContainer()验证密钥有效性成功则返回hardware_count与total_available统计controller/deployment.go失败时对*ionet.APIError做类型断言向用户展示detail中的真实错误信息前端设置页系统设置中的 io.net 部署设置区块位于 web/src/features/system-settings/integrations/ionet-deployment-settings-section.tsx相关的启用/配置状态类型定义在 web/src/features/system-settings/types.tshooks 文件 web/src/features/models/hooks/use-model-deployment-settings.ts 负责与后端设置接口交互共同构成填写 Key → 测试连接 → 启用部署的完整管理闭环。十、实战小结与调用建议结合 docs/ionet-client.md 的示例与 pkg/ionet 的实现接入 io.net 时的关键经验总结如下认证统一所有请求都依赖X-API-KEY请求头务必通过NewClient/NewEnterpriseClient构造不要手动拼接头部端点语义区分创建、延长、重启等变更操作为POST更新配置为PATCH改名与删除为PUT/DELETE查询一律GET响应格式分叉data包装与裸响应并存使用decodeData系函数解析列表/详情类端点对集群改名、部署创建这类裸响应端点直接json.Unmarshal名称管理流程先CheckClusterNameAvailability校验再UpdateClusterName提交{cluster_name: ...}成功响应即文档中的{status:succeeded,message:Cluster name updated successfully}错误排查捕获*ionet.APIError读取Message/Details优先展示detail字段中的服务端原始信息扩展接入若要将 io.net 能力暴露为 new-api 的模型部署渠道可参照 controller/deployment.go 的getIoClient/TestIoNetConnection模式配置项开关 API Key 存储 连接自检再在 router 层注册对应路由。以文档中的集群 ID654fc0a9-0d4a-4db4-9b95-3f56189348a2为例一次完整的改名调用应为curl -X PUT \ https://api.io.solutions/v1/io-cloud/clusters/654fc0a9-0d4a-4db4-9b95-3f56189348a2/update-name \ -H X-API-KEY: your-api-key \ -H Content-Type: application/json \ -d {cluster_name: my-new-cluster-name}期望返回{status:succeeded,message:Cluster name updated successfully}——与文档记录完全一致也可作为验证UpdateClusterName实现的端到端基准。【免费下载链接】new-apiAI模型聚合管理中转分发系统一个应用管理您的所有AI模型支持将多种大模型转为统一格式调用支持OpenAI、Claude、Gemini等格式可供个人或者企业内部管理与分发渠道使用。 A Unified AI Model Management Distribution System. Aggregate all your LLMs into one app and access them via an OpenAI-compatible API, with native support for Claude (Messages) and Gemini formats.项目地址: https://gitcode.com/QuantumNous/new-api创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
new-api 接入 io.net 集群部署：pkg/ionet 客户端库与 API 交互实战指南
new-api 接入 io.net 集群部署pkg/ionet 客户端库与 API 交互实战指南【免费下载链接】new-apiAI模型聚合管理中转分发系统一个应用管理您的所有AI模型支持将多种大模型转为统一格式调用支持OpenAI、Claude、Gemini等格式可供个人或者企业内部管理与分发渠道使用。 A Unified AI Model Management Distribution System. Aggregate all your LLMs into one app and access them via an OpenAI-compatible API, with native support for Claude (Messages) and Gemini formats.项目地址: https://gitcode.com/QuantumNous/new-api本指南以仓库文档 docs/ionet-client.md 为核心骨架围绕 io.net 集群重命名这一具体 API 调用展开并结合 pkg/ionet 的完整客户端实现系统讲解如何在 QuantumNous/new-api 中集成 io.netapi.io.solutions的容器集群部署能力包括客户端初始化、认证与统一请求封装、集群与部署生命周期管理、容器运维、硬件与位置查询、价格估算以及前端模型部署设置中的真实接线方式。读者读完可掌握 io.net 客户端库的全部公开方法、参数语义、返回结构与调用注意事项并能直接将其用于接入新的渠道或自动化运维脚本。一、文档定位一次真实的集群重命名调用仓库中与 io.net 客户端相关的说明文档 docs/ionet-client.md 记录了一次真实的 HTTP 调用示例原文如下Request URL https://api.io.solutions/v1/io-cloud/clusters/654fc0a9-0d4a-4db4-9b95-3f56189348a2/update-name Request Method PUT {status:succeeded,message:Cluster name updated successfully}这段内容展示了 io.net API 的典型交互特征请求方式PUT幂等更新语义用于修改集群名称URL 结构https://api.io.solutions/v1/io-cloud/clusters/{cluster_id}/update-name其中654fc0a9-0d4a-4db4-9b95-3f56189348a2是集群的唯一 IDUUID 格式成功响应返回 JSON 对象{status:succeeded,message:Cluster name updated successfully}注意该响应没有data包装层与大多数 io.net 端点返回{data: ...}的格式不同。这段文档中的 URL 与响应体在仓库源码 pkg/ionet/deployment.go 中得到了精确的对应实现——UpdateClusterName方法正是向/clusters/{clusterID}/update-name发送PUT请求并直接以UpdateClusterNameResponsestatusmessage两个字段解析响应体。这为理解整个 io.net 客户端库提供了一个真实的、可对照的样本。二、客户端库总览pkg/ionet 包结构与能力地图io.net 客户端被封装在 pkg/ionet 目录下共 6 个源文件各自职责清晰文件职责client.go客户端构造、HTTP 客户端抽象、统一请求封装、查询参数构建types.go全部请求/响应/错误的数据结构定义deployment.go部署Deployment与集群Cluster生命周期管理container.go容器Container查询、日志、重启/停止/执行hardware.go硬件类型、位置、可用性与余量查询jsonutil.go响应解析辅助data解包与宽松时间解析从整体能力看该客户端覆盖了 io.net 平台的核心操作域可以划分为五大类集群/部署生命周期创建、列表、详情、更新、延长、删除、改名容器运维容器列表/详情、日志获取与流式跟踪、重启、停止、执行命令硬件与位置硬件类型、单卡最大 GPU 数、位置列表、实时可用性价格估算按位置、硬件、时长、副本数估算成本并返回明细拆分连接自检测试 API Key 有效性并返回硬件与余量统计供前端测试连接使用。三、客户端初始化与认证3.1 三个构造函数在 pkg/ionet/client.go 中定义了三个构造入口// 面向公有 API默认 base URL func NewClient(apiKey string) *Client { return NewClientWithConfig(apiKey, DefaultBaseURL, nil) } // 面向企业 API func NewEnterpriseClient(apiKey string) *Client { return NewClientWithConfig(apiKey, DefaultEnterpriseBaseURL, nil) } // 全参数构造可自定义 base URL 与 HTTP 客户端 func NewClientWithConfig(apiKey, baseURL string, httpClient HTTPClient) *Client对应的常量定义pkg/ionet/client.goconst ( DefaultEnterpriseBaseURL https://api.io.solutions/enterprise/v1/io-cloud/caas DefaultBaseURL https://api.io.solutions/v1/io-cloud/caas DefaultTimeout 30 * time.Second )注意NewClientWithConfig中baseURL为空时回退到DefaultBaseURLhttpClient为 nil 时使用带 30 秒超时的默认 HTTP 客户端NewDefaultHTTPClient(DefaultTimeout)。HTTPClient是一个可插拔接口便于测试时注入 mock。3.2 认证方式X-API-KEY 头所有请求统一在makeRequestpkg/ionet/client.go中注入认证头headers : map[string]string{ X-API-KEY: c.APIKey, Content-Type: application/json, }即通过X-API-KEY请求头传递 API Key而非 Bearer Token 或查询参数。makeRequest还统一负责请求体 JSON 序列化、拼接BaseURL endpoint、错误响应处理。3.3 统一错误处理当响应状态码 400时makeRequest会优先尝试解析 io.net 常见的错误格式{detail: message}构造APIError{Code, Message}解析失败则回退为APIError{Code, Message: API request failed with status N, Details: 原始响应体}。APIError实现了error接口pkg/ionet/types.go调用方可通过类型断言判断具体错误。四、集群/部署生命周期管理4.1 创建部署DeployContainerfunc (c *Client) DeployContainer(req *DeploymentRequest) (*DeploymentResponse, error)请求体结构pkg/ionet/types.go及其必填校验pkg/ionet/deployment.go字段类型说明校验规则resource_private_namestring资源私有名称必填非空duration_hoursint租用时长小时≥ 1gpus_per_containerint每容器 GPU 数≥ 1hardware_idint硬件类型 ID 0location_ids[]int目标位置 ID 列表非空container_configContainerConfig容器配置副本数、环境变量、入口命令、流量端口、参数replica_count≥ 1registry_configRegistryConfig镜像仓库配置image_url必填可选用户名/密钥image_url必填其中ContainerConfig支持env_variables普通环境变量与secret_env_variables敏感环境变量两组键值Entrypoint与Args均为字符串数组TrafficPort用于声明对外流量端口。成功时端点POST /deploy直接返回{status: ..., deployment_id: ...}。4.2 查询部署列表与详情列表ListDeployments(opts *ListDeploymentsOptions)请求GET /deployments支持status、location_id、page、page_size、sort_by、sort_order等过滤与分页参数pkg/ionet/types.go这些参数会经过buildQueryParams转为查询字符串。返回的DeploymentList中每个Deployment还额外派生GPUCount与Replicas两个字段当前按HardwareQuantity1:1 映射见 pkg/ionet/deployment.go。详情GetDeployment(deploymentID)请求GET /deployment/{id}返回的DeploymentDetail包含完整的计费与运行信息AmountPaid已支付金额、CompletedPercent完成度、TotalGPUs、ComputeMinutesServed/Remaining已服务/剩余算力分钟、Locations等。4.3 更新、延长与删除更新配置UpdateDeployment(deploymentID, req)通过PATCH /deployment/{id}修改环境变量、入口命令、镜像等UpdateDeploymentRequestpkg/ionet/types.go。延长租期ExtendDeployment(deploymentID, req)通过POST /deployment/{id}/extend追加duration_hours≥ 1响应为最新的部署详情。删除部署DeleteDeployment(deploymentID)通过DELETE /deployment/{id}删除活跃部署。4.4 集群名称管理对应文档示例这正是 docs/ionet-client.md 记录的核心操作源码实现位于 pkg/ionet/deployment.go// 先校验名称可用性 func (c *Client) CheckClusterNameAvailability(clusterName string) (bool, error) // GET /clusters/check_cluster_name_availability?cluster_name... // 再更新集群名称 func (c *Client) UpdateClusterName(clusterID string, req *UpdateClusterNameRequest) (*UpdateClusterNameResponse, error) // PUT /clusters/{clusterID}/update-name其中UpdateClusterNameRequest的 JSON 字段为cluster_name响应结构UpdateClusterNameResponse{Status, Message}与文档中的{status:succeeded,message:Cluster name updated successfully}完全对应。两个方法均有空值校验集群 ID 非空、名称非空。文档中的完整请求 URL 与源码端点拼装一致PUT https://api.io.solutions/v1/io-cloud/clusters/{cluster_id}/update-name。五、容器运维与日志容器相关方法集中在 pkg/ionet/container.go方法HTTP 端点说明ListContainers(deploymentID)GET /deployment/{id}/containers列出部署下全部容器含public_url、uptime_percent、事件流GetContainerDetails(deploymentID, containerID)GET /deployment/{id}/container/{cid}单容器详情GetContainerJobs(deploymentID, containerID)GET /deployment/{id}/containers-jobs/{cid}容器任务列表GetContainerLogs(deploymentID, containerID, opts)GET /deployment/{id}/log/{cid}归一化日志把\r\n归一为\n逐行转为LogEntryGetContainerLogsRaw(...)同上原始文本日志StreamContainerLogs(...)同上 follow参数轮询式流式日志每 2 秒轮询一次支持 cursor 续传RestartContainer(...)POST /deployment/{id}/container/{cid}/restart重启容器StopContainer(...)POST /deployment/{id}/container/{cid}/stop停止容器ExecuteInContainer(...)POST /deployment/{id}/container/{cid}/exec在容器内执行命令返回output日志查询选项GetLogsOptionspkg/ionet/types.go支持start_time/end_time*time.Time、level、streamstdout/stderr、limit、cursor分页游标与follow流式跟踪。StreamContainerLogs采用轮询实现将follow置为 true不断拉取并以回调函数逐条投递日志条目遇到has_morefalse且无next_cursor时结束每次轮询间隔 2 秒以降低 API 压力源码注释也提示真实场景可用 SSE 或 WebSocket 做更高效的流式日志见 pkg/ionet/container.go。六、硬件、位置与价格估算6.1 硬件与位置查询pkg/ionet/hardware.goGetMaxGPUsPerContainer()请求GET /hardware/max-gpus-per-container返回每种硬件的max_gpus_per_container、available余量、硬件/品牌名称ListHardwareTypes()基于上述端点把MaxGPUInfo映射为HardwareType名称缺失时回退为Hardware {id}并计算总的可用数量Total为 0 时按各硬件available求和GetAvailableReplicas(hardwareID, gpuCount)请求GET /available-replicas返回各位置可用的副本数量ListLocations()/GetLocation(id)位置列表与详情ISO2国家码会被统一转为大写GetLocationAvailability(locationID)请求GET /locations/{id}/availability返回该位置各硬件的实时可用数量AvailableCount与单卡上限MaxGPUs。6.2 价格估算pkg/ionet/deployment.goGetPriceEstimation(req)请求GET /price是参数最复杂的端点之一。请求参数PriceEstimationRequestpkg/ionet/types.go与默认值逻辑currency默认usdcduration_type支持hour/day/week/month大小写不敏感含复数形式默认hour内部会换算为hourly/daily/weekly/monthly传给 API并据此计算总时长小时数日 ×24、周 ×24×7、月 ×24×30duration_qty时长数量缺省回退到duration_hourshardware_qty硬件数量缺省回退到gpus_per_container必填校验location_ids非空、hardware_id非 0、replica_count≥ 1。响应解析遵循 io.net 文档给出的data包装格式{ data: { replica_count: 0, gpus_per_container: 0, available_replica_count: [0], discount: 0, ionet_fee: 0, ionet_fee_percent: 0, currency_conversion_fee: 0, currency_conversion_fee_percent: 0, total_cost_usdc: 0 } }内部将其转换为统一的PriceEstimationResponseEstimatedCost取total_cost_usdcPriceBreakdown拆分为ComputeCost总成本扣除 io.net 手续费与货币转换费、TotalCost与HourlyRate总成本 ÷ 时长小时数Currency转为大写如USDC。七、响应解析的鲁棒性设计io.net API 存在两类显著的不一致性客户端通过 pkg/ionet/jsonutil.go 做了统一兼容data包装层不一致多数端点返回{data: ...}如价格估算、部署列表而部分端点直接返回裸对象如集群改名响应、部署创建响应。客户端据此分为两组使用decodeData/decodeDataWithFlexibleTimes自动解包data与直接json.Unmarshal裸解析。这也是UpdateClusterName特意注释根据 API 文档直接解析响应、不做 data 包装pkg/ionet/deployment.go的原因。时间戳时区缺失部分端点返回不带时区的本地时间字符串如2006-01-02T15:04:05直接time.Time反序列化会失败。decodeWithFlexibleTimes先解析为interface{}递归遍历所有字符串值尝试按RFC3339Nano、RFC3339及多种无时区布局解析成功则统一规范为 UTC 的RFC3339Nano后再反序列化pkg/ionet/jsonutil.go。部署详情、容器列表、日志等端点均走该路径。八、查询参数构建规则buildQueryParamspkg/ionet/client.go是所有 GET 请求的参数引擎规则如下nil值跳过string 空值跳过int/int64 为 0 跳过bool 为 false 跳过time.Time为零值跳过time.Time格式化为 RFC3339*time.Time判空后同样处理[]int、[]string非空时以 JSON 数组形式编码如location_ids[1,2]其余类型使用fmt.Sprint兜底最终以?url.Values.Encode()拼接。这套规则保证了零值不传参的语义例如ListDeployments不设置任何过滤项时不会携带无意义参数。九、在 new-api 中的真实接线模型部署设置io.net 客户端并非孤立库它已被 new-api 的模型部署Model Deployment功能集成入口为 controller/deployment.go开关与密钥通过全局配置项model_deployment.ionet.enabledtrue才启用与model_deployment.ionet.api_key控制controller/deployment.go配置缺失或未启用时返回io.net model deployment is not enabled or api key missing客户端选择getIoClient使用公有 APIionet.NewClient(apiKey)getIoEnterpriseClient使用企业 APIionet.NewEnterpriseClient(apiKey)controller/deployment.go对应上一节的两种 base URL连接自检TestIoNetConnection优先使用请求体中的api_key否则回退到已存储的配置密钥随后调用client.GetMaxGPUsPerContainer()验证密钥有效性成功则返回hardware_count与total_available统计controller/deployment.go失败时对*ionet.APIError做类型断言向用户展示detail中的真实错误信息前端设置页系统设置中的 io.net 部署设置区块位于 web/src/features/system-settings/integrations/ionet-deployment-settings-section.tsx相关的启用/配置状态类型定义在 web/src/features/system-settings/types.tshooks 文件 web/src/features/models/hooks/use-model-deployment-settings.ts 负责与后端设置接口交互共同构成填写 Key → 测试连接 → 启用部署的完整管理闭环。十、实战小结与调用建议结合 docs/ionet-client.md 的示例与 pkg/ionet 的实现接入 io.net 时的关键经验总结如下认证统一所有请求都依赖X-API-KEY请求头务必通过NewClient/NewEnterpriseClient构造不要手动拼接头部端点语义区分创建、延长、重启等变更操作为POST更新配置为PATCH改名与删除为PUT/DELETE查询一律GET响应格式分叉data包装与裸响应并存使用decodeData系函数解析列表/详情类端点对集群改名、部署创建这类裸响应端点直接json.Unmarshal名称管理流程先CheckClusterNameAvailability校验再UpdateClusterName提交{cluster_name: ...}成功响应即文档中的{status:succeeded,message:Cluster name updated successfully}错误排查捕获*ionet.APIError读取Message/Details优先展示detail字段中的服务端原始信息扩展接入若要将 io.net 能力暴露为 new-api 的模型部署渠道可参照 controller/deployment.go 的getIoClient/TestIoNetConnection模式配置项开关 API Key 存储 连接自检再在 router 层注册对应路由。以文档中的集群 ID654fc0a9-0d4a-4db4-9b95-3f56189348a2为例一次完整的改名调用应为curl -X PUT \ https://api.io.solutions/v1/io-cloud/clusters/654fc0a9-0d4a-4db4-9b95-3f56189348a2/update-name \ -H X-API-KEY: your-api-key \ -H Content-Type: application/json \ -d {cluster_name: my-new-cluster-name}期望返回{status:succeeded,message:Cluster name updated successfully}——与文档记录完全一致也可作为验证UpdateClusterName实现的端到端基准。【免费下载链接】new-apiAI模型聚合管理中转分发系统一个应用管理您的所有AI模型支持将多种大模型转为统一格式调用支持OpenAI、Claude、Gemini等格式可供个人或者企业内部管理与分发渠道使用。 A Unified AI Model Management Distribution System. Aggregate all your LLMs into one app and access them via an OpenAI-compatible API, with native support for Claude (Messages) and Gemini formats.项目地址: https://gitcode.com/QuantumNous/new-api创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考