DocsICP FilingConsole
官方文档
首页

Character image training API details

更新时间：
复制 MD 格式
产品详情
我的收藏

Important

This document applies only to the China (Beijing) region. Use an API key from this region.

Character image training

Note

Supported realm/task: AIGC/facechain character portrait generation

You can train a model on an uploaded compressed image file to obtain a resource that represents the character in the images. You can then use this resource to generate character portraits.

Character image training is a prerequisite for generating character portraits. You must successfully train a model for a character and obtain a resource before you can generate portraits.

Model overview

Model name

Model description

facechain-finetune

Trains a model on uploaded images to create a character resource. This resource is used to generate character portraits.

HTTP API

Description

This is a model customization service that uses a time-consuming algorithm. Therefore, the API submits tasks using asynchronous calls. When you submit a job, the system returns a job ID that you can use to query or manage the task.

Prerequisites

  • Activate the service and obtain an API key. For more information, see Obtain an API key.

Note

A single account, which includes the root account and its RAM users, is subject to the following API limits: The task submission API is limited to 2 queries per second (QPS), and the number of concurrent tasks is limited to 1.

Prepare training data

You can prepare 1 to 10 images that contain faces and provide them to the training service in one of the following ways:

1. Store the images in a file service, such as Alibaba Cloud Object Storage Service (OSS), and generate an authorized access URL. (Recommended)

2. If you do not have a suitable file service, you can upload the images to the file management service for model customization. You can upload them individually or as a compressed ZIP file. After the upload, obtain the file_id.

File management

You can use the file service provided by DashScope to manage your training files. For more information about the API, see Alibaba Cloud Model Studio File Management API.

Step 1: Create a model customization task

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/fine-tunes

Replace {WorkspaceId} with your actual workspace ID.

Description

After you upload the training data, you can use the returned file_id to start a facechain model customization task.

Request parameters

Field

Type

Passing parameters

Required

Description

Example

Content-Type

String

Header

Yes

Request type: application/json

application/json

Authorization

String

Header

Yes

Your API key. Example: Bearer sk-xxxx

Bearer sk-xxxx

model

String

Body

Yes

The name of the foundation model to customize.

facechain-finetune

training_file_ids

Array

Body

Yes

A list of training set files. Use the training files that you prepared. URLs, file_ids, or a mix of both are supported.

[ "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/fine-tune/facechain/sample1.jpg","https://dashscope.oss-cn-beijing.aliyuncs.com/samples/fine-tune/facechain/sample2.jpg","https://dashscope.oss-cn-beijing.aliyuncs.com/samples/fine-tune/facechain/sample3.jpg"]
Response parameters

Field

Type

Description

Example

request_id

String

The unique ID of the request. Use this ID for troubleshooting and log tracking.

7574ee8f-38a3-4b1e-9280-11c33ab46e51

output.status

String

The status of the task. Valid values:

  • PENDING: The task is queued.

  • RUNNING: The task is in progress.

  • SUCCEEDED: The task is successful.

  • FAILED: The task failed.

  • CANCELED: The task is canceled.

  • UNKNOWN: The task does not exist or its status is unknown.

PENDING

output.job_id

String

The unique job ID generated by the system. Use this ID to query the customization training job.

ft-202509020951-f8bf

output.job_name

String

The name of the job. This is usually the same as the job ID.

ft-202509020951-f8bf

output.finetuned_output

String

The name of the model generated after customization. Use this model for subsequent inference calls.

facechain-finetune-ft-202509020951-f8bf

output.model

String

The identifier of the model used for the customization task.

facechain-finetune

output.base_model

String

The base model used for the customization task. This is the pre-trained model.

facechain-finetune

output.training_file_ids

Array

A list of input file URLs for model training. Multiple URLs are supported.

[ "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/fine-tune/facechain/sample1.jpg"]

output.validation_file_ids

Array

A list of file URLs for model validation. This can be empty if there is no validation set.

[]

output.hyper_parameters

Object

The hyperparameter settings used during training. By default, this is empty.

{}

output.training_type

String

The training method for the custom model. The value is fixed to: sft

sft

output.create_time

String

The time the task was created, in

YYYY-MM-DD HH:mm:ss

2025-09-02 09:51:02

output.workspace_id

String

The ID of the workspace to which the API key belongs.

llm-dmt509ikxxxxxx

output.user_identity

String

The unique user ID (UID) of the account that calls the API.

12402258xxxxxx

output.modifier

String

The UID of the user who last modified the task.

12402258xxxxxx

output.creator

String

The UID of the user who created the training job.

12402258xxxxxx

output.group

String

The logical group tag of the task.

facechain

output.model_name

String

The model name identifier for the task. This is usually the same as the job ID.

ft-202509020951-f8bf

output.max_output_cnt

Int

The maximum number of custom models that can be generated at the same time.

1

Sample request

Note

Replace <YOUR-DASHSCOPE-API-KEY> with your API key to run the code.

curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/fine-tunes' \
--header 'Authorization: Bearer <YOUR-DASHSCOPE-API-KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "model": "facechain-finetune",
    "training_file_ids": [
        "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/fine-tune/facechain/sample1.jpg"
    ]
}'

Sample response

{
    "request_id": "b6c9e77d-02a1-4a70-b127-xxxxxx",
    "output": {
        "job_id": "ft-202509020951-f8bf",
        "job_name": "ft-202509020951-f8bf",
        "status": "PENDING",
        "finetuned_output": "facechain-finetune-ft-202509020951-f8bf",
        "model": "facechain-finetune",
        "base_model": "facechain-finetune",
        "training_file_ids": [
            "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/fine-tune/facechain/sample1.jpg"
        ],
        "validation_file_ids": [],
        "hyper_parameters": {},
        "training_type": "sft",
        "create_time": "2025-09-02 09:51:02",
        "workspace_id": "llm-dmt509ikxxxxxx",
        "user_identity": "12402258xxxxxx",
        "modifier": "124022586xxxxxx",
        "creator": "1240225868xxxxxx",
        "group": "facechain",
        "model_name": "ft-202509020951-f8bf",
        "max_output_cnt": 1
    }
}

Step 2: Query the status of the customization task

Note

Replace <job_id> with the actual job_id to run the code.

GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/fine-tunes/<job_id>

Replace {WorkspaceId} with your actual workspace ID.

Description

You can query the status of a model customization task and retrieve the result after the task is complete. When the training job is successful, you can use the value of finetuned_output to make inference calls.

Request parameters

Field

Type

Passing Parameters

Required

Description

Example

Content-Type

String

Header

Yes

Request type: application/json

application/json

Authorization

String

Header

Yes

Your API key. Example: Bearer sk-xxxx

Bearer sk-xxxx

job_id

String

URL

Yes

The ID of the job to query.

ft-202509020951-f8bf
Response parameters

Field

Type

Description

Example

request_id

String

The unique ID of the request. Use this ID for troubleshooting and log tracking.

7574ee8f-38a3-4b1e-9280-11c33ab46e51

output.status

String

The status of the task. Valid values:

  • PENDING: The task is queued.

  • RUNNING: The task is in progress.

  • SUCCEEDED: The task is successful.

  • FAILED: The task failed.

  • CANCELED: The task is canceled.

  • UNKNOWN: The task does not exist or its status is unknown.

PENDING

output.job_id

String

The unique job ID generated by the system. Use this ID to query the customization training job.

ft-202509020951-f8bf

output.job_name

String

The name of the job. This is usually the same as the job ID.

ft-202509020951-f8bf

output.finetuned_output

String

The name of the model generated after customization. Use this model for subsequent inference calls.

facechain-finetune-ft-202509020951-f8bf

output.model

String

The identifier of the model used for the customization task.

facechain-finetune

output.base_model

String

The base model used for the customization task. This is the pre-trained model.

facechain-finetune

output.training_file_ids

Array

A list of input file URLs for model training. Multiple URLs are supported.

[ "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/fine-tune/facechain/sample1.jpg"]

output.validation_file_ids

Array

A list of file URLs for model validation. This can be empty if there is no validation set.

[]

output.hyper_parameters

Object

The hyperparameter settings used during training. By default, this is empty.

{}

output.training_type

String

The training method for the custom model. The value is fixed to: sft

sft

output.create_time

String

The time the task was created, in

YYYY-MM-DD HH:mm:ss

2025-09-02 09:51:02

output.workspace_id

String

The ID of the workspace to which the API key belongs.

llm-dmt509ikxxxxxx

output.user_identity

String

The unique user ID (UID) of the account that calls the API.

12402258xxxxxx

output.modifier

String

The UID of the user who last modified the task.

12402258xxxxxx

output.creator

String

The UID of the user who created the training job.

12402258xxxxxx

output.group

String

The logical group tag of the task.

facechain

output.usage

Int

The number of training runs. This is used for billing.

1

output.end_time

String

The end time of the task. The format is as follows:

YYYY-MM-DD HH:mm:ss

This is returned only after the task is complete (SUCCEEDED/FAILED).

2025-09-02 09:56:04

output.model_name

String

The model name identifier for the task. This is usually the same as the job ID.

ft-202509020951-f8bf

output.max_output_cnt

Int

The maximum number of custom models that can be generated at the same time.

1

output.output_cnt

Int

The number of custom models that have been generated.

This is returned only after the task is complete.

1

Sample request

Note

Replace <YOUR-DASHSCOPE-API-KEY> with your API key to run the code.

curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/fine-tunes/ft-202509020951-xxxx' \ 
--header 'Authorization: Bearer <YOUR-DASHSCOPE-API-KEY>' \
--header 'Content-Type: application/json'

Sample response

{
    "request_id": "fcfb99e6-7ae5-48b2-acca-xxxxxx",
    "output": {
        "job_id": "ft-202509020951-f8bf",
        "job_name": "ft-202509020951-f8bf",
        "status": "SUCCEEDED",
        "finetuned_output": "facechain-finetune-ft-202509020951-f8bf",
        "model": "facechain-finetune",
        "base_model": "facechain-finetune",
        "training_file_ids": [
            "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/fine-tune/facechain/sample1.jpg"
        ],
        "validation_file_ids": [],
        "hyper_parameters": {},
        "training_type": "sft",
        "create_time": "2025-09-02 09:51:02",
        "workspace_id": "llm-dmt509ikfxxxxxxx",
        "user_identity": "1240225868xxxxxx",
        "modifier": "1240225868xxxxxx",
        "creator": "1240225868xxxxxx",
        "end_time": "2025-09-02 09:56:04",
        "group": "facechain",
        "usage": 1,
        "model_name": "ft-202509020951-f8bf",
        "max_output_cnt": 1,
        "output_cnt": 1
    }
}

For more information about other operations, such as listing and deleting customization tasks, see Model Customization API details.

Status codes

For general status codes for the large model service platform, see Error messages.

This model also returns the following model-specific error codes:

HTTP status code

Error code (code)

Error message (message)

Description

Solution

400

InvalidParameter

Missing training files.

An input parameter is invalid. For example, a required parameter is missing or a parameter is in an incorrect format.

Check the error message and correct the parameter.

400

UnsupportedOperation

The finetuning job cannot be deleted because its status is successful, failed, or canceled.

The operation cannot be performed on the resource because of its current state.

Try the operation again after the resource enters a valid state.

404

NotFound

job {job_id} not found.

The resource to query or operate on does not exist.

Check whether the ID of the resource is correct.

409

Conflict

A model instance named xxxxx already exists. You must specify a suffix.

A deployment instance with the specified name already exists for the model. You must specify a unique suffix to distinguish the new instance.

Specify a unique suffix for the deployment.

429

Throttling

Too many finetuning jobs are running. Please try again later.

The number of concurrent resource creation requests has reached the platform limit.

Try again later.

500

InternalError

Internal server error!

An internal error occurred.

Record the request_id and submit a ticket to contact Alibaba Cloud.
Previous：Human Image Detection API DetailsNext：AI portrait generation API details