Create an embedding backend through the root-level API

Save an embedding model backend configuration and obtain a new backend ID.

POST https://api.moi.matrixorigin.cn/v5/embedding/backends

Before you call this API

Set BASE_URL to the product API prefix https://api.moi.matrixorigin.cn/v5. For private deployments, use the corresponding product API URL.

Configure identity, Workspace, and object permissions in the same environment.

Request

curl --request POST \
  "$BASE_URL/embedding/backends" \
  --header "X-API-Key: $MOI_KEY" \
  --header "X-Workspace-ID: $WORKSPACE_ID" \
  --header "Content-Type: application/json" \
  --data-raw '{"name":"临时后端","type":"OPENAI","api_key":"provider-key-example","models":["bge-m3"],"address":"https://provider.example.invalid/v1"}'

Parameter

Location

Type

Required

Description

X-Workspace-ID

Headers

string

Yes

Workspace ID in the same environment.

name

Body

string

Yes

Nonempty name after trimming surrounding whitespace.

type

Body

string

No

OPENAI/OLLAMA/VLLM/QIANWEN/DOUBAO/DEV_LLM/HTTP. Omitted/invalid values become OPENAI; Embedding rejects DEV_LLM.

api_key

Body

string

Conditionally required

Required for OPENAI/QIANWEN/DOUBAO; separate from MOI_KEY.

models

Body

array (strings)

Yes

At least one valid model name.

timeout_seconds

Body

integer

No

Positive timeout in seconds. Omitted/nonpositive values become 30.

reasoning_control_protocol

Body

string

No

LLM reasoning-control protocol; defaults to NONE. Embedding does not use reasoning control.

address

Body

string

No

A nonempty Embedding address can create an endpoint at the same time. LLM creation ignores the address and requires separate endpoint creation.

Requires Workspace model_backend.create. Save the returned id, then read details and endpoints. Configuration does not verify model connectivity or inference capability. Ordinary Workspace-level creation does not automatically create endpoints. DEV adapters have special internal behavior and are not a production integration method.

Successful response

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "id": 12,
    "name": "临时后端",
    "type": "OPENAI",
    "timeout_seconds": 30,
    "models": [
      "bge-m3"
    ],
    "created_at": 1794445200,
    "updated_at": 1794445200,
    "reasoning_control_protocol": "REASONING_CONTROL_NONE",
    "endpoints": [
      {
        "id": 21,
        "backend_id": 12,
        "address": "https://provider.example.invalid/v1",
        "status": "ONLINE",
        "created_at": 1794445200,
        "updated_at": 1794445200
      }
    ]
  }
}

HTTP 200。

Field

Type

Description

code

string

OK on success.

msg

string

OK on success.

data

object

Actual objects for this protocol.

Error responses

Errors and result confirmation distinguishes the two protocols. Parse omitted fields, SDK zero values, and empty HTTP responses separately. Confirm writes using the corresponding read operation.

Last updated on