# 创建推理接入点

> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。

`POST https://ark.cn-beijing.volcengineapi.com/?Action=CreateEndpoint&Version=2024-01-01`

创建一个推理接入点（Endpoint），用于调用模型服务。接入点是调用模型的入口资源，绑定模型后即可通过接入点 ID 发起推理请求。

> **说明：注意**
>
> 创建接入点为异步操作，返回 *Id* 后接入点进入调度（`Scheduling`）状态，运行就绪后转为 `Running`。计费随接入点进入 `Running` 状态开始；如需先校验参数而不实际创建，可设置 *DryRun* 为 `true`。

## 鉴权

本接口支持鉴权方式如下，详情请参见 [Base URL 及鉴权](/docs/base-url-and-authentication)。

* Access Key 鉴权，请在 [Access Key 管理](https://console.volcengine.com/iam/keymanage) 页面，获取 Access Key。本接口仅支持 Access Key 鉴权。

---

<span id="request-parameters"></span>
## 请求参数

### Body 参数

**ModelReference** `object` `必选` | 接入模型配置

接入点接入的模型引用。二选一指定：基础模型（*FoundationModel*）或定制模型（*CustomModelId*）。

**CustomModelId** `string` | 定制模型 ID

`ModelReference.CustomModelId`

定制模型 ID，以 `cm-` 开头，与 *FoundationModel* 二选一。

**FoundationModel** `object` | 基础模型引用

`ModelReference.FoundationModel`

基础模型引用，与 *CustomModelId* 二选一。指定基础模型时必填该字段。

**ModelVersion** `string` `必选` | 基础模型版本

`ModelReference.FoundationModel.ModelVersion`

基础模型版本号，可通过 *ListFoundationModels* 接口查询。

**Name** `string` `必选` | 基础模型名称

`ModelReference.FoundationModel.Name`

基础模型名称，可通过 *ListFoundationModels* 接口查询。

**Name** `string` `必选` | 接入点名称

接入点名称，用于在控制台与列表接口中标识该接入点。建议在名称中体现模型与用途，便于识别。

**AgenticStrategy** `object` | Agent 策略

Agent 策略配置，包含 Skill 与上下文压缩等子项

**AgenticSkill** `object` `必选` | Agent 技能配置。

`AgenticStrategy.AgenticSkill`

**AgenticSkillInfos** `object[]` `必选` | 技能实例列表

`AgenticStrategy.AgenticSkill.AgenticSkillInfos`

Agent 技能实例列表

**ID** `string` `必选` | Agent 技能 ID。

`AgenticStrategy.AgenticSkill.AgenticSkillInfos.ID`

**Type** `string` `必选` | 技能类型

`AgenticStrategy.AgenticSkill.AgenticSkillInfos.Type`

Agent 技能类型。取值 `Custom`(自定义)、`Sharing`(共享)

**Version** `string` `必选` | Agent 技能版本号。

`AgenticStrategy.AgenticSkill.AgenticSkillInfos.Version`

**VersionID** `string` | Agent 技能版本 ID。

`AgenticStrategy.AgenticSkill.AgenticSkillInfos.VersionID`

**Enabled** `number` `必选` | 启用 Agent 技能

`AgenticStrategy.AgenticSkill.Enabled`

是否启用 Agent 技能

**Mode** `string` `必选` | 技能模式

`AgenticStrategy.AgenticSkill.Mode`

Agent 技能模式。取值 `Auto`(自动)、`Custom`(自定义)

**AgenticContext** `object` | Agent 上下文配置。

`AgenticStrategy.AgenticContext`

**AgenticContextTosLocation** `object` `必选` | Agent 上下文存储的 TOS 位置。

`AgenticStrategy.AgenticContext.AgenticContextTosLocation`

**BucketName** `string` `必选` | TOS

`AgenticStrategy.AgenticContext.AgenticContextTosLocation.BucketName`

TOS 桶名称。在创建和选择 TOS 桶时请注意，当前火山方舟只支持华北 2-北京 地域（region: cn-beijing）的存储桶

**ObjectKey** `string` `必选` | TOS 对象路径。

`AgenticStrategy.AgenticContext.AgenticContextTosLocation.ObjectKey`

**CompressionEnabled** `number` `必选` | 启用上下文压缩

`AgenticStrategy.AgenticContext.CompressionEnabled`

是否启用上下文压缩

**AllowDataCollected** `boolean` | 允许数据采集

是否允许采集调用数据用于模型训练或数据回流

**BatchOnly** `boolean` `默认值 false` | 仅批量推理

是否为批量推理。取值 `true` 表示接入点为批量推理 ep；`false` 表示实时推理。

**ContentGeneration** `object` | 生图/生视频配置

生图 / 生视频模型的特化配置，用于设置并发与每分钟任务数上限。

**ConcurrentRequests** `number` | 并发请求数

`ContentGeneration.ConcurrentRequests`

并发请求数上限。默认按模型缺省值。

**CreateTaskRpm** `number` | 每分钟任务数

`ContentGeneration.CreateTaskRpm`

每分钟创建任务数上限。默认按模型缺省值。

**DataDelivery** `boolean` `默认值 false` | 数据回流

是否开启推理数据回流。取值 `true` 表示开启，接入点的请求与响应可被回流用于数据采集；`false` 表示关闭。

**DedicatedToDynamicPTU** `boolean` | 动态模型单元

是否绑定动态模型单元（Dynamic PTU）

**DedicatedToPTU** `boolean` `默认值 false` | 独占模型单元

是否将该接入点专用于绑定的模型单元（PTU）。取值 `true` 表示接入点流量将独占绑定的模型单元；`false` 表示接入点与模型单元非独占。

**DeploymentType** `string` | 部署类型

部署类型。取值 `global`(全球部署)、`regional`(区域部署)

**Description** `string` | 接入点描述

接入点的描述信息，便于在控制台或列表中区分用途。默认为空。

**Domain** `string` `默认值 Ark` | 接入点类型

接入点类型。取值 `Ark`（方舟接入点）、`Mlp`（MLP 接入点）、`Foundry`（推理代工）、`All`（所有场景）。

**DryRun** `boolean` `默认值 false` | 预检模式

是否仅进行预检。取值 `true` 表示仅校验请求合法性，不实际创建接入点；`false` 表示正式执行创建。

**Fallback** `object` | 降级配置

降级配置。主模型不可用时按候选模型顺序回退

**NeedFallback** `number` `必选` | 是否启用降级。

`Fallback.NeedFallback`

**CandidateModels** `object[]` | 候选基础模型列表。

`Fallback.CandidateModels`

候选基础模型列表，按顺序回退

**ModelVersion** `string` `必选` | 基础模型版本

`Fallback.CandidateModels.ModelVersion`

基础模型版本号，可通过 *ListFoundationModels* 接口查询。

**Name** `string` `必选` | 基础模型名称

`Fallback.CandidateModels.Name`

基础模型名称，可通过 *ListFoundationModels* 接口查询。

**ConfigurationId** `string` | 模型配置 ID

`Fallback.CandidateModels.ConfigurationId`

模型配置 ID。默认为空，使用模型默认配置。

**InferenceFoundry** `object` | 推理工厂配置

推理工厂（Inference Foundry）配置，用于自定义推理性能档位

**InferenceFoundryPerformance** `object` | 性能档位配置

`InferenceFoundry.InferenceFoundryPerformance`

推理工厂性能档位配置

**Tier** `integer` | 推理性能档位编号。

`InferenceFoundry.InferenceFoundryPerformance.Tier`

**Tpm** `integer` | 该档位每分钟 token 数。

`InferenceFoundry.InferenceFoundryPerformance.Tpm`

**IntelligentRouter** `object` | 智能路由

智能路由配置，用于在多个候选模型间按策略分发请求

**Mode** `string` `必选` | 路由模式

`IntelligentRouter.Mode`

路由模式。取值 `Automatic`(自动)、`CandidateSet`(候选集合)、`Ordered`(按顺序)

**Strategy** `string` `必选` | 路由策略

`IntelligentRouter.Strategy`

路由策略。取值 `EffectFirst`(效果优先)、`CostFirst`(成本优先)、`Balanced`(均衡)

**CandidateModels** `object[]` | 候选模型列表。

`IntelligentRouter.CandidateModels`

**CustomModelId** `string` | 定制模型 ID

`IntelligentRouter.CandidateModels.CustomModelId`

定制模型 ID，以 `cm-` 开头，与 *FoundationModel* 二选一。

**FoundationModel** `object` | 基础模型引用

`IntelligentRouter.CandidateModels.FoundationModel`

基础模型引用，与 *CustomModelId* 二选一。指定基础模型时必填该字段。

**ModelVersion** `string` `必选` | 基础模型版本

`IntelligentRouter.CandidateModels.FoundationModel.ModelVersion`

基础模型版本号，可通过 *ListFoundationModels* 接口查询。

**Name** `string` `必选` | 基础模型名称

`IntelligentRouter.CandidateModels.FoundationModel.Name`

基础模型名称，可通过 *ListFoundationModels* 接口查询。

**IsAgentic** `boolean` | 启用 Agent 化

是否启用 Agent 化能力(接入点可作为 Agent 调用)

**IsIntelligent** `boolean` | 启用智能路由

是否启用智能路由能力

**LimitCoefficient** `object` | 限流系数

限流系数配置，用于调整接入点限流策略

**NeedLimitCoefficient** `number` `必选` | 是否启用限流系数。

`LimitCoefficient.NeedLimitCoefficient`

**ModelUnitId** `string` | 模型单元 ID

模型单元（PTU）ID，以 `ptu-` 开头。指定后接入点为预付费模式并绑定该模型单元；不传则为后付费模式。

**Moderation** `object` | 内容安全护栏

内容护栏方案。*Strategy* 必填；仅当 *Strategy* 为 `Customized` 时填写 *CustomizedModerationInfos*。

**Strategy** `string` `必选` | 内容安全护栏方案

`Moderation.Strategy`

内容安全护栏方案。取值: 
- `Default`（默认）: 更低延迟，广泛覆盖内容安全通用需求
- `Basic`：基本方案（公测中）。支持在接口响应中提供命中的风险分类，暂时只包含严重违规和激进行为两类风险。
- `Skip`：跳过内容审核。
- `Customized`：自定义内容审核。

> **注意**
>
> 流式调用场景下不建议使用 `Basic`，否则可能导致响应延迟升高。 

**NeedWatermark** `boolean` | 启用水印

生成内容是否需要添加水印。启用后需同时填写 *WatermarkInfo* 提供水印主体信息

**ProjectName** `string` `默认值 default` | 项目名称

资源所属的项目名称。若资源不在默认项目（`default`）中，需填写实际项目名称。

**RateLimit** `object` | 限流配置

接入点限流配置，为空时使用模型默认限流。其中 *Rpm* 与 *Tpm* 必填，*Ipm* 与 *FastTpm* 按需填写。

**Rpm** `integer` `必选` | 每分钟请求数

`RateLimit.Rpm`

每分钟请求数上限（Requests Per Minute）。

**Tpm** `integer` `必选` | 每分钟请求 token 数

`RateLimit.Tpm`

每分钟 token 数上限（Tokens Per Minute）。

**Ipm** `integer` | 每分钟生成图片数

`RateLimit.Ipm`

每分钟生成图片数上限（Images Per Minute）。仅生图模型有效。

**ServiceInfo** `object` | MLP 服务信息

MLP 服务信息。创建 MLP 接入点时，*ServiceInfo* 中的 *Id* 和 *Region* 必填

**Id** `string` | MLP 服务 ID

`ServiceInfo.Id`

MLP 推理服务 ID，以 `msrv-` 开头。

**ModelName** `string` | MLP 模型名称

`ServiceInfo.ModelName`

MLP 服务对应的模型名称。默认从 MLP 服务定义自动解析。

**Region** `string` | MLP 服务地域

`ServiceInfo.Region`

MLP 推理服务所在区域，如 `cn-beijing`、`ap-southeast-1`。

**ServiceName** `string` | MLP 服务名称

`ServiceInfo.ServiceName`

MLP 服务名称。默认从 MLP 服务定义自动解析。

**Tags** `object[]` | 标签列表

接入点绑定的标签列表，用于资源分类与检索。每个标签由 *Key*（必填）与 *Value*（可选）组成。

**Key** `string` `必选` | 标签键

`Tags.Key`

标签键，长度 1~64 字符。

**Value** `string` `必选` | 标签值

`Tags.Value`

标签值，长度不超过 256 字符。

**WatermarkInfo** `object` | 水印主体信息

水印主体信息。当 *NeedWatermark* 为 `true` 时填写

**SocialUnifiedCreditCode** `string` `必选` | 统一社会信用代码。

`WatermarkInfo.SocialUnifiedCreditCode`

**SubjectName** `string` `必选` | 水印主体名称。

`WatermarkInfo.SubjectName`

**IsContentDissemination** `number` | 是否允许内容传播。

`WatermarkInfo.IsContentDissemination`

## 响应参数

**Id** `string` | 接入点 ID

创建成功的推理接入点 ID，以 `ep-` 开头。可用于后续 *GetEndpoint*、*UpdateEndpoint*、*DeleteEndpoint* 等接口的 *Id* 入参。


## 代码示例

## 默认

### cURL

#### Request

```bash
curl 'https://ark.cn-beijing.volcengineapi.com/?Action=CreateEndpoint&Version=2024-01-01' \
  -H 'Content-Type: application/json' \
  -H 'X-Date: <X-Date>' \
  -H 'X-Content-Sha256: <X-Content-Sha256>' \
  -H 'Authorization: HMAC-SHA256 Credential=<AK>/<X-Date>/cn-beijing/ark/request, SignedHeaders=content-type;host;x-content-sha256;x-date, Signature=<Signature>' \
  -d '{
  "Name": "my-endpoint",
  "Description": "My model inference endpoint",
  "ModelReference": {
    "FoundationModel": {
      "Name": "doubao-seed-2-1-pro",
      "ModelVersion": "260628"
    }
  }
}
'
```

#### Response

```
{
  "ResponseMetadata": {
    "RequestId": "20240514212750152186163065FE5A2A",
    "Action": "CreateEndpoint",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "ep-20240514212750-a3f8k"
  }
}
```