Fine-tuning

Manage the full fine-tuning lifecycle from the terminal: choose the create command for text, audio, image, or video, and manage jobs, checkpoints, and model compression.

Append --help to any command for full parameter details, e.g. bl finetune list --help. Command details on this page are verified against bl 2.5.1.

Choose a command by modality

Modality	Create command	Description
Text	`bl finetune text create`	Fine-tune text models with sft, sft-lora, dpo, dpo-lora, or cpt
Audio	`bl finetune audio create`	Fine-tune audio models
Image	`bl finetune image create`	Fine-tune image generation models
Video	`bl finetune video create`	Fine-tune video generation models

Text fine-tuning

bl finetune text create

Create a text model fine-tune job (sft | sft-lora | dpo | dpo-lora | cpt). Requires API Key authentication. Usage

bl finetune text create

Parameter	Type	Required	Description
`--base-model <model>`	string	yes	Base model to fine-tune (e.g. qwen3-8b; not the output model name)
`--datasets <ids\|paths>`	string	yes	Comma-separated dataset file IDs or local paths (.jsonl for text, .zip for audio/image/video). Local paths are uploaded (validated) first, then their file-ids are used.
`--validations <ids\|paths>`	string	no	Comma-separated validation dataset file IDs or local paths (auto-uploaded like --datasets).
`--model-name <name>`	string	no	Output model name (after training)
`--suffix <text>`	string	no	Output suffix appended by the platform (finetuned_output_suffix)
`--job-name <value>`	string	no	Training job display name (job_name)
`--priority <value>`	string	no	Requested scheduling priority; verify the service response
`--eval-steps <value>`	number	no	Validation interval in training steps
`--lora-alpha <value>`	number	no	LoRA scaling coefficient
`--lora-dropout <value>`	number	no	LoRA dropout probability
`--lora-rank <value>`	number	no	LoRA matrix rank
`--lr-scheduler-type <value>`	string	no	Learning rate scheduler supported by the selected model
`--save-strategy <value>`	string	no	Checkpoint saving strategy
`--save-total-limit <value>`	number	no	Maximum number of saved checkpoints
`--save-steps <value>`	number	no	Checkpoint saving interval for strategy=steps
`--split <value>`	number	no	Training fraction when no validation dataset is supplied
`--max-split-val-dataset-sample <value>`	number	no	Maximum automatically split validation samples
`--data-augmentation <value>`	string	no	Mix platform training data (true or false)
`--training-type <t>`	string	no	Training type: sft \| sft-lora \| dpo \| dpo-lora \| cpt (default: sft-lora). Mapping to the server happens at the interface boundary (e.g. sft-lora -> efficient_sft, dpo -> dpo_full).
`--n-epochs <n>`	number	no	Number of epochs (default: 3)
`--batch-size <n>`	number	no	Per-device batch size (clamped to [8, 1024]). Auto-set to 8 for small datasets (<100KB)
`--learning-rate <str>`	string	no	Learning rate as a string to preserve precision (e.g. "1.6e-5")
`--max-length <n>`	number	no	Max sequence length

Example: Create a text fine-tune job with base model and dataset

bl finetune text create --base-model qwen3-8b --datasets file-xxx

Training-type values use the <method> / <method>-lora convention: sft (full) | sft-lora (LoRA) | dpo (full) | dpo-lora (LoRA) | cpt. These map to the server's training_type at the interface boundary, so the rest of the CLI never sees the raw server strings.
Before submitting (non dry-run) the job, the model's training capability is checked via listFoundationModels (no console login required); an unsupported training type fails fast with the list the model actually supports.
n_epochs defaults to 3. Other hyper-parameters are platform defaults unless set.
Learning rate is forwarded as a string to avoid JSON-number precision loss.
Pre-submit gate: if the training dataset's sample count is not greater than batch_size, the job is rejected before upload or quota consumption (the platform would otherwise fail ~10 min in, after data processing).

Audio fine-tuning

bl finetune audio create

Create an audio TTS model fine-tune job (sft-lora). Requires API Key authentication. Usage

bl finetune audio create

Parameter	Type	Required	Description
`--base-model <model>`	string	yes	Base model to fine-tune (e.g. qwen3-8b; not the output model name)
`--datasets <ids\|paths>`	string	yes	Comma-separated dataset file IDs or local paths (.jsonl for text, .zip for audio/image/video). Local paths are uploaded (validated) first, then their file-ids are used.
`--validations <ids\|paths>`	string	no	Comma-separated validation dataset file IDs or local paths (auto-uploaded like --datasets).
`--model-name <name>`	string	no	Output model name (after training)
`--suffix <text>`	string	no	Output suffix appended by the platform (finetuned_output_suffix)

Example: Create an audio TTS fine-tune job with base model and local zip dataset

bl finetune audio create --base-model cosyvoice-v3-flash --datasets ./audio.zip

Audio TTS training runs sft-lora (efficient_sft) with fixed CosyVoice hyper-parameter defaults; there are no training-type or hyper-parameter knobs to set.

Image fine-tuning

bl finetune image create

Create an image generation model fine-tune job (sft-lora). Requires API Key authentication. Usage

bl finetune image create

Parameter	Type	Required	Description
`--base-model <model>`	string	yes	Base model to fine-tune (e.g. qwen3-8b; not the output model name)
`--datasets <ids\|paths>`	string	yes	Comma-separated dataset file IDs or local paths (.jsonl for text, .zip for audio/image/video). Local paths are uploaded (validated) first, then their file-ids are used.
`--validations <ids\|paths>`	string	no	Comma-separated validation dataset file IDs or local paths (auto-uploaded like --datasets).
`--model-name <name>`	string	no	Output model name (after training)
`--suffix <text>`	string	no	Output suffix appended by the platform (finetuned_output_suffix)
`--generation-type <t2i\|i2i>`	string	no	Generation type: t2i (default) \| i2i. Sets generation_type/max_pixels. Required to train I2I from a file-id or with --dry-run (local data auto-detects input_img).
`--learning-rate <str>`	string	no	Learning rate as a string to preserve precision (e.g. "3e-5")

Example: Create an image generation fine-tune job with base model and local zip dataset

bl finetune image create --base-model wan2.7-image-pro --datasets ./images.zip

Image generation training runs sft-lora (efficient_sft) with fixed defaults; only --learning-rate is overridable. T2I vs I2I is declared with --generation-type (default t2i), which sets generation_type/max_pixels. For local data the type is auto-detected (records with input_img train I2I); pass --generation-type explicitly to train I2I from a file-id or in --dry-run.

Video fine-tuning

bl finetune video create

Create a video generation model fine-tune job (Wan i2v/kf2v, efficient_sft). Requires API Key authentication. Usage

bl finetune video create

Parameter	Type	Required	Description
`--base-model <model>`	string	yes	Base model to fine-tune (e.g. qwen3-8b; not the output model name)
`--datasets <ids\|paths>`	string	yes	Comma-separated dataset file IDs or local paths (.jsonl for text, .zip for audio/image/video). Local paths are uploaded (validated) first, then their file-ids are used.
`--validations <ids\|paths>`	string	no	Comma-separated validation dataset file IDs or local paths (auto-uploaded like --datasets).
`--model-name <name>`	string	no	Output model name (after training)
`--suffix <text>`	string	no	Output suffix appended by the platform (finetuned_output_suffix)
`--n-epochs <n>`	number	no	Training epochs (default: 50)
`--batch-size <n>`	number	no	Batch size (default: model-specific, 1 for wan2.7, 4 for wan2.5/2.2)
`--learning-rate <str>`	string	no	Learning rate as a string to preserve precision (default: "2e-5")

Example: Create a video generation fine-tune job with base model and dataset ID

bl finetune video create --base-model wan2.7-i2v --datasets file-xxx

Video generation training (Wan i2v/kf2v) runs efficient_sft with model-specific defaults: wan2.7 (batch_size=1, max_pixels=102400), wan2.5/2.2 (batch_size=4, max_pixels per model). Override with --batch-size/--n-epochs.
Datasets are .zip archives with data.jsonl + frame images + videos.
Recommended: ≥10 training samples, 20-100 for stable results.

Fine-tuning job management

bl finetune list

List fine-tune jobs. Requires API Key authentication. Usage

bl finetune list [--page <n>] [--page-size <n>] [--status <s>] [--base-model <model>]

Parameter	Type	Required	Description
`--page <n>`	number	no	Page number (default: 1)
`--page-size <n>`	number	no	Results per page (default: 10, max 100)
`--status <s>`	string	no	Filter by status (PENDING / RUNNING / SUCCEEDED / FAILED / CANCELED)
`--base-model <model>`	string	no	Filter by base model ID (server-side)

Example: List fine-tune jobs filtered by status

bl finetune list --status RUNNING

bl finetune get

Get details of a single fine-tune job. Requires API Key authentication. Usage

bl finetune get --job-id <id>

Parameter	Type	Required	Description
`--job-id <id>`	string	yes	Fine-tune job ID

Example: Get details of a specific fine-tune job by ID

bl finetune get --job-id ft-xxx

bl finetune watch

Probe a fine-tune job's status (default: single non-blocking fetch). Pass --follow to poll until terminal. Requires API Key authentication. Usage

bl finetune watch --job-id <id> [--follow] [--interval <sec>] [--poll-timeout <sec>]

Parameter	Type	Required	Description
`--job-id <id>`	string	yes	Fine-tune job ID
`--follow`	switch	no	Block and poll until a terminal state (the legacy behavior). Without it, a single status probe is performed and the command returns immediately.
`--interval <sec>`	number	no	Seconds between polls with --follow (default: ${DEFAULT_INTERVAL_SEC}, min: ${MIN_INTERVAL_SEC}). Ignored without --follow.
`--poll-timeout <sec>`	number	no	With --follow, stop polling after this many seconds (default: no limit). Ignored without --follow.

Example: Probe a fine-tune job's status once and return immediately

bl finetune watch --job-id ft-xxx                       # single probe, returns immediately

Default (no --follow) is a NON-BLOCKING single status probe: one fetch, then return immediately. This is the mode meant for agents / scripts — the caller owns the polling cadence, so the CLI never holds the terminal.
A terminal FAILED/CANCELED status raises a normal CLI error (non-zero exit); a SUCCEEDED or still-running status returns 0. With --follow, exceeding --poll-timeout raises a timeout error.
Use --follow for the blocking, human-terminal-follow experience; use the default mode when driving the loop yourself (e.g. from an agent).
For per-step training output (not status), use finetune logs.

bl finetune logs

Fetch training logs for a fine-tune job. Requires API Key authentication. Usage

bl finetune logs --job-id <id> [--page <n>] [--page-size <n>] [--search <keyword>] [--tail <n>]

Parameter	Type	Required	Description
`--job-id <id>`	string	yes	Fine-tune job ID
`--page <n>`	number	no	Page number (default: 1)
`--page-size <n>`	number	no	Lines per page (default: server-defined)
`--search <keyword>`	string	no	Case-insensitive substring filter. When set, all log pages are fetched and filtered client-side (--page is ignored).
`--tail <n>`	number	no	Keep only the last N entries. When set, all log pages are fetched and the trailing N are kept (--page is ignored).

Example: Fetch training logs for a fine-tune job by ID

bl finetune logs --job-id ft-xxx

bl finetune checkpoints

List checkpoints produced by a fine-tune job. Requires API Key authentication. Usage

bl finetune checkpoints --job-id <id>

Parameter	Type	Required	Description
`--job-id <id>`	string	yes	Fine-tune job ID

Example: List checkpoints from a fine-tune job by ID

bl finetune checkpoints --job-id ft-xxx

model_name (shown for SUCCEEDED checkpoints) is the direct input for deploy create --model-name.
Checkpoints expire ~15 days after creation; expire_time shows the deadline. Export or deploy before expiry.

bl finetune export

Publish a checkpoint as a deployable model. Requires API Key authentication. Usage

bl finetune export --job-id <id> --checkpoint <name> --model-name <name>

Parameter	Type	Required	Description
`--job-id <id>`	string	yes	Fine-tune job ID
`--checkpoint <name>`	string	yes	Checkpoint identifier from `finetune checkpoints`
`--model-name <name>`	string	yes	Deployable model name

Example: Publish a checkpoint as a deployable model with a name

bl finetune export --job-id ft-xxx --checkpoint ckpt-3 --model-name my-qwen-sft

Required before deploy <modality> create can target a checkpoint. The platform may auto-export the best checkpoint when a job reaches SUCCEEDED — explicit export is the canonical path for non-best checkpoints.

bl finetune cancel

Cancel a running fine-tune job. Requires API Key authentication. Usage

bl finetune cancel --job-id <id>

Parameter	Type	Required	Description
`--job-id <id>`	string	yes	Fine-tune job ID

Example: Cancel a fine-tune job by ID

bl finetune cancel --job-id ft-xxx

Only PENDING / RUNNING jobs can be cancelled. Completed / failed / already-cancelled jobs return a server-side error (passed through verbatim).

bl finetune delete

Delete a fine-tune job record. Requires API Key authentication. Usage

bl finetune delete --job-id <id>

Parameter	Type	Required	Description
`--job-id <id>`	string	yes	Fine-tune job ID
`--yes`	switch	no	Confirm this high-risk operation

This permanently deletes the specified fine-tune job record and cannot be undone.

Example: Delete a fine-tune job record by ID

bl finetune delete --job-id ft-xxx

Irreversible — the job record is permanently removed.
Cancel a RUNNING job first via finetune cancel — the platform refuses to delete jobs that are still in flight.

bl finetune capability

Query fine-tune training capability — by model (which training types it supports) or by training type (which models support it). No authentication required. Usage

bl finetune capability --base-model <m> | --training-type <t>

Parameter	Type	Required	Description
`--base-model <m>`	string	no	List training types supported by this base model.
`--training-type <t>`	string	no	List models supporting this training type: sft \| sft-lora \| dpo \| dpo-lora \| cpt.

Example: List training types supported by base model qwen3-8b

bl finetune capability --base-model qwen3-8b

Exactly one of --base-model / --training-type is required.
Training-type values use the <method> / <method>-lora convention: sft | sft-lora | dpo | dpo-lora | cpt. (cpt has no -lora variant server-side.)
Queries listFoundationModels, a public API — no console login needed.

bl finetune price

Estimate the training cost for a fine-tune job (token billing). Usage

bl finetune price --base-model <model> --datasets <ids> [--training-type <type>] [--n-epochs <n>]

Parameter	Type	Required	Description
`--base-model <model>`	string	yes	Base model to fine-tune (e.g. qwen3-8b; not the output model name)
`--datasets <ids>`	string	yes	Training dataset file IDs, comma-separated
`--training-type <type>`	string	no	Training type: sft \| dpo \| cpt (default: sft)
`--n-epochs <n>`	number	no	Number of training epochs (default: 3)

Example: Estimate training cost for datasets using base model qwen3-8b

bl finetune price --base-model qwen3-8b --datasets file-ft-xxx

Estimate only — the server computes token usage from the datasets; final cost is subject to the bill.
Covers token billing for sft / dpo / cpt. Training-unit (MTU) billing is not supported by this command.
Hyper-parameters other than --n-epochs are fixed at representative defaults for estimation.

Model compression

Model compression quantizes supported full-parameter fine-tuned models. Run templates to find a compatible template, then create a compression job. On success, the returned quantized_output can be passed to deploy text create --model-name. Model compression APIs are currently available only in the Beijing region.

bl finetune compress templates

List quantizable models and their compression templates. Requires API Key authentication. Usage

bl finetune compress templates [--model <model>]

Parameter	Type	Required	Description
`--model <model>`	string	no	Filter by custom model ID or base model name

Example: List supported models and templates

bl finetune compress templates

Only supported full-parameter fine-tuned models are returned. LoRA and already-quantized models are excluded.
Template IDs live in output.custom_models[].templates[].template_id. output.base_models only lists quantizable base model names and carries no templates.
An empty templates[].hyper_parameters array means the template exposes no tunable hyper-parameters; omit --hparam when creating the job.

bl finetune compress create

Create a model compression job. Requires API Key authentication. Usage

bl finetune compress create --model <model> --template-id <id> [flags]

Parameter	Type	Required	Description
`--model <model>`	string	yes	Source custom model ID
`--template-id <id>`	string	yes	Compression template ID
`--job-name <name>`	string	no	Unique job name (max 50 characters)
`--description <text>`	string	no	Job description (max 200 characters)
`--hparam <key=value>`	array	no	Hyper-parameter override; repeat for multiple values
`--calibration-files <file-id,...>`	string	no	Comma-separated calibration dataset file IDs
`--suffix <suffix>`	string	no	Output model suffix (1-8 lowercase letters or digits)

Example: Create a compression job with a specific template

bl finetune compress create --model qwen3.5-flash-2026-02-23-ft-xxx --template-id quant-flash-nvfp4-mlp-nomtp

bl finetune compress list

List model compression jobs. Requires API Key authentication. Usage

bl finetune compress list [filters] [--page <n>] [--page-size <n>]

Parameter	Type	Required	Description
`--status <status>`	string	no	Filter by job status
`--model <model>`	string	no	Filter by source model ID
`--template-id <id>`	string	no	Filter by template ID
`--quant-spec <spec>`	string	no	Filter by quantization specification
`--quant-method <method>`	string	no	Filter by quantization method
`--start-time <time>`	string	no	Filter jobs starting no earlier than this time
`--end-time <time>`	string	no	Filter jobs ending no later than this time
`--search <keyword>`	string	no	Search job ID or name
`--search-field <job_id\|job_name>`	string	no	Limit --search to job_id or job_name
`--sort-order <asc\|desc>`	string	no	Sort order by create_time (default: desc)
`--page <n>`	number	no	Page number (default: 1)
`--page-size <n>`	number	no	Results per page (default: 10, max: 100)

Example: List recently succeeded compression jobs

bl finetune compress list --status SUCCEEDED --page-size 20

bl finetune compress get

Get a compression job. Requires API Key authentication. Usage

bl finetune compress get --job-id <id>

Parameter	Type	Required	Description
`--job-id <id>`	string	yes	Compression job ID

Example: Get a specific compression job

bl finetune compress get --job-id quant-xxx

bl finetune compress watch

Probe or follow a compression job's status. Requires API Key authentication. Usage

bl finetune compress watch --job-id <id> [--follow] [--interval <sec>] [--poll-timeout <sec>]

Parameter	Type	Required	Description
`--job-id <id>`	string	yes	Compression job ID
`--follow`	switch	no	Poll until the job reaches a terminal state
`--interval <sec>`	number	no	Polling interval with --follow (default: 10, min: 1)
`--poll-timeout <sec>`	number	no	Stop polling after this many seconds

Example: Follow a compression job until it finishes

bl finetune compress watch --job-id quant-xxx --follow

Without --follow, the command performs one non-blocking status probe.
On success, quantized_output can be passed to deploy text create --model-name.

bl finetune compress logs

Get compression job logs. Requires API Key authentication. Usage

bl finetune compress logs --job-id <id> [--offset <n>] [--lines <n> | --tail <n>]

Parameter	Type	Required	Description
`--job-id <id>`	string	yes	Compression job ID
`--offset <n>`	number	no	Skip the first N lines (default: 0)
`--lines <n>`	number	no	Number of lines to read (default: 100, max: 1000)
`--tail <n>`	number	no	Read the last N log lines

Example: Read the last 20 lines of compression logs

bl finetune compress logs --job-id quant-xxx --tail 20

bl finetune compress cancel

Cancel a compression job. Requires API Key authentication. Usage

bl finetune compress cancel --job-id <id>

Parameter	Type	Required	Description
`--job-id <id>`	string	yes	Compression job ID

Example: Cancel a compression job

bl finetune compress cancel --job-id quant-xxx

Only PENDING, QUEUING, or RUNNING jobs can be cancelled.

bl finetune compress delete

Delete a compression job record. Requires API Key authentication. Usage

bl finetune compress delete --job-id <id>

Parameter	Type	Required	Description
`--job-id <id>`	string	yes	Compression job ID
`--yes`	switch	no	Confirm this high-risk operation

This permanently deletes the compression job record and cannot be undone.

Example: Preview deleting a compression job record

bl finetune compress delete --job-id quant-xxx --dry-run

Only terminal jobs can be deleted. Deleting a job record does not delete its quantized output model.

​Choose a command by modality

​Text fine-tuning

​bl finetune text create

​Audio fine-tuning

​bl finetune audio create

​Image fine-tuning

​bl finetune image create

​Video fine-tuning

​bl finetune video create

​Fine-tuning job management

​bl finetune list

​bl finetune get

​bl finetune watch

​bl finetune logs

​bl finetune checkpoints

​bl finetune export

​bl finetune cancel

​bl finetune delete

​bl finetune capability

​bl finetune price

​Model compression

​bl finetune compress templates

​bl finetune compress create

​bl finetune compress list

​bl finetune compress get

​bl finetune compress watch

​bl finetune compress logs

​bl finetune compress cancel

​bl finetune compress delete

Choose a command by modality

Text fine-tuning

bl finetune text create

Audio fine-tuning

bl finetune audio create

Image fine-tuning

bl finetune image create

Video fine-tuning

bl finetune video create

Fine-tuning job management

bl finetune list

bl finetune get

bl finetune watch

bl finetune logs

bl finetune checkpoints

bl finetune export

bl finetune cancel

bl finetune delete

bl finetune capability

bl finetune price

Model compression

bl finetune compress templates

bl finetune compress create

bl finetune compress list

bl finetune compress get

bl finetune compress watch

bl finetune compress logs

bl finetune compress cancel

bl finetune compress delete