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 |
|---|---|---|---|---|
|
Path |
string |
Yes |
Target workspace ID, matching X-Workspace-ID. |
|
Headers |
string |
Yes |
Workspace accessible to the current identity in the same environment. |
|
Body |
string |
Yes |
Business idempotency identifier for this creation, not the X-Request-ID header. |
|
Body |
string |
Yes |
Base model identifier readable by a Worker; creation only checks nonemptiness. |
|
Body |
array (strings) |
Yes |
Nonempty training run_id set, trimmed, deduplicated, and sorted. |
|
Body |
array (strings) |
Yes |
Nonempty validation run_id set, disjoint from the training set. |
|
Body |
object |
Yes |
Training configuration, including at least training_objective=tool_selector. |
|
Body |
string |
No |
Training compute instance. Omission or empty delegates to the shared Worker pool, which still requires an available training node. |
|
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 |
|---|---|---|
|
string |
OK on success. |
|
string |
Response information. |
|
object |
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}'