Create a fine-tuning job

Save frozen training/validation sets, base model, and recipe. By default, HTTP 200 only means a pending job was saved, not that training started. launch=true continues scheduling without waiting for training completion.

POST https://api.moi.matrixorigin.cn/v5/workspaces/{id}/finetune-jobs

Before you call this API

Set BASE_URL to the product API prefix https://api.moi.matrixorigin.cn/v5; use the corresponding product API URL for a dedicated deployment.

Prepare identity, training inputs, and environment. Example IDs and results are fixed illustrative values. Replace models, run_id, request_id, and compute instances before calling.

Request

curl --request POST \
  "$BASE_URL/workspaces/$WORKSPACE_ID/finetune-jobs" \
  --header "X-API-Key: $MOI_KEY" \
  --header "X-Workspace-ID: $WORKSPACE_ID" \
  --header "Content-Type: application/json" \
  --data '{"request_id": "request-example", "base_model": "example/base-model", "train_run_ids": ["train-run-2", "train-run-1"], "holdout_run_ids": ["holdout-run-1"], "recipe": {"training_objective": "tool_selector"}, "compute_resource_id": "resource-example", "launch": false}'

Parameter

Location

Type

Required

Description

id

Path

string

Yes

Target workspace ID, matching X-Workspace-ID.

X-Workspace-ID

Headers

string

Yes

Workspace accessible to the current identity in the same environment.

request_id

Body

string

Yes

Business idempotency identifier for this creation, not the X-Request-ID header.

base_model

Body

string

Yes

Base model identifier readable by a Worker; creation only checks nonemptiness.

train_run_ids

Body

array (strings)

Yes

Nonempty training run_id set, trimmed, deduplicated, and sorted.

holdout_run_ids

Body

array (strings)

Yes

Nonempty validation run_id set, disjoint from the training set.

recipe

Body

object

Yes

Training configuration, including at least training_objective=tool_selector.

compute_resource_id

Body

string

No

Training compute instance. Omission or empty delegates to the shared Worker pool, which still requires an available training node.

launch

Body

boolean

No

Default false. true continues launching after saving; launch failure may leave a saved job.

Successful response

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "job_id": "ftj-example",
    "workspace_id": "workspace-example",
    "request_id": "request-example",
    "base_model": "example/base-model",
    "status": "pending",
    "train_run_ids": [
      "train-run-1",
      "train-run-2"
    ],
    "holdout_run_ids": [
      "holdout-run-1"
    ],
    "recipe": {
      "training_objective": "tool_selector"
    },
    "compute_resource_id": "resource-example",
    "created_at": "2026-11-12T01:00:00Z",
    "updated_at": "2026-11-12T01:00:00Z"
  }
}

Field

Type

Description

code

string

OK on success.

msg

string

Response information.

data

object

Job objects and omission rules.

Errors and next steps

Lifecycle and recovery distinguishes parameters, identity, conflicts, saved jobs, and actual training outcomes.

Request launch at creation

Keep original parameters. Setting launch=true continues launching after saving. On failure, retain request_id and training parameters, replay creation with launch=false to obtain the existing job_id, then verify with GET. Do not change identifiers to create duplicates. The following only illustrates the changed field; actual scheduling requires a confirmed training environment.

curl --request POST \
  "$BASE_URL/workspaces/$WORKSPACE_ID/finetune-jobs" \
  --header "X-API-Key: $MOI_KEY" \
  --header "X-Workspace-ID: $WORKSPACE_ID" \
  --header "Content-Type: application/json" \
  --data '{"request_id": "request-example", "base_model": "example/base-model", "train_run_ids": ["train-run-2", "train-run-1"], "holdout_run_ids": ["holdout-run-1"], "recipe": {"training_objective": "tool_selector"}, "compute_resource_id": "resource-example", "launch": true}'
Last updated on