Digital-human creation SDK integration

Installation

示例

# Install from npm
npm install nuwaai-sdk 

# Import
import { NuwaAISDK } from 'nuwaai-sdk';
const sdk=new NuwaAISDK()

# Or download the SDK package directly
# Download URL: https://nuwaai.com/demo/api-sdk/demo.api.tgz


# Download the SDK package directly
# Download URL: https://docs.nuwaai.com/sdk/NuwaAI-IOSSDK.zip
# Add libNuwaSDK.a and WebRTC.framework as dependencies in Xcode


import com.nuwaai.sdk.NuwaAIClient;
import com.nuwaai.sdk.NuwaAIConfig;

NuwaAIConfig config = NuwaAIConfig.builder()
    .apiKey("sk-xxxx")
    // .baseUrl("https://api.nuwaai.com")  // Optional; this is the default URL
    .build();
NuwaAIClient.init(config);

// Place nuwa-sdk.js in the Mini Program's utils directory (matching miniprogram/utils/nuwa-sdk.js in this repository)
const nuwa = require('../../utils/nuwa-sdk.js');
const sdk = nuwa.createClient({ secretKey: 'sk-xxxx' });
// Optional: sdk.baseUrl defaults to https://api.nuwaai.com

SDK demo

2. Global conventions

API call flow:

Step 1: Apply for an API key on the platform.
Step 2: Call the authentication endpoint to obtain a token with the API key.
Step 3: Call business endpoints with the token in the request header.

Base URL:

https://api.nuwaai.com

2.1 Request format

All endpoints use the following headers by default:

Header	Value
Content-Type	application/json
Authorization	Bearer <token>

2.2 Response format

{
  "code": 0,
  "msg": "success",
  "data": Object
}

code: 0 indicates success.
msg: Error or informational message.
data: Actual response payload.

3. Authentication API

3.1 Get a token with an API key

POST /web/apiKey/auth

Request example

示例

const res = await sdk.authByApiKey("sk-xxxx");
console.log(res.data); // token

import NuwaSDK

// Obtain an access token
NuwaAuthManager.getAccessTokenWithAPIKey("sk-xxxx") { accessToken, error in
    if let error = error {
        print("Failed to obtain token: \(error.localized Description)")
        return
    }
    
    if let accessToken = accessToken {
        print("Token obtained successfully: \(accessToken)")
        // Save the token for subsequent API calls
    }
}

#import <NuwaSDK/NuwaSDK.h>

// Obtain an access token
[NuwaAuthManager getAccessTokenWithAPIKey:@"sk-xxxx" completion:^(NSString * _Nullable accessToken, NSError * _Nullable error) {
    if (error) {
        NSLog(@"Failed to obtain token: %@", error.localized Description);
        return;
    }
    
    if (accessToken) {
        NSLog(@"Token obtained successfully: %@", accessToken);
        // Save the token for subsequent API calls
    }
}];

import com.nuwaai.sdk.NuwaAIClient;
import com.nuwaai.sdk.NuwaCallback;

// Configure NuwaAIConfig and call NuwaAIClient.init first (see "Installation")
NuwaAIClient.getInstance().authenticate(new NuwaCallback<String>() {
    @Override
    public void onSuccess(String token) {
        // The SDK stores the token in its internal TokenManager and automatically adds Authorization to subsequent requests
    }

    @Override
    public void onFailure(int code, String message) { }
});

const nuwa = require('../../utils/nuwa-sdk.js');
const sdk = nuwa.createClient({ secretKey: 'sk-xxxx' });
const token = await sdk.auth(); // On success, the token is stored internally and Authorization is added to subsequent requests
console.log(token);

Response example

{
  "code": 0,
  "msg": null,
  "data": "MnTjgFHRfslJov-PG9yNdKtGaxPicW06VKCRCt5-zuAh_YA0ECkp9cbFCR8kuK50EgSPFjtabTkAtR-1fNFLUoa-G7o3301t4zIem82yn2Sj5iglV-GDU3OA7pwaZff_"
}

Request parameter description

Parameter	Type	Required	Description
secretKey	String	Yes	API key

Response parameter description

Parameter	Type	Description
code	Integer	0: request succeeded; non-zero: request failed
msg	String	Response message
data	String	Token

4. File management API

4.1 File upload

POST /web/web-file/upload

Request example

示例

const uploadRes = await sdk.uploadFile(file);
console.log(uploadRes.data.url);

import NuwaSDK

// Initialize the API client
let apiClient = NuwaAPIClient(accessToken: "your-access-token")

// Upload a file
let fileURL = URL(fileURLWithPath: "/path/to/local.jpg")
apiClient.uploadFile(fileURL) { result, error in
    if let error = error {
        print("Upload failed: \(error.localized Description)")
        return
    }
    
    if let result = result, let url = result["url"] as? String {
        print("Upload succeeded. File URL: \(url)")
    }
}

#import <NuwaSDK/NuwaSDK.h>

// Initialize the API client
NuwaAPIClient *apiClient = [[NuwaAPIClient alloc] initWithAccessToken:@"your-access-token"];

// Upload a file
NSURL *fileURL = [NSURL fileURLWithPath:@"/path/to/local.jpg"];
[apiClient uploadFile:fileURL completion:^(NSDictionary * _Nullable result, NSError * _Nullable error) {
    if (error) {
        NSLog(@"Upload failed: %@", error.localized Description);
        return;
    }
    
    if (result) {
        NSString *url = result[@"url"];
        if (url) {
            NSLog(@"Upload succeeded. File URL: %@", url);
        }
    }
}];

import com.nuwaai.sdk.NuwaAIClient;
import com.nuwaai.sdk.NuwaCallback;
import com.nuwaai.sdk.model.FileUploadResult;

import java.io.File;

File file = new File("/path/to/local.jpg");
NuwaAIClient.getInstance().getFileManager().uploadFile(file, new NuwaCallback<FileUploadResult>() {
    @Override
    public void onSuccess(FileUploadResult data) {
        String url = data.getUrl();
    }

    @Override
    public void onFailure(int code, String message) { }
});

// filePath: the temporary path returned by wx.chooseMessageFile, chooseMedia, or a similar API
const res = await sdk.uploadFile(filePath);
console.log(res.url);

Response example

{
    "code": 0,
    "msg": null,
    "data": {
        "bucketName": "nuwa",
        "fileName": "78/202512/20251202/5c0b16e1c89d4ff9ae9b93f775a722f6.jpeg",
        "url": "/nuwa/78/202512/20251202/5c0b16e1c89d4ff9ae9b93f775a722f6.jpeg"
    }
}

Request parameter description

Name	Type	Required	Description
file	MultipartFile	Yes	File

Response parameter description

Name	Type	Description
code	Integer	0: success; non-zero: failure
msg	String	Description
data	Object	API response data
bucketName	String	Bucket name
fileName	String	OSS file name
url	String	OSS path

4.2 File deletion

DELETE /web/web-file/deleteFile

Request example

示例

await sdk.deleteFile("/nuwa/xx/xx.pptx");

import NuwaSDK

// Initialize the API client
let apiClient = NuwaAPIClient(accessToken: "your-access-token")

// Delete a file
apiClient.deleteFile("/nuwa/xx/xx.pptx") { success, error in
    if let error = error {
        print("Deletion failed: \(error.localized Description)")
        return
    }
    
    if success {
        print("Deleted successfully")
    }
}

#import <NuwaSDK/NuwaSDK.h>

// Initialize the API client
NuwaAPIClient *apiClient = [[NuwaAPIClient alloc] initWithAccessToken:@"your-access-token"];

// Delete a file
[apiClient deleteFile:@"/nuwa/xx/xx.pptx" completion:^(BOOL success, NSError * _Nullable error) {
    if (error) {
        NSLog(@"Deletion failed: %@", error.localized Description);
        return;
    }
    
    if (success) {
        NSLog(@"Deleted successfully");
    }
}];

import com.nuwaai.sdk.NuwaAIClient;
import com.nuwaai.sdk.NuwaCallback;

NuwaAIClient.getInstance().getFileManager().deleteFile("/nuwa/xx/xx.pptx", new NuwaCallback<Boolean>() {
    @Override
    public void onSuccess(Boolean data) { }

    @Override
    public void onFailure(int code, String message) { }
});

await sdk.deleteFile('/nuwa/xx/xx.pptx');

Response example

 {
  "code": 0,
  "msg": null,
  "data": true
}

Request parameter description

Name	Type	Required	Description
filePath	String	Yes	File path in OSS

Response parameter description

Name	Type	Description
code	Integer	0: success; non-zero: failure
msg	String	Description
data	Boolean	true : success,false:failure

4.3 Get a file preview URL

GET /web/document/getDownPreSignedUrl

Request example

示例

const previewRes = await sdk.getDownPreSignedUrl("134/figure/demo.mp4");
console.log(previewRes.data);

import NuwaSDK

// Initialize the API client
let apiClient = NuwaAPIClient(accessToken: "your-access-token")

// Obtain the file preview URL
apiClient.getPreviewURLForFilename("134/figure/demo.mp4") { previewURL, error in
    if let error = error {
        print("Failed to obtain preview URL: \(error.localized Description)")
        return
    }
    
    if let previewURL = previewURL {
        print("Preview URL: \(previewURL)")
    }
}

#import <NuwaSDK/NuwaSDK.h>

// Initialize the API client
NuwaAPIClient *apiClient = [[NuwaAPIClient alloc] initWithAccessToken:@"your-access-token"];

// Obtain the file preview URL
[apiClient getPreviewURLForFilename:@"134/figure/demo.mp4" completion:^(NSString * _Nullable previewURL, NSError * _Nullable error) {
    if (error) {
        NSLog(@"Failed to obtain preview URL: %@", error.localized Description);
        return;
    }
    
    if (previewURL) {
        NSLog(@"Preview URL: %@", previewURL);
    }
}];

import com.nuwaai.sdk.NuwaAIClient;
import com.nuwaai.sdk.NuwaCallback;

NuwaAIClient.getInstance().getFileManager().getPreSignedUrl("134/figure/demo.mp4", new NuwaCallback<String>() {
    @Override
    public void onSuccess(String url) { }

    @Override
    public void onFailure(int code, String message) { }
});

const url = await sdk.getDownPreSignedUrl('134/figure/demo.mp4');
console.log(url);

Response example

{
  "code": 0,
  "msg": null,
  "data": "https://nuwa-ai.oss-cn-shenzhen.aliyuncs.com/134/figure/1947499417004638210/be367e3322de4b0eb857aaa62ddd3e46.mp4?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20251202T025318Z&X-Amz-SignedHeaders=host&X-Amz-Expires=518399&X-Amz-Credential=YHenriLQRiAqWFbmnZgQ%2F20251202%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=93e949dd325710726103601e661b9bb8b517abcc830fc783388fcd067ecee586"
}

Request parameter description

Name	Type	Required	Description
filename	String	Yes	OSS file name

Response parameter description

Name	Type	Description
code	Integer	0: success; non-zero: failure
msg	String	Description
data	String	File URL

4.4 File download

GET /web/web-file/download

Request example

示例

const resp = await sdk.downloadFile("/nuwa/xx/demo.pptx");
const blob = await resp.blob();

import NuwaSDK

// Initialize the API client
let apiClient = NuwaAPIClient(accessToken: "your-access-token")

// Download a file
apiClient.downloadFile("/nuwa/xx/demo.pptx") { data, error in
    if let error = error {
        print("Download failed: \(error.localized Description)")
        return
    }
    
    if let data = data {
        // Process the downloaded data, for example by saving it to a local file
        let documentsDirectory = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first!
        let fileURL = documentsDirectory.appendingPathComponent("demo.pptx")
        
        do {
            try data.write(to: fileURL)
            print("File saved successfully: \(fileURL.path)")
        } catch {
            print("Failed to save file: \(error.localized Description)")
        }
    }
}

#import <NuwaSDK/NuwaSDK.h>

// Initialize the API client
NuwaAPIClient *apiClient = [[NuwaAPIClient alloc] initWithAccessToken:@"your-access-token"];

// Download a file
[apiClient downloadFile:@"/nuwa/xx/demo.pptx" completion:^(NSData * _Nullable data, NSError * _Nullable error) {
    if (error) {
        NSLog(@"Download failed: %@", error.localized Description);
        return;
    }
    
    if (data) {
        // Process the downloaded data, for example by saving it to a local file
        NSArray *paths = NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES);
        NSString *documentsDirectory = [paths objectAtIndex:0];
        NSString *filePath = [documentsDirectory stringByAppendingPathComponent:@"demo.pptx"];
        
        BOOL success = [data writeToFile:filePath atomically:YES];
        if (success) {
            NSLog(@"File saved successfully: %@", filePath);
        } else {
            NSLog(@"Failed to save file");
        }
    }
}];

import com.nuwaai.sdk.NuwaAIClient;
import com.nuwaai.sdk.NuwaCallback;

import okhttp3.ResponseBody;

NuwaAIClient.getInstance().getFileManager().downloadFile("/nuwa/xx/demo.pptx", new NuwaCallback<ResponseBody>() {
    @Override
    public void onSuccess(ResponseBody body) {
        // Write body.byteStream() to a local file, for example
    }

    @Override
    public void onFailure(int code, String message) { }
});

const tempFilePath = await sdk.downloadFile('/nuwa/xx/demo.pptx');
// Add api.nuwaai.com to the downloadFile domain allowlist in the Mini Program console

Response example

Request parameter description

Name	Type	Required	Description
url	String	Yes	OSS file URL

5. Image/video generation API

5.1 Text-to-image

POST /web/model/submitTask

Request example

示例

await sdk.textToImage({
  forwardPrompt: "生成一张在海边散步的美女图片",
  bizId: 1995841869673639938,
  from: "1",
  aspectRatio: "16:9",
  model: "doubao-seedream-4-5-251128"
});

import NuwaSDK

// Initialize the API client
let apiClient = NuwaAPIClient(accessToken: "your-access-token")

// Generate an image from text
apiClient.textToImageWithForwardPrompt("生成一张在海边散步的美女图片",
                                      bizId: "1995841869673639938",
                                      from: "1",
                                      aspectRatio: "16:9",
                                      model: "doubao-seedream-4-5-251128") { taskId, error in
    if let error = error {
        print("Text-to-image generation failed: \(error.localized Description)")
        return
    }
    
    if let taskId = taskId {
        print("Text-to-image task submitted. Task ID: \(taskId)")
        // Use taskId to query task progress
    }
}

#import <NuwaSDK/NuwaSDK.h>

// Initialize the API client
NuwaAPIClient *apiClient = [[NuwaAPIClient alloc] initWithAccessToken:@"your-access-token"];

// Generate an image from text
[apiClient textToImageWithForwardPrompt:@"生成一张在海边散步的美女图片"
                                 bizId:@"1995841869673639938"
                                  from:@"1"
                           aspectRatio:@"16:9"
                                 model:@"doubao-seedream-4-5-251128"
                            completion:^(NSString * _Nullable taskId, NSError * _Nullable error) {
    if (error) {
        NSLog(@"Text-to-image generation failed: %@", error.localized Description);
        return;
    }
    
    if (taskId) {
        NSLog(@"Text-to-image task submitted. Task ID: %@", taskId);
        // Use taskId to query task progress
    }
}];

import com.nuwaai.sdk.NuwaAIClient;
import com.nuwaai.sdk.NuwaCallback;

NuwaAIClient.getInstance().getModelManager().text2Image(
    "生成一张在海边散步的美女图片",
    1995841869673639938L,
    "1",
    "doubao-seedream-4-5-251128",
    "16:9",
    new NuwaCallback<String>() {
        @Override
        public void onSuccess(String requestId) { }

        @Override
        public void onFailure(int code, String message) { }
    });

await sdk.submitTask({
  type: 'text2img',
  forwardPrompt: '生成一张在海边散步的美女图片',
  bizId: 1995841869673639938,
  from: '1',
  aspectRatio: '16:9',
  model: 'doubao-seedream-4-5-251128'
});

Response example

{
  "code": 0,
  "msg": null,
  "data": "0be340e8bfd4405fab420a02ac3150d1"
}

Request parameter description

Name	Type	Required	Description
type	String	Yes	Type(img2img:Description,text2img:Description,img2video:Description)
forwardPrompt	String	Yes	Forward prompt
bizId	Long	Yes	Figure/talent ID
from	String	Yes	Description(1:figure Description,2:talent Description,3:Create digital human,4:Description figure Description,5:Description talent Description)
model	String	Yes	Model ID(Description：gemini-3-pro-image-preview,gemini-3.1-flash-image-preview,doubao-seedream-4-0-250828,doubao-seedream-4-5-251128,doubao-seedream-5-0-260128)
aspectRatio	String	No	Description(Description：16:9,9:16,Description：16:9)

Response parameter description

Name	Type	Description
code	Integer	0: success; non-zero: failure
msg	String	Description
data	String	request ID

5.2 Image-to-image

POST /web/model/submitTask

Request example

示例

await sdk.imageToImage({
  forwardPrompt: "请保持风格生成新图",
  bizId: 1995841869673639938,
  from: "1",
  path: "/nuwa/xx/ref.jpg"
});

import NuwaSDK

// Initialize the API client
let apiClient = NuwaAPIClient(accessToken: "your-access-token")

// Generate an image from another image
apiClient.imageToImageWithForwardPrompt("请保持风格生成新图",
                                       imageURL: "/nuwa/xx/ref.jpg",
                                       bizId: "1995841869673639938",
                                       from: "1",
                                       aspectRatio: nil,
                                       model: "doubao-seedream-4-5-251128") { taskId, error in
    if let error = error {
        print("Image-to-image generation failed: \(error.localized Description)")
        return
    }
    
    if let taskId = taskId {
        print("Image-to-image task submitted. Task ID: \(taskId)")
        // Use taskId to query task progress
    }
}

#import <NuwaSDK/NuwaSDK.h>

// Initialize the API client
NuwaAPIClient *apiClient = [[NuwaAPIClient alloc] initWithAccessToken:@"your-access-token"];

// Generate an image from another image
[apiClient imageToImageWithForwardPrompt:@"请保持风格生成新图"
                                imageURL:@"/nuwa/xx/ref.jpg"
                                   bizId:@"1995841869673639938"
                                    from:@"1"
                             aspectRatio:nil
                                   model:@"doubao-seedream-4-5-251128"
                              completion:^(NSString * _Nullable taskId, NSError * _Nullable error) {
    if (error) {
        NSLog(@"Image-to-image generation failed: %@", error.localized Description);
        return;
    }
    
    if (taskId) {
        NSLog(@"Image-to-image task submitted. Task ID: %@", taskId);
        // Use taskId to query task progress
    }
}];

import com.nuwaai.sdk.NuwaAIClient;
import com.nuwaai.sdk.NuwaCallback;

NuwaAIClient.getInstance().getModelManager().img2Image(
    "请保持风格生成新图",
    1995841869673639938L,
    "1",
    "doubao-seedream-4-5-251128",
    null,
    "/nuwa/xx/ref.jpg",
    new NuwaCallback<String>() {
        @Override
        public void onSuccess(String requestId) { }

        @Override
        public void onFailure(int code, String message) { }
    });

await sdk.submitTask({
  type: 'img2img',
  forwardPrompt: '请保持风格生成新图',
  bizId: 1995841869673639938,
  from: '1',
  model: 'doubao-seedream-4-5-251128',
  path: '/nuwa/xx/ref.jpg'
});

Response example

{
  "code": 0,
  "msg": null,
  "data": "0be340e8bfd4405fab420a02ac3150d1"
}

Request parameter description

Name	Type	Required	Description
type	String	Yes	Type(img2img:Description,text2img:Description,img2video:Description)
forwardPrompt	String	Yes	Forward prompt
bizId	Long	Yes	Figure/talent ID
from	String	Yes	Description(1:figure Description,2:talent Description,3:Create digital human,4:Description figure Description,5:Description talent Description)
model	String	Yes	Model ID(Description：gemini-3-pro-image-preview,gemini-3.1-flash-image-preview,doubao-seedream-4-0-250828,doubao-seedream-4-5-251128,doubao-seedream-5-0-260128)
aspectRatio	String	No	Description(Description：16:9,9:16,Description：16:9)
path	String	Yes	OssChinese DescriptionURL

Response parameter description

Name	Type	Description
code	Integer	0: success; non-zero: failure
msg	String	Description
data	String	request ID

5.3 Image-to-video

GET /api/order/descriptionecondsid=557899

Request example

示例

await sdk.imageToVideo({
  forwardPrompt: "人物轻微走动",
  bizId: 1995841869673639938,
  from: "1",
  videoTime: 5,
  path: "/nuwa/xx/ref.jpg"
});

import NuwaSDK

// Initialize the API client
let apiClient = NuwaAPIClient(accessToken: "your-access-token")

// Generate a video from an image
apiClient.imageToVideoWithForwardPrompt("人物轻微走动",
                                       imageURL: "/nuwa/xx/ref.jpg",
                                       bizId: "1995841869673639938",
                                       from: "1",
                                       videoTime: 5) { taskId, error in
    if let error = error {
        print("Image-to-video generation failed: \(error.localized Description)")
        return
    }
    
    if let taskId = taskId {
        print("Image-to-video task submitted. Task ID: \(taskId)")
        // Use taskId to query task progress
    }
}

#import <NuwaSDK/NuwaSDK.h>

// Initialize the API client
NuwaAPIClient *apiClient = [[NuwaAPIClient alloc] initWithAccessToken:@"your-access-token"];

// Generate a video from an image
[apiClient imageToVideoWithForwardPrompt:@"人物轻微走动"
                                imageURL:@"/nuwa/xx/ref.jpg"
                                   bizId:@"1995841869673639938"
                                    from:@"1"
                                videoTime:5
                              completion:^(NSString * _Nullable taskId, NSError * _Nullable error) {
    if (error) {
        NSLog(@"Image-to-video generation failed: %@", error.localized Description);
        return;
    }
    
    if (taskId) {
        NSLog(@"Image-to-video task submitted. Task ID: %@", taskId);
        // Use taskId to query task progress
    }
}];

import com.nuwaai.sdk.NuwaAIClient;
import com.nuwaai.sdk.NuwaCallback;

NuwaAIClient.getInstance().getModelManager().img2Video(
    "人物轻微走动",
    1995841869673639938L,
    "1",
    null,
    null,
    "/nuwa/xx/ref.jpg",
    5,
    new NuwaCallback<String>() {
        @Override
        public void onSuccess(String requestId) { }

        @Override
        public void onFailure(int code, String message) { }
    });

await sdk.submitTask({
  type: 'img2video',
  forwardPrompt: '人物轻微走动',
  bizId: 1995841869673639938,
  from: '1',
  videoTime: 5,
  path: '/nuwa/xx/ref.jpg'
});

Response example

{
  "code": 0,
  "msg": null,
  "data": "0be340e8bfd4405fab420a02ac3150d1"
}

Request parameter description

Name	Type	Required	Description
type	String	Yes	Type(img2img:Description,text2img:Description,img2video:Description)
forwardPrompt	String	Yes	Forward prompt
bizId	Long	Yes	Figure/talent ID
from	String	Yes	Description(1:figure Description,2:talent Description,3:Create digital human,4:Description figure Description,5:Description talent Description)
videoTime	String	Yes	Duration(unit：seconds),Description[4,10]
path	String	Yes	OssChinese DescriptionURL

Response parameter description

Name	Type	Description
code	Integer	0: success; non-zero: failure
msg	String	Description
data	String	request ID

5.4 Query generation results

POST /web/model/queryTask

Request example

示例

await sdk.queryModelTask("requestId", 0);

import NuwaSDK

// Initialize the API client
let apiClient = NuwaAPIClient(accessToken: "your-access-token")

// Query task results
apiClient.queryTaskWithRequestId("requestId", lastReq: 0) { result, error in
    if let error = error {
        print("Task query failed: \(error.localized Description)")
        return
    }
    
    if let result = result {
        print("Task query succeeded: \(result)")
        // Process the task result
    }
}

#import <NuwaSDK/NuwaSDK.h>

// Initialize the API client
NuwaAPIClient *apiClient = [[NuwaAPIClient alloc] initWithAccessToken:@"your-access-token"];

// Query task results
[apiClient queryTaskWithRequestId:@"requestId" lastReq:0 completion:^(NSDictionary * _Nullable result, NSError * _Nullable error) {
    if (error) {
        NSLog(@"Task query failed: %@", error.localized Description);
        return;
    }
    
    if (result) {
        NSLog(@"Task query succeeded: %@", result);
        // Process the task result
    }
}];

import com.nuwaai.sdk.NuwaAIClient;
import com.nuwaai.sdk.NuwaCallback;
import com.nuwaai.sdk.model.QueryTaskRequest;
import com.nuwaai.sdk.model.TaskResult;

QueryTaskRequest req = new QueryTaskRequest("requestId", 0);
NuwaAIClient.getInstance().getModelManager().queryTask(req, new NuwaCallback<TaskResult>() {
    @Override
    public void onSuccess(TaskResult data) { }

    @Override
    public void onFailure(int code, String message) { }
});

await sdk.queryTask({ requestId: 'requestId', lastReq: 0 });

Response example

{
  "code": 0,
  "msg": null,
  "data": {
    "status": "done",
    "data": {
      "requestId": "6fa929b620b74dbabe90bade8d967f7a",
      "thumbnailPath": "/pub-nuwa/78/figure/1995841869673639938/a5e9d52675be4a0da036a8093e3ab1d0.jpg",
      "scenePath": "/nuwa/78/figure/1995841869673639938/58eafbb780964614bc5d7b4761211517.jpg",
      "watermarkUrl": "/nuwa/78/figure/1995841869673639938/81ab006fee864635b63b35499216f383.jpg",
      "videoPath": null,
      "userId": "78",
      "from": "1"
    }
  }
}

Request parameter description

Name	Type	Required	Description
requestId	String	Yes	request ID
lastReq	Integer	Yes	YesNo Description(0:No,1:Yes)

Response parameter description

Name	Type	Description
code	Integer	0: success; non-zero: failure
msg	String	Description
data	Object	Description
Description
status	String	Status(running:processing,done:Description)
data	Object	Description
requestId	String	request ID
userId	Long	user ID
from	String	Description(1:figure Description,2:talent Description,3:Create digital human,4:Description figure Description,5:Description talent Description)
videoPath	String	Path
scenePath	String	Path
thumbnailPath	String	Thumbnail path
watermarkUrl	String	Path

6. Digital-human voice API

6.1 Create a voice model

POST /webhp/humanAgent/voiceSet

Request example

示例

await sdk.voiceSet(file, "音频文案");

import NuwaSDK

// Initialize the API client
let apiClient = NuwaAPIClient(accessToken: "your-access-token")

// Create a voice model
let audioURL = URL(fileURLWithPath: "/path/to/audio.wav")
apiClient.createVoiceModel(audioURL, text: "音频文案") { models, error in
    if let error = error {
        print("Voice model creation failed: \(error.localized Description)")
        return
    }
    
    if let models = models {
        print("Voice model created successfully: \(models)")
        // Process the voice model list
    }
}

#import <NuwaSDK/NuwaSDK.h>

// Initialize the API client
NuwaAPIClient *apiClient = [[NuwaAPIClient alloc] initWithAccessToken:@"your-access-token"];

// Create a voice model
NSURL *audioURL = [NSURL fileURLWithPath:@"/path/to/audio.wav"];
[apiClient createVoiceModel:audioURL text:@"音频文案" completion:^(NSArray * _Nullable models, NSError * _Nullable error) {
    if (error) {
        NSLog(@"Voice model creation failed: %@", error.localized Description);
        return;
    }
    
    if (models) {
        NSLog(@"Voice model created successfully: %@", models);
        // Process the voice model list
    }
}];

import com.nuwaai.sdk.NuwaAIClient;
import com.nuwaai.sdk.NuwaCallback;
import com.nuwaai.sdk.model.VoiceModelResponse;

import java.io.File;

File audio = new File("/path/to/audio.wav");
NuwaAIClient.getInstance().getVoiceManager().createVoiceModel(audio, "音频文案", new NuwaCallback<VoiceModelResponse>() {
    @Override
    public void onSuccess(VoiceModelResponse data) { }

    @Override
    public void onFailure(int code, String message) { }
});

// filePath: the temporary path of a local recording or selected audio file
await sdk.voiceSet(filePath, '音频文案');

Response example

{
    "code": 200,
    "model": [
        {
            "version": "1",
            "name": "speech:声音克隆__e4ca50ff",
            "url": "/nuwa-ai/4000170/voice/f2656220c9654cb292ddf6091e56f4b3.wav"
        },
        {
            "version": "3",
            "name": "index:声音克隆__dfb303370fc24d70b328593d4621ae3c",
            "url": "/nuwa-ai/4000170/voice/ba3d776aaf7e4ee1951ee03a47b91f21.wav"
        }
    ]
}

Request parameter description

Name	Type	Required	Description
file	MultipartFile	Yes	File
text	String	Yes	Content

Response parameter description

Name	Type	Description
code	Integer	200: success; non-zero: failure
model	Array	Voice list
model Description
version	String	1:Description，3：Chinese description
name	String	Voice name
url	String	OSSVoice OSS path

6.2 Clone a voice

POST /web/voice/clone

Request example

示例

await sdk.cloneVoice({ voiceName: "A0012", ... });

import NuwaSDK

// Initialize the API client
let apiClient = NuwaAPIClient(accessToken: "your-access-token")

// Clone a voice
let voiceModel = ["version": "1", "name": "speech:声音克隆__e4ca50ff", "url": "/nuwa-ai/4000170/voice/f2656220c9654cb292ddf6091e56f4b3.wav"]
apiClient.cloneVoice(voiceName: "A0012", content: "你好，这是一段测试文本", voiceType: "5", sex: "1", age: "1", voiceTime: 5, featureList: ["大气活力"], model: voiceModel) { success, error in
    if let error = error {
        print("Voice cloning failed: \(error.localized Description)")
        return
    }
    
    if success {
        print("Voice cloned successfully")
    }
}

#import <NuwaSDK/NuwaSDK.h>

// Initialize the API client
NuwaAPIClient *apiClient = [[NuwaAPIClient alloc] initWithAccessToken:@"your-access-token"];

// Clone a voice
NSDictionary *voiceModel = @{@"version": @"1", @"name": @"speech:声音克隆__e4ca50ff", @"url": @"/nuwa-ai/4000170/voice/f2656220c9654cb292ddf6091e56f4b3.wav"};
[apiClient cloneVoiceWithVoiceName:@"A0012" content:@"你好，这是一段测试文本" voiceType:@"5" sex:@"1" age:@"1" voiceTime:5 featureList:@[@"大气活力"] model:voiceModel completion:^(BOOL success, NSError * _Nullable error) {
    if (error) {
        NSLog(@"Voice cloning failed: %@", error.localized Description);
        return;
    }
    
    if (success) {
        NSLog(@"Voice cloned successfully");
    }
}];

import com.nuwaai.sdk.NuwaAIClient;
import com.nuwaai.sdk.NuwaCallback;
import com.nuwaai.sdk.model.CloneVoiceRequest;

CloneVoiceRequest req = new CloneVoiceRequest();
req.setVoiceName("A0012");
// Set content, voiceType, sex, age, voiceTime, featureList, model, and other fields as needed
NuwaAIClient.getInstance().getVoiceManager().cloneVoice(req, new NuwaCallback<Boolean>() {
    @Override
    public void onSuccess(Boolean data) { }

    @Override
    public void onFailure(int code, String message) { }
});

await sdk.voiceClone({ voiceName: 'A0012', /* content, voiceType, model, etc. */ });

Response example

{
    "code": 0,
    "msg": null,
    "data": true
}

Request parameter description

Name	Type	Required	Description
voiceName	String	Yes	Voice name
content	String	Yes	Voice informationcontent
voiceType	String	Yes	voice type（3:Description,5:Description）
sex	String	Yes	gender（1：male，2：female，3：neutral）
age	String	Yes	age（1:Description，2：Chinese Description，3：Description，4：Description）
voiceTime	Integer	Yes	voiceduration（unit：seconds）
featureList	Array	No	Voice information
model	Array	Yes	Voice information
model Description
version	String	Yes	1:Description，3：Chinese description
name	String	Yes	Voice name
url	String	Yes	OSSVoice OSS path

Response parameter description

Name	Type	Description
code	Integer	0: success; non-zero: failure
msg	String	Description
data	Boolean	true :success，false:failure

6.3 Delete a voice

DELETE /web/voice/delete/{id}

Request example

示例

await sdk.deleteVoice("1935958397612609538");

import NuwaSDK

// Initialize the API client
let apiClient = NuwaAPIClient(accessToken: "your-access-token")

// Delete a voice
apiClient.deleteVoice("1935958397612609538") { success, error in
    if let error = error {
        print("Voice deletion failed: \(error.localized Description)")
        return
    }
    
    if success {
        print("Voice deleted successfully")
    }
}

#import <NuwaSDK/NuwaSDK.h>

// Initialize the API client
NuwaAPIClient *apiClient = [[NuwaAPIClient alloc] initWithAccessToken:@"your-access-token"];

// Delete a voice
[apiClient deleteVoice:@"1935958397612609538" completion:^(BOOL success, NSError * _Nullable error) {
    if (error) {
        NSLog(@"Voice deletion failed: %@", error.localized Description);
        return;
    }
    
    if (success) {
        NSLog(@"Voice deleted successfully");
    }
}];

import com.nuwaai.sdk.NuwaAIClient;
import com.nuwaai.sdk.NuwaCallback;

NuwaAIClient.getInstance().getVoiceManager().deleteVoice("1935958397612609538", new NuwaCallback<Boolean>() {
    @Override
    public void onSuccess(Boolean data) { }

    @Override
    public void onFailure(int code, String message) { }
});

await sdk.voiceDelete('1935958397612609538');

Response example

{
  "code": 0,
  "msg": null,
  "data": true
}

Request parameter description

Name	Type	Required	Description
id	Long	Yes	voice ID

Response parameter description

Name	Type	Description
code	Integer	0: success; non-zero: failure
msg	String	Description
data	Boolean	true :success，false:failure

6.4 Voice list

POST /web/voice/voiceList

Request example

示例

await sdk.voiceList({ type: 1, current: 1, size: 10 });

import NuwaSDK

// Initialize the API client
let apiClient = NuwaAPIClient(accessToken: "your-access-token")

// Retrieve the voice list
apiClient.getVoiceList(type: 1, current: 1, size: 10, age: nil, voiceName: nil, feature: nil) { result, error in
    if let error = error {
        print("Failed to retrieve voice list: \(error.localized Description)")
        return
    }
    
    if let result = result {
        print("Voice list retrieved successfully: \(result)")
        // Process the voice list
    }
}

#import <NuwaSDK/NuwaSDK.h>

// Initialize the API client
NuwaAPIClient *apiClient = [[NuwaAPIClient alloc] initWithAccessToken:@"your-access-token"];

// Retrieve the voice list
[apiClient getVoiceListWithType:1 current:1 size:10 age:nil voiceName:nil feature:nil completion:^(NSDictionary * _Nullable result, NSError * _Nullable error) {
    if (error) {
        NSLog(@"Failed to retrieve voice list: %@", error.localized Description);
        return;
    }
    
    if (result) {
        NSLog(@"Voice list retrieved successfully: %@", result);
        // Process the voice list
    }
}];

import com.nuwaai.sdk.NuwaAIClient;
import com.nuwaai.sdk.NuwaCallback;
import com.nuwaai.sdk.model.PageData;
import com.nuwaai.sdk.model.VoiceListRequest;
import com.nuwaai.sdk.model.VoiceRecord;

VoiceListRequest req = new VoiceListRequest();
req.setType(1);
req.setCurrent(1);
req.setSize(10);
NuwaAIClient.getInstance().getVoiceManager().getVoiceList(req, new NuwaCallback<PageData<VoiceRecord>>() {
    @Override
    public void onSuccess(PageData<VoiceRecord> data) { }

    @Override
    public void onFailure(int code, String message) { }
});

await sdk.voiceList({ type: 1, current: 1, size: 10 });

Response example

{
  "code": 0,
  "msg": null,
  "data": {
    "records": [
      {
        "createTime": "2025-08-12 15:00:50",
        "updateTime": "2025-08-12 15:00:50",
        "voiceId": "1955162543697666049",
        "voiceName": "热血青年",
        "modeName": "index:测试1__06bd8d06",
        "sex": "1",
        "age": "1",
        "voiceType": "5",
        "feature": "大气活力",
        "path": "/pub-nuwa/admin/audio/284ea5be2345470cbffef3aceecde81f.wav",
        "systemFlag": "1",
        "featureList": [
          "大气活力"
        ]
      },
      {
        "createTime": "2025-08-12 14:59:41",
        "updateTime": "2025-08-12 14:59:41",
        "voiceId": "1955162254982750210",
        "voiceName": "少儿故事",
        "modeName": "index:少儿故事__1b7293b3",
        "sex": "1",
        "age": "4",
        "voiceType": "5",
        "feature": "亲和力强",
        "path": "/pub-nuwa/admin/audio/d5077c655c5e4dc3b35eb93e7d74b491.wav",
        "systemFlag": "1",
        "featureList": [
          "亲和力强"
        ]
      }
    ],
    "total": 14,
    "size": 2,
    "current": 2,
    "pages": 7
  }
}

Request parameter description

Name	Type	Required	Description
size	Long	Yes	page size
current	Long	Yes	current page(page 1)
type	Integer	Yes	Querytype(1:platformvoice，2：Description voice)
age	String	No	age（1:Description，2：Chinese Description，3：Description，4：Description）
voiceName	String	No	Voice name
feature	String	No	Voice information

Response parameter description

Name	Type	Description
code	Integer	0: success; non-zero: failure
msg	String	Description
data	Object	Description
recods Description
createTime	LocalDateTime	created at
updateTime	LocalDateTime	updated at
voiceId	Long	voiceid
voiceName	String	Voice name
modeName	String	Voice name
sex	String	gender（1：male，2：female，3：neutral）
age	String	age（1:Description，2：Chinese Description，3：Description，4：Description）
voiceTime	Integer	voiceduration（unit：seconds）
voiceType	String	voice type（3:Description,5:Description）
feature	String	Voice information
path	String	voicepath
systemFlag	String	voicepermission（1：public，2：private）
featureList	Array	Voice list
Description
total	Long	total records
size	Long	page size
current	Long	current page(page 1)
pages	Long	total pages

7. Digital-human appearance API

7.1 Create an appearance

POST /web/figure/create

Request example

示例

await sdk.createFigure("A042");

import NuwaSDK

// Initialize the API client
let apiClient = NuwaAPIClient(accessToken: "your-access-token")

// Create an appearance
apiClient.createFigure("A042") { figureDetail, error in
    if let error = error {
        print("Appearance creation failed: \(error.localized Description)")
        return
    }
    
    if let figureDetail = figureDetail {
        print("Appearance created successfully: \(figureDetail)")
        // Process the appearance details
    }
}

#import <NuwaSDK/NuwaSDK.h>

// Initialize the API client
NuwaAPIClient *apiClient = [[NuwaAPIClient alloc] initWithAccessToken:@"your-access-token"];

// Create an appearance
[apiClient createFigure:@"A042" completion:^(NSDictionary * _Nullable figureDetail, NSError * _Nullable error) {
    if (error) {
        NSLog(@"Appearance creation failed: %@", error.localized Description);
        return;
    }
    
    if (figureDetail) {
        NSLog(@"Appearance created successfully: %@", figureDetail);
        // Process the appearance details
    }
}];

import com.nuwaai.sdk.NuwaAIClient;
import com.nuwaai.sdk.NuwaCallback;
import com.nuwaai.sdk.model.FigureDetail;

NuwaAIClient.getInstance().getFigureManager().createFigure("A042", new NuwaCallback<FigureDetail>() {
    @Override
    public void onSuccess(FigureDetail data) { }

    @Override
    public void onFailure(int code, String message) { }
});

await sdk.figureCreate({ figureName: 'A042' });

Response example

{
  "code": 0,
  "msg": null,
  "data": {
    "createBy": "18672393036",
    "createTime": "2025-12-02 21:05:57",
    "updateBy": "18672393036",
    "updateTime": "2025-12-02 21:05:57",
    "figureId": "1995841869673639938",
    "figureName": "A042",
    "status": "0",
    "systemFlag": "2",
    "client": "pc",
    "channel": "natural",
    "userId": "78"
  }
}

Request parameter description

Name	Type	Required	Description
figureName	String	Yes	figurename

Response parameter description

Name	Type	Description
code	Integer	0: success; non-zero: failure
msg	String	Description
data	Object	Description
figure Description
figureId	Long	figureid
figureName	String	figurename
status	String	figurestatus（0：incomplete，1：creating，2：created,3:creation failed）
systemFlag	String	figurepermission（1：public，2：private）
userId	Long	user ID
createBy	String	Create Description
updateBy	String	Description
updateTime	LocalDateTime	updated at
client	String	client
channel	String	channel

7.2 Update an appearance

PUT /web/figure/edit

Request example

示例

await sdk.editFigure({ figureId: "199...", ... });

import NuwaSDK

// Initialize the API client
let apiClient = NuwaAPIClient(accessToken: "your-access-token")

// Update an appearance
let actionList = ["actionType": "0", "videoPath": "/nuwa/xx/action.mp4"]
apiClient.editFigure(figureId: "199...", figureName: "A042", videoPath: "/nuwa/xx/video.mp4", voiceType: "5", modeName: "index:测试1__06bd8d06", displayName: "测试声音", voicePath: nil, style: nil, age: "1", sex: "1", actionList: [actionList]) { taskId, error in
    if let error = error {
        print("Appearance update failed: \(error.localized Description)")
        return
    }
    
    if let taskId = taskId {
        print("Appearance update task submitted. Task ID: \(taskId)")
        // Use taskId to query task progress
    }
}

#import <NuwaSDK/NuwaSDK.h>

// Initialize the API client
NuwaAPIClient *apiClient = [[NuwaAPIClient alloc] initWithAccessToken:@"your-access-token"];

// Update an appearance
NSDictionary *actionItem = @{@"actionType": @"0", @"videoPath": @"/nuwa/xx/action.mp4"};
NSArray *actionList = @[actionItem];
[apiClient editFigureWithFigureId:@"199..." figureName:@"A042" videoPath:@"/nuwa/xx/video.mp4" voiceType:@"5" modeName:@"index:测试1__06bd8d06" displayName:@"测试声音" voicePath:nil style:nil age:@"1" sex:@"1" actionList:actionList completion:^(NSString * _Nullable taskId, NSError * _Nullable error) {
    if (error) {
        NSLog(@"Appearance update failed: %@", error.localized Description);
        return;
    }
    
    if (taskId) {
        NSLog(@"Appearance update task submitted. Task ID: %@", taskId);
        // Use taskId to query task progress
    }
}];

import com.nuwaai.sdk.NuwaAIClient;
import com.nuwaai.sdk.NuwaCallback;
import com.nuwaai.sdk.model.EditFigureRequest;

EditFigureRequest req = new EditFigureRequest();
req.setFigureId("199...");
// Set figureName, videoPath, voiceType, modeName, displayName, actionList, and other fields as needed
NuwaAIClient.getInstance().getFigureManager().editFigure(req, new NuwaCallback<String>() {
    @Override
    public void onSuccess(String taskId) { }

    @Override
    public void onFailure(int code, String message) { }
});

await sdk.figureEdit({ figureId: '199...', /* figureName, videoPath, etc. */ });

Response example

{
    "code": 0,
    "msg": null,
    "data": "db5945deccd24ad2bf13687b94c585d8"
}

Request parameter description

Name	Type	Required	Description
figureId	Long	Yes	figure ID
figureName	String	Yes	figurename
videoPath	String	Yes	OSS path
voiceType	String	Yes	voice type（3:Description,5:Description）
modeName	String	Yes	Voice name
displayName	String	Yes	Voice name
voicePath	String	No	voicefile path
style	String	No	stylename
age	String	Yes	age（1:Description，2：Chinese Description，3：Description，4：Description）
sex	String	Yes	gender（1：male，2：female，3：neutral）
actionList	Array	No	Figure list
Description
id	Long	No	Model ID
actionType	String	Yes	Type（0：opening text，1：Description，2：Description）
videoPath	String	Yes	OssChinesePath

Response parameter description

Name	Type	Description
code	Integer	0: success; non-zero: failure
msg	String	Description
data	String	request ID，Model IDDescriptionQueryfigureStatus

7.3 Delete an appearance

DELETE /web/figure/delete/{id}

Request example

示例

await sdk.deleteFigure("199...");

import NuwaSDK

// Initialize the API client
let apiClient = NuwaAPIClient(accessToken: "your-access-token")

// Delete an appearance
apiClient.deleteFigure("199...") { success, error in
    if let error = error {
        print("Appearance deletion failed: \(error.localized Description)")
        return
    }
    
    if success {
        print("Appearance deleted successfully")
    }
}

#import <NuwaSDK/NuwaSDK.h>

// Initialize the API client
NuwaAPIClient *apiClient = [[NuwaAPIClient alloc] initWithAccessToken:@"your-access-token"];

// Delete an appearance
[apiClient deleteFigure:@"199..." completion:^(BOOL success, NSError * _Nullable error) {
    if (error) {
        NSLog(@"Appearance deletion failed: %@", error.localized Description);
        return;
    }
    
    if (success) {
        NSLog(@"Appearance deleted successfully");
    }
}];

import com.nuwaai.sdk.NuwaAIClient;
import com.nuwaai.sdk.NuwaCallback;

NuwaAIClient.getInstance().getFigureManager().deleteFigure("199...", new NuwaCallback<Boolean>() {
    @Override
    public void onSuccess(Boolean data) { }

    @Override
    public void onFailure(int code, String message) { }
});

await sdk.figureDelete('199...');

Response example

 {
    "code": 0,
    "msg": null,
    "data": true
}

Request parameter description

Name	Type	Required	Description
id	Long	Yes	figure ID

Response parameter description

Name	Type	Description
code	Integer	0: success; non-zero: failure
msg	String	Description
data	Boolean	true: success,false：failure

7.4 Appearance list

POST /web/figure/figureList

Request example

示例

await sdk.figureList({ type: 2, current: 1, size: 10 });

import NuwaSDK

// Initialize the API client
let apiClient = NuwaAPIClient(accessToken: "your-access-token")

// Retrieve the appearance list
apiClient.getFigureList(type: 2, current: 1, size: 10, age: nil, sex: nil, figureName: nil, style: nil) { result, error in
    if let error = error {
        print("Failed to retrieve appearance list: \(error.localized Description)")
        return
    }
    
    if let result = result {
        print("Appearance list retrieved successfully: \(result)")
        // Process the appearance list
    }
}

#import <NuwaSDK/NuwaSDK.h>

// Initialize the API client
NuwaAPIClient *apiClient = [[NuwaAPIClient alloc] initWithAccessToken:@"your-access-token"];

// Retrieve the appearance list
[apiClient getFigureListWithType:2 current:1 size:10 age:nil sex:nil figureName:nil style:nil completion:^(NSDictionary * _Nullable result, NSError * _Nullable error) {
    if (error) {
        NSLog(@"Failed to retrieve appearance list: %@", error.localized Description);
        return;
    }
    
    if (result) {
        NSLog(@"Appearance list retrieved successfully: %@", result);
        // Process the appearance list
    }
}];

import com.nuwaai.sdk.NuwaAIClient;
import com.nuwaai.sdk.NuwaCallback;
import com.nuwaai.sdk.model.FigureListRequest;
import com.nuwaai.sdk.model.FigureRecord;
import com.nuwaai.sdk.model.PageData;

FigureListRequest req = new FigureListRequest();
req.setType(2);
req.setCurrent(1);
req.setSize(10);
NuwaAIClient.getInstance().getFigureManager().getFigureList(req, new NuwaCallback<PageData<FigureRecord>>() {
    @Override
    public void onSuccess(PageData<FigureRecord> data) { }

    @Override
    public void onFailure(int code, String message) { }
});

await sdk.figureList({ type: 2, current: 1, size: 10 });

Response example

{
  "code": 0,
  "msg": null,
  "data": {
    "records": [
      {
        "createTime": "2025-12-02 21:05:57",
        "updateTime": "2025-12-02 21:05:57",
        "figureId": "1995841869673639938",
        "figureName": "A042",
        "thumbnailPath": /pub-nuwa/47/figure/1996947256201060354/53e2bc648edb4b68918d8936251544da.jpg,
        "status": "0",
        "systemFlag": "2",
        "storage": "0",
        "userId": "78",
        "nickName": "王白玄龟"
      },
      {
       "createTime": "2025-11-28 12:02:40",
       "updateTime": "2025-11-28 12:06:29",
       "figureId": "1994255593560322050",
        "figureName": "星辰ixYb",
        "thumbnailPath": "/pub-nuwa/78/figure/1994255593560322050/262f413c69914f718c30c9fedd53d692.jpg",
        "status": "2",
        "systemFlag": null,
       "storage": "1584116",
       "userId": "78",
        "nickName": "王白玄龟"
       
      }
    ],
    "total": 8,
    "size": 2,
    "current": 1,
    "pages": 4
  }
}

Request parameter description

Name	Type	Required	Description
current	Long	Yes	current page(page 1)
size	Long	Yes	page size
type	Integer	Yes	Querytype（1：platformfigure，2：Description figure）
age	String	No	age（1:Description，2：Chinese Description，3：Description，4：Description）
sex	String	No	gender（1：male，2：female，3：neutral）
figureName	String	No	figurename
style	String	No	figurestyle

Response parameter description

Name	Type	Description
code	Integer	0: success; non-zero: failure
msg	String	Description
data	Array	Description
records Description
figureId	Long	figure ID
figureName	String	figurename
userId	Long	user ID
nickName	String	user Description
thumbnailPath	String	figurethumbnailpath
storage	Long	storage size（unit：Byte）
status	String	figurestatus（0：incomplete，1：creating，2：created,3:creation failed）
createTime	LocalDateTime	created at
updateTime	LocalDateTime	updated at

7.5 Appearance details

GET /web/figure/detail/{figureId}

Request example

示例

await sdk.figureDetail("199...");

import NuwaSDK

// Initialize the API client
let apiClient = NuwaAPIClient(accessToken: "your-access-token")

// Retrieve appearance details
apiClient.getFigureDetail("199...") { figureDetail, error in
    if let error = error {
        print("Failed to retrieve appearance details: \(error.localized Description)")
        return
    }
    
    if let figureDetail = figureDetail {
        print("Appearance details retrieved successfully: \(figureDetail)")
        // Process the appearance details
    }
}

#import <NuwaSDK/NuwaSDK.h>

// Initialize the API client
NuwaAPIClient *apiClient = [[NuwaAPIClient alloc] initWithAccessToken:@"your-access-token"];

// Retrieve appearance details
[apiClient getFigureDetail:@"199..." completion:^(NSDictionary * _Nullable figureDetail, NSError * _Nullable error) {
    if (error) {
        NSLog(@"Failed to retrieve appearance details: %@", error.localized Description);
        return;
    }
    
    if (figureDetail) {
        NSLog(@"Appearance details retrieved successfully: %@", figureDetail);
        // Process the appearance details
    }
}];

import com.nuwaai.sdk.NuwaAIClient;
import com.nuwaai.sdk.NuwaCallback;
import com.nuwaai.sdk.model.FigureDetail;

NuwaAIClient.getInstance().getFigureManager().getFigureDetail("199...", new NuwaCallback<FigureDetail>() {
    @Override
    public void onSuccess(FigureDetail data) { }

    @Override
    public void onFailure(int code, String message) { }
});

await sdk.figureDetail('199...');

Response example

{
  "code": 0,
  "msg": null,
  "data": {
    "createBy": "",
    "createTime": "2025-11-28 12:02:40",
    "updateBy": "",
    "updateTime": "2025-11-28 12:06:29",
    "delFlag": "0",
    "figureId": "1994255593560322050",
    "figureName": "星辰ixYb",
    "age": "1",
    "sex": "2",
    "style": null,
    "startPath": "/nuwa/78/figure/1994255593560322050/13d93328e5c04802b22bb77378f69097.jpg",
    "thumbnailPath": "/pub-nuwa/78/figure/1994255593560322050/262f413c69914f718c30c9fedd53d692.jpg",
    "previewPath": null,
    "figurePath": "/nuwa/78/figure/1994255593560322050/model.mp4",
    "videoPath": "/nuwa/78/figure/1994255593560322050/0cc04aa4c8224a6b86dfd8a48e588665.mp4",
    "voicePath": "",
    "displayName": "中二少女",
    "modeName": "index:飞销__cbbcc4ec",
    "voiceType": "5",
    "generaType": "3",
    "preStatus": "0",
    "status": "2",
    "systemFlag": "2",
    "failReason": "",
    "storage": "1584116",
    "client": "pc",
    "channel": "natural",
    "userId": "78"
  }
}

Request parameter description

Name	Type	Required	Description
figureId	Long	Yes	figure ID

Response parameter description

Name	Type	Description
code	Integer	0: success; non-zero: failure
msg	String	Description
data	Object	Description
figure Description
figureId	Long	figureid
figureName	String	figurename
age	String	age（1:Description，2：Chinese Description，3：Description，4：Description）
sex	String	gender（1：male，2：female，3：neutral）
style	String	figurestyle
thumbnailPath	String	thumbnailpath
previewPath	String	figurePath
figurePath	String	figurePath
videoPath	String	Path
voicePath	String	voicefile path
displayName	String	Voice name
modeName	String	Voice name
voiceType	String	voice type（3:Description,5:Description）
generaType	String	Type(1:Description,2:Description,3:Description)
preStatus	String	figureStatus（1：creating,2:created，3：creation failed）
status	String	figurestatus（0：incomplete，1：creating，2：created,3:creation failed）
systemFlag	String	figurepermission（1：public，2：private）
failReason	String	figure Description creation failed Description
actions	String	action list
client	String	client
channel	String	channel
storage	Long	storage size（unit：Byte）
userId	Long	user ID
delFlag	String	Delete Description,1:DescriptionDelete,0:Description

8. Real-time digital-human interaction

8.1 Initialization and connection

Request example

示例

import NuwaSDK

class ViewController: UIViewController, NuwaClientDelegate {
    
    private var nuwaClient: NuwaClient?
    private var videoContainerView: UIView!
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        // Initialize NuwaClient
        nuwaClient = NuwaClient(avatarId: "your_avatar_id", bizId: "your_biz_id", accessToken: "your_access_token")
        nuwaClient?.delegate = self
        
        // Create the video container
        videoContainerView = UIView(frame: CGRect(x: 0, y: 0, width: view.bounds.width, height: view.bounds.width * 9/16))
        videoContainerView.backgroundColor = .black
        view.addSubview(videoContainerView)
    }
    
    // Connect to the digital human
    func connect() {
        guard let nuwaClient = nuwaClient else { return }
        
        // Retrieve the video view and add it to the container
        let videoView = nuwaClient.videoViewWithFrame(videoContainerView.bounds)
        videoContainerView.addSubview(videoView)
        
        // Start the connection
        nuwaClient.connect()
    }
    
    // Disconnect
    func disconnect() {
        nuwaClient?.disconnect()
    }
    
    // Send a text message
    func sendTextMessage(_ text: String) {
        nuwaClient?.sendTextMessage(text)
    }
    
    // Send a control message
    func sendControlMessage(_ content: String) {
        nuwaClient?.sendControlMessage(content)
    }
    
    // Send audio data
    func sendAudioData(_ audioData: Data) {
        nuwaClient?.sendAudioData(audioData)
    }
    
    // Mute local audio
    func muteLocalAudio(_ mute: Bool) {
        nuwaClient?.muteLocalAudio(mute)
    }
    
    // Disable local video
    func muteLocalVideo(_ mute: Bool) {
        nuwaClient?.muteLocalVideo(mute)
    }
    
    // MARK: - NuwaClientDelegate
    
    func nuwaClientDidChangeState(_ state: NuwaConnectionState) {
        switch state {
        case .disconnected:
            print("State: disconnected")
        case .connecting:
            print("State: connecting...")
        case .connected:
            print("State: connected")
        case .reconnecting:
            print("State: reconnecting...")
        }
    }
    
    func nuwaClientDidConnect(_ sessionId: String) {
        print("Connected. Session ID: \(sessionId)")
    }
    
    func nuwaClientDidDisconnect() {
        print("Disconnected")
    }
    
    func nuwaClientDidReceiveMessage(_ message: [AnyHashable : Any]) {
        print("Received message: \(message)")
        
        if let type = message["type"] as? String {
            switch type {
            case "avator-text":
                if let text = message["data"] as? [String: Any], let content = text["text"] as? String {
                    print("Digital-human text: \(content)")
                }
            case "chat":
                if let data = message["data"] as? [String: Any], let content = data["content"] as? String {
                    print("Chat message: \(content)")
                }
            case "asr-text":
                if let data = message["data"] as? [String: Any], let content = data["content"] as? String {
                    print("Speech recognition: \(content)")
                }
            default:
                break
            }
        }
    }
    
    func nuwaClientDidReceiveError(_ error: Error) {
        print("Error: \(error.localized Description)")
    }
    
    func nuwaClientDidReceiveRemoteVideo(_ videoView: UIView) {
        DispatchQueue.main.async {
            videoView.frame = self.videoContainerView.bounds
            self.videoContainerView.addSubview(videoView)
            self.videoContainerView.bringSubviewToFront(videoView)
        }
    }
    
    func nuwaClientDidReceiveRemoteAudio() {
        print("Received remote audio")
    }
}

#import <NuwaSDK/NuwaSDK.h>

@interface ViewController () <NuwaClientDelegate>

@property (nonatomic, strong) NuwaClient *nuwaClient;
@property (nonatomic, strong) UIView *videoContainerView;

@end

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];
    
    // Initialize NuwaClient
    self.nuwaClient = [[NuwaClient alloc] initWithAvatarId:@"your_avatar_id" bizId:@"your_biz_id" accessToken:@"your_access_token"];
    self.nuwaClient.delegate = self;
    
    // Create the video container
    self.videoContainerView = [[UIView alloc] initWithFrame:CGRectMake(0, 0, self.view.bounds.size.width, self.view.bounds.size.width * 9/16)];
    self.videoContainerView.backgroundColor = [UIColor blackColor];
    [self.view addSubview:self.videoContainerView];
}

// Connect to the digital human
- (void)connect {
    // Retrieve the video view and add it to the container
    UIView *videoView = [self.nuwaClient videoViewWithFrame:self.videoContainerView.bounds];
    [self.videoContainerView addSubview:videoView];
    
    // Start the connection
    [self.nuwaClient connect];
}

// Disconnect
- (void)disconnect {
    [self.nuwaClient disconnect];
}

// Send a text message
- (void)sendTextMessage:(NSString *)text {
    [self.nuwaClient sendTextMessage:text];
}

// Send a control message
- (void)sendControlMessage:(NSString *)content {
    [self.nuwaClient sendControlMessage:content];
}

// Send audio data
- (void)sendAudioData:(NSData *)audioData {
    [self.nuwaClient sendAudioData:audioData];
}

// Mute local audio
- (void)muteLocalAudio:(BOOL)mute {
    [self.nuwaClient muteLocalAudio:mute];
}

// Disable local video
- (void)muteLocalVideo:(BOOL)mute {
    [self.nuwaClient muteLocalVideo:mute];
}

#pragma mark - NuwaClientDelegate

- (void)nuwaClientDidChangeState:(NuwaConnectionState)state {
    switch (state) {
        case NuwaConnectionStateDisconnected:
            NSLog(@"State: disconnected");
            break;
        case NuwaConnectionStateConnecting:
            NSLog(@"State: connecting...");
            break;
        case NuwaConnectionStateConnected:
            NSLog(@"State: connected");
            break;
        case NuwaConnectionStateReconnecting:
            NSLog(@"State: reconnecting...");
            break;
    }
}

- (void)nuwaClientDidConnect:(NSString *)sessionId {
    NSLog(@"Connected. Session ID: %@", sessionId);
}

- (void)nuwaClientDidDisconnect {
    NSLog(@"Disconnected");
}

- (void)nuwaClientDidReceiveMessage:(NSDictionary *)message {
    NSLog(@"Received message: %@", message);
    
    NSString *type = message[@"type"];
    if ([type isEqualToString:@"avator-text"]) {
        NSString *text = message[@"data"][@"text"];
        if (text) {
            NSLog(@"Digital-human text: %@", text);
        }
    } else if ([type isEqualToString:@"chat"]) {
        NSString *content = message[@"data"][@"content"];
        if (content) {
            NSLog(@"Chat message: %@", content);
        }
    } else if ([type isEqualToString:@"asr-text"]) {
        NSString *content = message[@"data"][@"content"];
        if (content) {
            NSLog(@"Speech recognition: %@", content);
        }
    }
}

- (void)nuwaClientDidReceiveError:(NSError *)error {
    NSLog(@"Error: %@", error.localized Description);
}

- (void)nuwaClientDidReceiveRemoteVideo:(UIView *)videoView {
    dispatch_async(dispatch_get_main_queue(), ^{  
        videoView.frame = self.videoContainerView.bounds;
        [self.videoContainerView addSubview:videoView];
        [self.videoContainerView bringSubviewToFront:videoView];
    });
}

- (void)nuwaClientDidReceiveRemoteAudio {
    NSLog(@"Received remote audio");
}

@end

9. Agent creation API

9.1 Create an agent

POST /web/digital/user/create

Request example

示例

await sdk.createDigitalUser("A020");

import com.nuwaai.sdk.NuwaAIClient;
import com.nuwaai.sdk.NuwaCallback;
import com.nuwaai.sdk.model.DigitalUserRecord;

NuwaAIClient.getInstance().getDigitalUserManager().create("A020", new NuwaCallback<DigitalUserRecord>() {
    @Override
    public void onSuccess(DigitalUserRecord data) { }

    @Override
    public void onFailure(int code, String message) { }
});

await sdk.digitalUserCreate({ name: 'A020' });

Response example

{
  "code": 0,
  "msg": null,
  "data": {
    "createBy": "18672393036",
    "createTime": "2025-12-04 21:29:59",
    "updateBy": "18672393036",
    "updateTime": "2025-12-04 21:29:59",
    "delFlag": "0",
    "id": "1996572693326966785",
    "name": "A020",
    "status": "0",
    "client": "pc",
    "channel": "natural",
    "userId": "78",
    "systemFlag": "2"
  }
}

Request parameter description

Name	Type	Required	Description
name	String	Yes	agentname

Response parameter description

Name	Type	Description
code	Integer	0: success; non-zero: failure
msg	String	Description
data	Object	Description
agent Description
id	Long	agent ID
name	String	agentname
status	String	agentstatus（0：incomplete，1：creating，2：created,3:creation failed）
client	String	client(pc,h5)
channel	String	channel
userId	Long	user ID
systemFlag	String	agentpermission（1：public，2：private）
createBy	String	Create Description
createTime	LocalDateTime	created at
updateBy	String	Description
updateTime	LocalDateTime	updated at
delFlag	String	Delete Description,1:DescriptionDelete,0:Description

8.2 Update an agent

PUT /web/digital/user/edit

Request example

示例

await sdk.editDigitalUser({ id: "199...", ... });

import com.nuwaai.sdk.NuwaAIClient;
import com.nuwaai.sdk.NuwaCallback;
import com.nuwaai.sdk.model.DigitalUserEditRequest;

DigitalUserEditRequest req = new DigitalUserEditRequest();
req.setId("199...");
// Set name, age, sex, figureId, figurePath, thumbnailPath, roleId, skillList, and other fields as needed
NuwaAIClient.getInstance().getDigitalUserManager().edit(req, new NuwaCallback<String>() {
    @Override
    public void onSuccess(String taskId) { }

    @Override
    public void onFailure(int code, String message) { }
});

await sdk.digitalUserEdit({ id: '199...', /* name, figureId, roleId, etc. */ });

Response example

{
    "code": 0,
    "msg": null,
    "data": "aced3bf3189c4576817fd590a6d397b7"
}

Request parameter description

Name	Type	Required	Description
id	Long	Yes	agent ID
name	String	Yes	agentname
age	String	Yes	agentage
sex	String	Yes	gender（1：male，2：female，3：neutral）
musicName	String	No	background music Description name
musicPath	String	No	background musicpath
musicVolume	Long	No	background musicvolume
keyWords	String	No	hotwords
shapeMouth	String	Yes	Description
speedSpeech	String	Yes	speaking rate
driveMode	String	Yes	Description(0:reverse,1:forward)
detectMode	String	No	Description(0:Description，1：Description)
roleId	Long	Yes	role ID
roleName	String	Yes	rolename
applicationScenarios	String	No	application scenarioID
specialty	String	No	background
personality	String	No	personality
languageStyle	String	No	language style
goal	String	No	conversation goal
figureId	BigDecimal	No	figure ID
openText	String	No	opening text,Description1000Description
detectFlag	String	No	Description（0：off，1：on）
silentTime	Integer	No	Description（unit：seconds）
recommend1	String	No	Description1,200Description
recommend2	String	No	Description2,200Description
recommend3	String	No	Description3,200Description
remark	String	No	Description
skillList	Array	No	skillList
skill Description
skillName	String	Yes	skillname
enabled	String	Yes	Enabled（1：enabled，0：disabled）
cardList	Array	No	DescriptionList
Description
cardName	String	Yes	Description name
enabled	String	Yes	Enabled（1：enabled，0：disabled）

Response parameter description

Name	Type	Description
code	Integer	0: success; non-zero: failure
msg	String	Description
data	String	CreateagentModel ID，DescriptionCreateagent Description，Description figure DescriptionCreateagent Description

8.3 Delete an agent

DELETE /web/digital/user/delete/{id}

Request example

示例

await sdk.deleteDigitalUser("199...");

import com.nuwaai.sdk.NuwaAIClient;
import com.nuwaai.sdk.NuwaCallback;

NuwaAIClient.getInstance().getDigitalUserManager().delete("199...", new NuwaCallback<Boolean>() {
    @Override
    public void onSuccess(Boolean data) { }

    @Override
    public void onFailure(int code, String message) { }
});

await sdk.digitalUserDelete('199...');

Response example

{
    "code": 0,
    "msg": null,
    "data": true
}

Request parameter description

Name	Type	Required	Description
id	Long	Yes	agent ID

Response parameter description

Name	Type	Description
code	Integer	0: success; non-zero: failure
msg	String	Description
data	Boolean	true:success,false：failure

8.4 Agent list

POST /web/digital/user/digitalList

Request example

示例

await sdk.digitalUserList({ type: 2, current: 1, size: 10 });

import com.nuwaai.sdk.NuwaAIClient;
import com.nuwaai.sdk.NuwaCallback;
import com.nuwaai.sdk.model.DigitalUserListRequest;
import com.nuwaai.sdk.model.DigitalUserRecord;
import com.nuwaai.sdk.model.PageData;

DigitalUserListRequest req = new DigitalUserListRequest();
req.setType(2);
req.setCurrent(1);
req.setSize(10);
NuwaAIClient.getInstance().getDigitalUserManager().getList(req, new NuwaCallback<PageData<DigitalUserRecord>>() {
    @Override
    public void onSuccess(PageData<DigitalUserRecord> data) { }

    @Override
    public void onFailure(int code, String message) { }
});

await sdk.digitalList({ type: 2, current: 1, size: 10 });

Response example

{
  "code": 0,
  "msg": null,
  "data": {
    "records": [
      {     
        "createTime": "2025-12-04 21:29:59",
        "updateTime": "2025-12-04 21:29:59",
        "id": "1996572693326966785",
        "name": "A020",
        "status": "0",
        "knowledgeStorage": "0",
        "userId": "78",
        "systemFlag": "2",
        "nickName": "王白玄龟",
      },
      {

        "createTime": "2025-11-27 11:17:02",
        "updateTime": "2025-11-28 11:31:07",
        "id": "1993881722078064641",
        "name": "76d64eac",
        "roleName": "小云",
        "thumbnailPath": "/pub-nuwa/1/figure/1955077707972714497/69c52b2e195444aa973cdf1a94286f69.jpg",
        "status": "2",
        "knowledgeStorage": "0",
        "userId": "78",
        "systemFlag": "2",
        "nickName": "王白玄龟"
      
      }
    ],
    "total": 4,
    "size": 2,
    "current": 1,
    "pages": 2
  }
}

Request parameter description

Name	Type	Required	Description
type	Integer	Yes	Querytype（1：platformdigital human，2：Description digital human）
current	Long	Yes	current page（page 1）
size	Long	Yes	Description
name	String	No	agentname
age	String	No	age（1:Description，2：Chinese Description，3：Description，4：Description）
sex	String	No	gender（1：male，2：female，3：neutral）

Response parameter description

Name	Type	Description
code	Integer	0: success; non-zero: failure
msg	String	Description
data	Object	Description
records	Array	agentList
current	Long	current page（Description1 Description）
size	Long	Description
total	Long	total records
pages	Long	total pages
agent Description
id	Long	agent ID
name	String	agentname
status	String	agentstatus（0：incomplete，1：creating，2：created,3:creation failed）
systemFlag	String	agentpermission（1：public，2：private）
userId	Long	user ID
nickName	String	user Description
knowledgeStorage	Long	Description（unit：Byte）
roleName	String	rolename
thumbnailPath	String	thumbnailpath
applicationScenariosName	String	application scenarioname
createTime	LocalDateTime	created at
updateTime	LocalDateTime	updated at

8.5 Role list

GET /web/role/list

Request example

示例

await sdk.roleList({ roleName: "", current: 1, size: 10 });

import com.nuwaai.sdk.NuwaAIClient;
import com.nuwaai.sdk.NuwaCallback;
import com.nuwaai.sdk.model.PageData;
import com.nuwaai.sdk.model.RoleRecord;

// Parameter order: roleName, size, current
NuwaAIClient.getInstance().getDigitalUserManager().getRoleList("", 10, 1, new NuwaCallback<PageData<RoleRecord>>() {
    @Override
    public void onSuccess(PageData<RoleRecord> data) { }

    @Override
    public void onFailure(int code, String message) { }
});

await sdk.roleList({ roleName: '', current: 1, size: 10 });

Response example

{
  "code": 0,
  "msg": null,
  "data": {
    "records": [
      {      
        "createTime": "2025-11-08 20:12:13",
        "updateTime": "2025-11-08 20:12:13",
        "roleId": "1987131038946664449",
        "roleName": "直播带货11",
        "applicationScenarios": "0",
        "language": "1",
        "specialty": "",
        "personality": "",
        "languageStyle": "",
        "goal": "",
        "workThinking": "",
        "modelName": "",

        "skillList": [
          {       
            "skillName": "PPT演讲",    
            "enabled": "1"
          }
        ],
        "nickName": null
      },
      {
      
        "createTime": "2025-11-03 12:06:25",
        "updateTime": "2025-11-08 20:12:03",
        "roleId": "1985196841234313218",
        "roleName": "直播带货",
        "applicationScenarios": "0",
        "language": "0",
        "specialty": "11",
        "personality": "22",
        "languageStyle": "33",
        "goal": "44",
        "workThinking": "55",
        "modelName": "66",
        "description": "77",
        "skillList": [
          {
            "skillName": "知识问答",
            "enabled": "1"
          },
          {
            "skillName": "PPT演讲",
            "enabled": "1"
          },
          {
            "skillName": "文件发送",
            "enabled": "1"
          },
          {
            "skillName": "福利设定",
            "enabled": "1"
          }
        ],
        "nickName": null
      }
    ],
    "total": 22,
    "size": 2,
    "current": 1,
    "pages": 11
  }
}

Request parameter description

Name	Type	Required	Description
current	Long	Yes	current page（page 1）
size	Long	Yes	Description
roleName	String	No	rolename

Response parameter description

Name	Type	Description
code	Integer	0: success; non-zero: failure
msg	String	Description
data	Object	Description
records	Array	roleList
current	Long	current page（Description1 Description）
size	Long	Description
total	Long	total records
pages	Long	total pages
role Description
roleId	Long	roleID
roleName	String	rolename
language	String	Description（0:DescriptionChinese,1:Description）
specialty	String	background
personality	String	Description
languageStyle	String	language style
goal	String	conversation goal
nickName	String	Create Description
applicationScenarios	String	application scenarioID
workThinking	String	Description
modelName	String	role Description name
createTime	LocalDateTime	created at
updateTime	LocalDateTime	updated at
skillList	Array	skillList
skill Description
skillName	String	skillname
enabled	String	Enabled（1：enabled，0：disabled）

9. Knowledge base CRUD API

9.1 Add document metadata

POST /web/document/4.0/add

Request example

示例

await sdk.addDocumentInfo({ fileSize: 27451057, digitalUserId: 199..., originalFilename: "demo.pdf" });

import com.nuwaai.sdk.NuwaAIClient;
import com.nuwaai.sdk.NuwaCallback;
import com.nuwaai.sdk.model.AddDocumentRequest;
import com.nuwaai.sdk.model.AddDocumentResult;

AddDocumentRequest req = new AddDocumentRequest();
req.setFileSize(27451057);
req.setDigitalUserId(1996572693326966785L); // Example: replace with the actual agent ID
req.setOriginalFilename("demo.pdf");
NuwaAIClient.getInstance().getDocumentManager().addDocument(req, new NuwaCallback<AddDocumentResult>() {
    @Override
    public void onSuccess(AddDocumentResult data) { }

    @Override
    public void onFailure(int code, String message) { }
});

await sdk.documentAdd4({
  fileSize: 27451057,
  digitalUserId: 1996572693326966785,
  originalFilename: 'demo.pdf'
});

Response example

{
    "code": 0,
    "msg": null,
    "data": {
        "documentId": "7131",
        "preUploadUrl": "https://nuwa-ai.oss-cn-shenzhen.aliyuncs.com/54/knowledge/2034192955560034305/f03fccd5e1ef41d3a36ad7c2473222ad.pptx?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20260320T014105Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Credential=LTAI5tHbpo83YpipHibjKr4L%2F20260320%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=7ad481ed6e4f0411d1ad8915270e0f2094e813febc358258af9162c649951389"
    }
}

Request parameter description

Name	Type	Required	Description
fileSize	Long	Yes	file Description（unit：Byte）
digitalUserId	Long	Yes	digital humanID
originalFilename	String	Yes	original filename Description
description	String	No	description

Response parameter description

Name	Type	Description
code	Integer	0: success; non-zero: failure
msg	String	Description
data	Object	Description
documentId	Long	document ID
preUploadUrl	String	DescriptionURL

9.2 Import a website

POST /web/document/importWebsite

Request example

示例

await sdk.importWebsite("www.nuwaai.com", 199...);

import com.nuwaai.sdk.NuwaAIClient;
import com.nuwaai.sdk.NuwaCallback;
import com.nuwaai.sdk.model.ImportWebsiteRequest;

ImportWebsiteRequest req = new ImportWebsiteRequest();
req.setUrl("www.nuwaai.com");
req.setDigitalUserId(1996572693326966785L); // Example: replace with the actual agent ID
NuwaAIClient.getInstance().getDocumentManager().importWebsite(req, new NuwaCallback<String>() {
    @Override
    public void onSuccess(String documentId) { }

    @Override
    public void onFailure(int code, String message) { }
});

await sdk.documentImportWebsite({
  url: 'www.nuwaai.com',
  digitalUserId: 1996572693326966785
});

Response example

{
    "code": 0,
    "msg": null,
    "data": "7133"
}

Request parameter description

Name	Type	Required	Description
url	String	Yes	DescriptionURL
digitalUserId	Long	Yes	agent ID

Response parameter description

Name	Type	Description
code	Integer	0: success; non-zero: failure
msg	String	Description
data	Long	document ID

9.3 Upload a knowledge-base document

PUT {preUploadUrl}

Request example

示例

const addRes = await sdk.addDocumentInfo({
  fileSize: file.size,
  digitalUserId,
  originalFilename: file.name,
  description:  ""
});
await sdk.uploadKnowledgeByPreSignedUrl(addRes.data.preUploadUrl, file);

import com.nuwaai.sdk.NuwaAIClient;
import com.nuwaai.sdk.NuwaCallback;
import com.nuwaai.sdk.model.AddDocumentRequest;
import com.nuwaai.sdk.model.AddDocumentResult;

import java.io.File;

File file = new File("/path/to/demo.pdf");
long digitalUserId = 1996572693326966785L;

AddDocumentRequest addReq = new AddDocumentRequest();
addReq.setFileSize(file.length());
addReq.setDigitalUserId(digitalUserId);
addReq.setOriginalFilename(file.getName());
addReq.set Description("");

NuwaAIClient.getInstance().getDocumentManager().addDocument(addReq, new NuwaCallback<AddDocumentResult>() {
    @Override
    public void onSuccess(AddDocumentResult data) {
        String path = file.getAbsolutePath();
        String uploadUrl = data.getPreUploadUrl();
        NuwaAIClient.getInstance().getDocumentManager().uploadDocumentFile(path, uploadUrl, new NuwaCallback<Void>() {
            @Override
            public void onSuccess(Void unused) { }

            @Override
            public void onFailure(int code, String message) { }
        });
    }

    @Override
    public void onFailure(int code, String message) { }
});

const addRes = await sdk.documentAdd4({
  fileSize,
  digitalUserId,
  originalFilename: fileName,
  description:  ''
});
await sdk.uploadKnowledgeFile(addRes.preUploadUrl, tempFilePath);

Request parameter description

Name	Type	Required	Description
preUploadUrl	String	Yes	DescriptionURL，Adddocument Description，DescriptionURLFile

9.4 Delete a knowledge-base document

POST /web/document/removeV2

Request example

示例

await sdk.removeDocuments({ digitalUserId: 199..., docIds: [7131] });

import com.nuwaai.sdk.NuwaAIClient;
import com.nuwaai.sdk.NuwaCallback;
import com.nuwaai.sdk.model.RemoveDocumentRequest;

import java.util.Arrays;

RemoveDocumentRequest req = new RemoveDocumentRequest();
req.setDigitalUserId(1996572693326966785L);
req.setDocIds(Arrays.asList(7131L));
NuwaAIClient.getInstance().getDocumentManager().removeDocument(req, new NuwaCallback<Object>() {
    @Override
    public void onSuccess(Object data) { }

    @Override
    public void onFailure(int code, String message) { }
});

await sdk.documentRemoveV2({ digitalUserId: 1996572693326966785, docIds: [7131] });

Response example

{
    "code": 0,
    "msg": null,
    "data": null
}

Request parameter description

Name	Type	Required	Description
digitalUserId	Long	Yes	agent ID
docIds	Long[]	Yes	document IDDescription

Response parameter description

Name	Type	Description
code	Integer	0: success; non-zero: failure
msg	String	Description
data	Object	Description

9.5 Update a knowledge-base document

POST /web/document/modifyV2

Request example

示例

await sdk.modifyDocument(7131, 0, file);

import com.nuwaai.sdk.NuwaAIClient;
import com.nuwaai.sdk.NuwaCallback;

import java.io.File;

File file = new File("/path/to/demo.pdf");
NuwaAIClient.getInstance().getDocumentManager().modifyDocument(7131L, 0, file, new NuwaCallback<Object>() {
    @Override
    public void onSuccess(Object data) { }

    @Override
    public void onFailure(int code, String message) { }
});

await sdk.documentModifyV2('7131', 0, tempFilePath);

Response example

{
    "code": 0,
    "msg": null,
    "data": null
}

Request parameter description

Name	Type	Required	Description
file	MultipartFile	Yes	Description document
docId	Long	Yes	document ID
editType	Integer	Yes	document type（0:Description/Description，1：Description document，2：ppt,3: URL）

Response parameter description

Name	Type	Description
code	Integer	0: success; non-zero: failure
msg	String	Description
data	Object	Description

9.6 View a knowledge-base document

GET /web/document/getDocumentById

Request example

示例

await sdk.getDocumentById("7131");

import com.nuwaai.sdk.NuwaAIClient;
import com.nuwaai.sdk.NuwaCallback;
import com.nuwaai.sdk.model.DocumentRecord;

NuwaAIClient.getInstance().getDocumentManager().getDocument("7131", new NuwaCallback<DocumentRecord>() {
    @Override
    public void onSuccess(DocumentRecord data) { }

    @Override
    public void onFailure(int code, String message) { }
});

await sdk.getDocumentById('7131');

Response example

{
    "code": 0,
    "msg": null,
    "data": {
        "id": "7131",
        "analysisUrl": "4000170/knowledge/1996852095362637826/b6aa31c01ab843f5bd3e9b309e77a294.md",
        "filePath": "4000170/knowledge/1996852095362637826/f53c7e92d8aa48e58814dfd93e47f79b.pdf",
        "type": "pdf",
        "original": "Nuwaai介绍手册2505-邦彦技术.pdf",
        "sendPermission": "1",
        "playPermission": "1",
        "description": null,
        "category": 1,
        "createTime": "2025-12-06 11:27:11",
        "updateTime": "2025-12-06 16:03:09",
        "status": "1",
        "reason": null
    }
}

Request parameter description

Name	Type	Required	Description
docId	String	Yes	document ID

Response parameter description

Name	Type	Description
code	Integer	0: success; non-zero: failure
msg	String	Description
data	Object	Description
Description
id	Long	document ID
analysisUrl	String	FileURL
type	String	document type
original	String	original filename
sendPermission	String	Description permission(0:off,1:on)
playPermission	String	Description permission(0:off,1:on)
description	String	description
category	String	document type（0:Description/Description，1：Description document，2：ppt,3: URL）
status	String	status(0:DescriptionChinese,1:success,2:failure)
reason	String	failure Description
createTime	LocalDateTime	uploaded at
updateTime	LocalDateTime	updated at

9.7 Knowledge-base document list

GET /web/document/pageV2

Request example

示例

await sdk.pageDocuments({ digitalUserId: 199..., current: 1, size: 10 });

import com.nuwaai.sdk.NuwaAIClient;
import com.nuwaai.sdk.NuwaCallback;
import com.nuwaai.sdk.model.DocumentRecord;
import com.nuwaai.sdk.model.PageData;

// Parameter order: digitalUserId, size, current, type, documentName (the last two are optional)
NuwaAIClient.getInstance().getDocumentManager().getDocumentPage(
    1996572693326966785L, 10, 1, null, null,
    new NuwaCallback<PageData<DocumentRecord>>() {
        @Override
        public void onSuccess(PageData<DocumentRecord> data) { }

        @Override
        public void onFailure(int code, String message) { }
    });

await sdk.documentPageV2({
  digitalUserId: 1996572693326966785,
  current: 1,
  size: 10
});

Response example

{
    "code": 0,
    "msg": null,
    "data": {
        "records": [
            {
                "id": "7130",
                "analysisUrl": "4000170/knowledge/1996852095362637826/fb3187e71a5944bba8bd9e4e75b4b65a.md",
                "filePath": "www.nuwaai.com",
                "type": "web",
                "original": "www.nuwaai.com",
                "sendPermission": "1",
                "playPermission": "1",
                "description": null,
                "category": 3,
                "createTime": "2025-12-06 11:17:59",
                "updateTime": "2025-12-06 11:18:42",
                "status": "1",
                "reason": null
            }
        ],
        "total": 1,
        "size": 10,
        "current": 1,
        "pages": 1
    }
}

Request parameter description

Name	Type	Required	Description
digitalUserId	Long	Yes	digital humanID
current	Long	Yes	current page(Description1 Description)
size	Long	Yes	Description
type	String	No	document type
documentName	String	No	documentname

Response parameter description

Name	Type	Description
code	Integer	0: success; non-zero: failure
msg	String	Description
data	Object	Description
Object properties
id	Long	document ID
analysisUrl	String	FileURL
filePath	String	Description documentpath
type	String	document type
original	String	original filename
sendPermission	String	Description permission(0:off,1:on)
playPermission	String	Description permission(0:off,1:on)
description	String	description
category	String	document type（0:Description/Description，1：Description document，2：ppt,3: URL）
status	String	status(0:DescriptionChinese,1:success,2:failure)
reason	String	failure Description
createTime	LocalDateTime	uploaded at
updateTime	LocalDateTime	updated at

10. Talent creation API

10.1 Create talent

POST /web/talent/create

Request example

示例

await sdk.createTalent("1");

import com.nuwaai.sdk.NuwaAIClient;
import com.nuwaai.sdk.NuwaCallback;
import com.nuwaai.sdk.model.CreateTalentRequest;
import com.nuwaai.sdk.model.TalentDetail;

CreateTalentRequest req = new CreateTalentRequest();
req.setType("1");
NuwaAIClient.getInstance().getTalentManager().create(req, new NuwaCallback<TalentDetail>() {
    @Override
    public void onSuccess(TalentDetail data) { }

    @Override
    public void onFailure(int code, String message) { }
});

await sdk.talentCreate({ type: '1' });

Response example

{
    "code": 0,
    "msg": null,
    "data": {
        "createBy": "18672393036",
        "createTime": "2025-12-12 09:41:40",
        "updateBy": "18672393036",
        "updateTime": "2025-12-12 09:41:40",
        "delFlag": "0",
        "id": "1999293545418145794",
        "name": "e0bc2e17",
        "type": "1",
        "client": "pc",
        "channel": "natural",
        "userId": "47",
        "systemFlag": "2"
       
    }
}

Request parameter description

Name	Type	Required	Description
type	String	Yes	talenttype(1:Description，2:Description)

Response parameter description

Name	Type	Description
code	Integer	0: success; non-zero: failure
msg	String	Description
data	Object	Description
talent Description
createBy	String	Create Description
createTime	LocalDateTime	created at
updateBy	String	Description
updateTime	LocalDateTime	updated at
id	Long	talent ID
name	String	talentname
type	String	talenttype(1:Description，2:Description)
client	String	client
channel	String	channel
userId	Long	user ID
systemFlag	String	talentpermission（1：public，2：private）

10.2 Update a talent

PUT /web/talent/edit

Request example

示例

await sdk.editTalent({ id: "199...", ... });

import com.nuwaai.sdk.NuwaAIClient;
import com.nuwaai.sdk.NuwaCallback;
import com.nuwaai.sdk.model.EditTalentRequest;

EditTalentRequest req = new EditTalentRequest();
req.setId("199...");
// Set name, type, videoPath, subtitlesStatus, and other fields as needed
NuwaAIClient.getInstance().getTalentManager().edit(req, new NuwaCallback<Boolean>() {
    @Override
    public void onSuccess(Boolean data) { }

    @Override
    public void onFailure(int code, String message) { }
});

await sdk.talentEdit({ id: '199...', /* name, type, videoPath, etc. */ });

Response example

{
    "code": 0,
    "msg": null,
    "data": true
}

Request parameter description

Name	Type	Required	Description
id	Long	Yes	talentID
name	String	Yes	talentname
type	String	Yes	talenttype(1:Description，2:Description)
videoPath	String	Yes	Path
style	String	No	style
songId	Long	No	Model ID
songPath	String	No	Path
songName	String	No	Description name
songFrom	String	No	Description(1:platform,2:Description，3：local upload)
lyric	String	No	File path
subtitlesStatus	String	Yes	Status（0：Description on，1：on）
acappella	String	No	Description voicepath

Response parameter description

Name	Type	Description
code	Integer	0: success; non-zero: failure
msg	String	Description
data	Boolean	true:success，false:failure

10.3 Delete a talent

DELETE /web/talent/delete/{id}

Request example

示例

await sdk.deleteTalent("199...");

import com.nuwaai.sdk.NuwaAIClient;
import com.nuwaai.sdk.NuwaCallback;

NuwaAIClient.getInstance().getTalentManager().delete("199...", new NuwaCallback<Boolean>() {
    @Override
    public void onSuccess(Boolean data) { }

    @Override
    public void onFailure(int code, String message) { }
});

await sdk.talentDelete('199...');

Response example

{
    "code": 0,
    "msg": null,
    "data": true
}

Request parameter description

Name	Type	Required	Description
id	Long	Yes	talent ID

Response parameter description

Name	Type	Description
code	Integer	0: success; non-zero: failure
msg	String	Description
data	Booelan	true:success，false:failure

10.4 Generate a talent video

POST /web/talent/preview

Request example

示例

await sdk.previewTalent({ id: "199...", ... });

import com.nuwaai.sdk.NuwaAIClient;
import com.nuwaai.sdk.NuwaCallback;
import com.nuwaai.sdk.model.PreviewTalentRequest;

PreviewTalentRequest req = new PreviewTalentRequest();
req.setId("199...");
// Set name, type, videoPath, speechText, voiceType, modeName, and other fields as needed
NuwaAIClient.getInstance().getTalentManager().preview(req, new NuwaCallback<String>() {
    @Override
    public void onSuccess(String requestId) { }

    @Override
    public void onFailure(int code, String message) { }
});

await sdk.talentPreview({ id: '199...', /* name, type, videoPath, speechText, etc. */ });

Response example

{
    "code": 0,
    "msg": null,
    "data": "a516fb5714484f14bfb4723bbaa9dc0d"
}

Request parameter description

Name	Type	Required	Description
id	Long	Yes	talentID
name	String	Yes	talentname
type	String	Yes	talenttype(1:Description，2:Description)
videoPath	String	Yes	Path
style	String	No	style
songId	Long	No	Model ID
songPath	String	No	Path，Description，Description
songName	String	No	Description name
songFrom	String	No	Description(1:platform,2:Description，3：local upload)
lyric	String	No	File path,Description，Description
subtitlesStatus	String	Yes	Status（0：Description on，1：on）
acappella	String	Yes	Description voicepath，Description，Description
voiceType	String	No	voice type(3:Description,5:Description),Description，Description
modeName	String	No	Voice name，Description，Description
speechText	String	No	Description,Description，Description

Response parameter description

Name	Type	Description
code	Integer	0: success; non-zero: failure
msg	String	Description
data	String	request ID,DescriptionQuerytalentYes Description

10.5 Talent list

POST /web/talent/talentList

Request example

示例

await sdk.talentList({ current: 1, size: 10, systemFlag: "2" });

import com.nuwaai.sdk.NuwaAIClient;
import com.nuwaai.sdk.NuwaCallback;
import com.nuwaai.sdk.model.PageData;
import com.nuwaai.sdk.model.TalentListRequest;
import com.nuwaai.sdk.model.TalentRecord;

TalentListRequest req = new TalentListRequest();
req.setCurrent(1);
req.setSize(10);
req.setSystemFlag("2");
NuwaAIClient.getInstance().getTalentManager().getList(req, new NuwaCallback<PageData<TalentRecord>>() {
    @Override
    public void onSuccess(PageData<TalentRecord> data) { }

    @Override
    public void onFailure(int code, String message) { }
});

await sdk.talentList({ current: 1, size: 10, systemFlag: '2' });

Response example

{
    "code": 0,
    "msg": null,
    "data": {
        "records": [
          
{  
    "createTime": "2025-12-01 16:02:11",
    "updateTime": "2025-12-01 18:01:55",
    "id": "1995403034264707074",
    "name": "b3baac21",
    "type": "1",
    "thumbnailPath": "/pub-nuwa/4000170/talent/1995403034264707074/0f5bf4fd6e934ab7b3fbdef049505b6c.jpg",
    "preStatus": "0",
    "storage": "4906412",
    "userId": "4000170",
    "nickName": "林墨麟" 
},
{  
    "createTime": "2025-12-01 09:16:14",
    "updateTime": "2025-12-01 09:20:44",
    "id": "1995300872645877762",
    "name": "青春旋律",
    "type": "1",
    "thumbnailPath": "/pub-nuwa/4000170/talent/1995300872645877762/df380a72f7ef4b4bb513ced80e7c544c.jpg",
    "preStatus": "2",
    "storage": "41966629", 
    "userId": "4000170",
    "nickName": "林墨麟"
}
        ],
        "total": 22,
        "size": 2,
        "current": 1,
        "pages": 11
    }
}

Request parameter description

Name	Type	Required	Description
current	Long	Yes	current page
size	Long	Yes	Description
systemFlag	String	Yes	permission（1：public，2：private）
name	String	No	talentname
type	String	No	talenttype(1:Description，2:Description)

Response parameter description

Name	Type	Description
code	Integer	0: success; non-zero: failure
msg	String	Description
data	Object	Description
records	Array	talentList
current	Long	current page（Description1 Description）
size	Long	Description
total	Long	total records
pages	Long	total pages
talent Description
id	Long	talent ID
name	String	talentname
type	String	talenttype(1:Description，2:Description)
thumbnailPath	String	Thumbnail path
storage	Long	storage size（unit：Byte）
userId	Long	user ID
nickName	String	user Description
createTime	LocalDateTime	created at
updateTime	LocalDateTime	updated at

10.6 Talent details

GET /web/talent/detail/{id}

Request example

示例

await sdk.talentDetail("199...");

import com.nuwaai.sdk.NuwaAIClient;
import com.nuwaai.sdk.NuwaCallback;
import com.nuwaai.sdk.model.TalentDetail;

NuwaAIClient.getInstance().getTalentManager().getDetail("199...", new NuwaCallback<TalentDetail>() {
    @Override
    public void onSuccess(TalentDetail data) { }

    @Override
    public void onFailure(int code, String message) { }
});

await sdk.talentDetail('199...');

Response example

{
    "code": 0,
    "msg": null,
    "data": {
      
        "createTime": "2025-11-25 14:29:56",
        "updateTime": "2025-11-25 21:18:30",
        "id": "1993205490860269569",
        "name": "A0012",
        "type": "2",
        "previewPath": "/nuwa-ai/talent/1993205490860269569/video-3f6bacb0400b403d98e1a6b70df7821b.mp4",
        "videoPath": "/nuwa-ai/4000170/talent/1993205490860269569/d6056ccbea144ffaaa2e1cbb6f25b7b7.mp4",
        "thumbnailPath": "/pub-nuwa/4000170/talent/1993205490860269569/14b459fe4ca344f7ba05ef1c68d137bb.jpg",
        "style": "现代",
        "songId": "74",
        "songPath": "/pub-nuwa/admin/music/8c95aa1cee1d4c89b328478b3b50e269.mp3",
        "songFrom": "1",
        "songName": "假如给我三天光明",
        "songVolume": 0.5,
        "subtitlesStatus": "0",
        "labiate": 1.5,
        "acappella": null,
        "lyric": null,
        "soundPath": "/pub-nuwa/admin/audio/571901a4f8974cedafc081c9ce5c9006.wav",
        "soundName": "新闻女主播",
        "speedSpeech": 1,
        "speechText": ""
        "voiceType": "5",
        "modeName": "index:新闻女主播__d67c8ff2",
        "preStatus": "2",
        "storage": "60905886",
        "client": "pc",
        "channel": "natural",
        "userId": "4000170",
        "systemFlag": "2"
    }
}

Request parameter description

Name	Type	Required	Description
id	Long	Yes	talent ID

Response parameter description

Name	Type	Description
code	Integer	0: success; non-zero: failure
msg	String	Description
data	Object	Description
id	Long	talent ID
name	String	talentname
type	String	talenttype(1:Description，2:Description)
previewPath	String	Description talentPath
videoPath	String	Path
thumbnailPath	String	Thumbnail path
style	String	style
songId	Long	Model ID
songPath	String	Path
songFrom	String	Description(1:platform,2:Description，3：local upload)
songName	String	Description name
songVolume	BigDecimal	Description volume
subtitlesStatus	String	Status（0：Description on，1：on）
labiate	BigDecimal	Description
acappella	String	Description voicepath
lyric	String	File path
soundPath	String	Description voicepath
soundName	String	DescriptionVoice name
speedSpeech	BigDecimal	speaking rate
speechText	String	Description
voiceType	String	voice type（3:Description，5：Description）
modeName	String	Voice name
preStatus	String	talent DescriptionURLstatus（1：creating,2:created，3：creation failed）
actions	String	action list
storage	Long	storage size（unit：Byte）
client	String	client
channel	String	channel
userId	Long	user ID
systemFlag	String	permission（1：public，2：private）