feat: voiceclone implement comprehensive voice cloning service with full API support (#38)

Co-authored-by: tomsun28 <tomsun28@outlook.com>

Author: Lighthousexx

core/src/main/java/ai/z/openapi/AbstractAiClient.java

@@ -23,6 +23,8 @@
 import ai.z.openapi.service.videos.VideosServiceImpl;
 import ai.z.openapi.service.assistant.AssistantService;
 import ai.z.openapi.service.assistant.AssistantServiceImpl;
+import ai.z.openapi.service.voiceclone.VoiceCloneService;
+import ai.z.openapi.service.voiceclone.VoiceCloneServiceImpl;
 import ai.z.openapi.core.config.ZaiConfig;
 import ai.z.openapi.core.model.BiFlowableClientResponse;
 import ai.z.openapi.core.model.ClientRequest;
@@ -98,6 +100,9 @@ public abstract class AbstractAiClient extends AbstractClientBaseService {
 	/** Assistant service for AI assistant functionality */
 	private AssistantService assistantService;
 
+	/** Voice clone service for voice cloning operations */
+	private VoiceCloneService voiceCloneService;
+
 	/**
 	 * Constructs a new AbstractAiClient with the specified configuration.
 	 * @param config the configuration object containing API keys, timeouts, and other
@@ -238,6 +243,18 @@ public synchronized AssistantService assistants() {
 		return assistantService;
 	}
 
+	/**
+	 * Returns the voice clone service for voice cloning operations. This service handles
+	 * voice cloning creation, deletion, and listing functionality.
+	 * @return the VoiceCloneService instance (lazily initialized)
+	 */
+	public synchronized VoiceCloneService voiceClone() {
+		if (voiceCloneService == null) {
+			this.voiceCloneService = new VoiceCloneServiceImpl(this);
+		}
+		return voiceCloneService;
+	}
+
 	// ==================== Utility Methods ====================
 
 	/**

core/src/main/java/ai/z/openapi/api/voiceclone/VoiceCloneApi.java

@@ -0,0 +1,66 @@
+package ai.z.openapi.api.voiceclone;
+
+import ai.z.openapi.service.voiceclone.VoiceCloneRequest;
+import ai.z.openapi.service.voiceclone.VoiceCloneResult;
+import ai.z.openapi.service.voiceclone.VoiceDeleteRequest;
+import ai.z.openapi.service.voiceclone.VoiceDeleteResult;
+import ai.z.openapi.service.voiceclone.VoiceListResult;
+import io.reactivex.rxjava3.core.Single;
+import retrofit2.http.Body;
+import retrofit2.http.GET;
+import retrofit2.http.Header;
+import retrofit2.http.POST;
+import retrofit2.http.Query;
+
+/**
+ * Voice Clone API for voice cloning and management operations. Provides endpoints for
+ * creating voice clones from audio samples, deleting existing voice clones, and listing
+ * available voice clones.
+ */
+public interface VoiceCloneApi {
+
+	/**
+	 * Creates a new voice clone from provided audio sample and parameters. Uses advanced
+	 * neural voice cloning technology to generate a custom voice model that can
+	 * synthesize speech matching the characteristics of the provided sample.
+	 * @param request voice clone creation parameters including voice name, sample text,
+	 * target text, and audio file reference
+	 * @return voice clone creation result with voice ID and preview file information
+	 */
+	@POST("voice/clone")
+	Single<VoiceCloneResult> cloneVoice(@Body VoiceCloneRequest request);
+
+	/**
+	 * Deletes an existing voice clone by voice ID. Permanently removes the voice model
+	 * and associated data from the system. This operation cannot be undone.
+	 * @param request voice deletion parameters containing the voice ID to delete
+	 * @return voice deletion result with confirmation and deletion timestamp
+	 */
+	@POST("voice/delete")
+	Single<VoiceDeleteResult> deleteVoice(@Body VoiceDeleteRequest request);
+
+	/**
+	 * Retrieves a list of available voice clones with optional filtering. Returns
+	 * metadata and details for voice clones including voice IDs, names, types, download
+	 * URLs, and creation timestamps.
+	 * @param voiceType optional voice type filter
+	 * @param voiceName optional voice name filter
+	 * @return list of voice clone data with comprehensive metadata
+	 */
+	@GET("voice/list")
+	Single<VoiceListResult> listVoices(@Query("voiceType") String voiceType, @Query("voiceName") String voiceName);
+
+	/**
+	 * Retrieves a list of available voice clones with optional filtering and Request-Id
+	 * header. Returns metadata and details for voice clones including voice IDs, names,
+	 * types, download URLs, and creation timestamps.
+	 * @param voiceType optional voice type filter
+	 * @param voiceName optional voice name filter
+	 * @param requestId unique request identifier for tracking and monitoring
+	 * @return list of voice clone data with comprehensive metadata
+	 */
+	@GET("voice/list")
+	Single<VoiceListResult> listVoices(@Query("voiceType") String voiceType, @Query("voiceName") String voiceName,
+			@Header("Request-Id") String requestId);
+
+}

core/src/main/java/ai/z/openapi/service/file/UploadFilePurpose.java

@@ -2,7 +2,8 @@
 
 public enum UploadFilePurpose {
 
-	BATCH("batch"), FILE_EXTRACT("file-extract"), CODE_INTERPRETER("code-interpreter"), AGENT("agent");
+	BATCH("batch"), FILE_EXTRACT("file-extract"), CODE_INTERPRETER("code-interpreter"), AGENT("agent"),
+	VOICE_CLONE_INPUT("voice-clone-input");
 
 	private final String value;
 

core/src/main/java/ai/z/openapi/service/voiceclone/VoiceCloneRequest.java

@@ -0,0 +1,34 @@
+package ai.z.openapi.service.voiceclone;
+
+import ai.z.openapi.core.model.ClientRequest;
+import ai.z.openapi.service.CommonRequest;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+
+/**
+ * Request parameters for voice cloning API. This class contains all the necessary
+ * parameters for voice cloning operations, including voice name, sample audio text,
+ * target preview text, and audio file information.
+ */
+@EqualsAndHashCode(callSuper = true)
+@Data
+public class VoiceCloneRequest extends CommonRequest implements ClientRequest<VoiceCloneRequest> {
+
+	/** Voice name */
+	@JsonProperty("voice_name")
+	private String voiceName;
+
+	/** Text content corresponding to the sample audio */
+	@JsonProperty("voice_text_input")
+	private String voiceTextInput;
+
+	/** Target text for preview audio */
+	@JsonProperty("voice_text_output")
+	private String voiceTextOutput;
+
+	/** File ID of the audio file */
+	@JsonProperty("file_id")
+	private String fileId;
+
+}

core/src/main/java/ai/z/openapi/service/voiceclone/VoiceCloneResponse.java

@@ -0,0 +1,35 @@
+package ai.z.openapi.service.voiceclone;
+
+import ai.z.openapi.core.model.ClientResponse;
+import ai.z.openapi.service.batches.BatchPage;
+import ai.z.openapi.service.model.ChatError;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+import java.io.Serializable;
+
+/**
+ * Response wrapper for voice cloning API operations. This class contains the standard
+ * response structure including status code, message, success flag, result data, and error
+ * information.
+ */
+@Data
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+public class VoiceCloneResponse implements ClientResponse<VoiceCloneResult> {
+
+	private int code;
+
+	private String msg;
+
+	private boolean success;
+
+	private VoiceCloneResult data;
+
+	private ChatError error;
+
+}

core/src/main/java/ai/z/openapi/service/voiceclone/VoiceCloneResult.java

@@ -0,0 +1,31 @@
+package ai.z.openapi.service.voiceclone;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+/**
+ * Result data for voice cloning operations. This class contains the voice cloning result
+ * information including voice ID, audio file ID, and file purpose.
+ */
+@Data
+@Builder
+@AllArgsConstructor
+@NoArgsConstructor
+public class VoiceCloneResult {
+
+	/** Voice ID */
+	@JsonProperty("voice_id")
+	private String voiceId;
+
+	/** Audio preview file ID */
+	@JsonProperty("file_id")
+	private String fileId;
+
+	/** File purpose */
+	@JsonProperty("file_purpose")
+	private String filePurpose;
+
+}

core/src/main/java/ai/z/openapi/service/voiceclone/VoiceCloneService.java

@@ -0,0 +1,32 @@
+package ai.z.openapi.service.voiceclone;
+
+/**
+ * Voice clone service interface for voice cloning operations. This service provides
+ * methods for creating, deleting, and listing voice clones.
+ */
+public interface VoiceCloneService {
+
+	/**
+	 * Creates a new voice clone based on the provided audio sample and parameters.
+	 * @param request the voice clone creation request containing voice name, sample audio
+	 * text, target text, and audio file information
+	 * @return VoiceCloneResponse containing the voice clone result and metadata
+	 */
+	VoiceCloneResponse cloneVoice(VoiceCloneRequest request);
+
+	/**
+	 * Deletes an existing voice clone by voice ID.
+	 * @param request the voice deletion request containing the voice ID to delete
+	 * @return VoiceDeleteResponse containing the deletion result and timestamp
+	 */
+	VoiceDeleteResponse deleteVoice(VoiceDeleteRequest request);
+
+	/**
+	 * Retrieves a list of available voice clones with optional filtering.
+	 * @param request the voice list request containing optional voice type and name
+	 * filters
+	 * @return VoiceListResponse containing the filtered list of voice data
+	 */
+	VoiceListResponse listVoice(VoiceListRequest request);
+
+}

core/src/main/java/ai/z/openapi/service/voiceclone/VoiceCloneServiceImpl.java

@@ -0,0 +1,78 @@
+package ai.z.openapi.service.voiceclone;
+
+import ai.z.openapi.AbstractAiClient;
+import ai.z.openapi.api.voiceclone.VoiceCloneApi;
+import ai.z.openapi.service.deserialize.MessageDeserializeFactory;
+import ai.z.openapi.utils.RequestSupplier;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import lombok.extern.slf4j.Slf4j;
+
+/**
+ * Voice clone service implementation for voice cloning operations. This service provides
+ * methods for creating, deleting, and listing voice clones using the VoiceClone API
+ * endpoints.
+ */
+public class VoiceCloneServiceImpl implements VoiceCloneService {
+
+	protected static final ObjectMapper mapper = MessageDeserializeFactory.defaultObjectMapper();
+
+	private final AbstractAiClient zAiClient;
+
+	private final VoiceCloneApi voiceCloneApi;
+
+	public VoiceCloneServiceImpl(AbstractAiClient zAiClient) {
+		this.zAiClient = zAiClient;
+		this.voiceCloneApi = zAiClient.retrofit().create(VoiceCloneApi.class);
+	}
+
+	@Override
+	public VoiceCloneResponse cloneVoice(VoiceCloneRequest request) {
+		validateCreateVoiceParams(request);
+		RequestSupplier<VoiceCloneRequest, VoiceCloneResult> supplier = voiceCloneApi::cloneVoice;
+		return this.zAiClient.executeRequest(request, supplier, VoiceCloneResponse.class);
+	}
+
+	@Override
+	public VoiceDeleteResponse deleteVoice(VoiceDeleteRequest request) {
+		validateDeleteVoiceParams(request);
+		RequestSupplier<VoiceDeleteRequest, VoiceDeleteResult> supplier = voiceCloneApi::deleteVoice;
+		return this.zAiClient.executeRequest(request, supplier, VoiceDeleteResponse.class);
+	}
+
+	@Override
+	public VoiceListResponse listVoice(VoiceListRequest request) {
+		RequestSupplier<VoiceListRequest, VoiceListResult> supplier = (params) -> {
+			String voiceType = params != null ? params.getVoiceType() : null;
+			String voiceName = params != null ? params.getVoiceName() : null;
+			String requestId = params != null ? params.getRequestId() : "";
+
+			return voiceCloneApi.listVoices(voiceType, voiceName, requestId);
+		};
+		return this.zAiClient.executeRequest(request, supplier, VoiceListResponse.class);
+	}
+
+	private void validateCreateVoiceParams(VoiceCloneRequest request) {
+		if (request == null) {
+			throw new IllegalArgumentException("request cannot be null");
+		}
+		if (request.getVoiceName() == null || request.getVoiceName().trim().isEmpty()) {
+			throw new IllegalArgumentException("voice name cannot be null or empty");
+		}
+		if (request.getVoiceTextInput() == null || request.getVoiceTextInput().trim().isEmpty()) {
+			throw new IllegalArgumentException("voice text input cannot be null or empty");
+		}
+		if (request.getFileId() == null || request.getFileId().trim().isEmpty()) {
+			throw new IllegalArgumentException("file ID cannot be null or empty");
+		}
+	}
+
+	private void validateDeleteVoiceParams(VoiceDeleteRequest request) {
+		if (request == null) {
+			throw new IllegalArgumentException("request cannot be null");
+		}
+		if (request.getVoiceId() == null || request.getVoiceId().trim().isEmpty()) {
+			throw new IllegalArgumentException("voice ID cannot be null or empty");
+		}
+	}
+
+}

core/src/main/java/ai/z/openapi/service/voiceclone/VoiceData.java

@@ -0,0 +1,32 @@
+package ai.z.openapi.service.voiceclone;
+
+import com.fasterxml.jackson.annotation.JsonFormat;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import lombok.Data;
+
+import java.util.Date;
+
+/**
+ * Voice data entity containing voice information. This class contains voice details
+ * including voice ID, name, type, download URL, and creation time.
+ */
+@Data
+public class VoiceData {
+
+	@JsonProperty("voice_id")
+	private String voiceId;
+
+	@JsonProperty("voice_name")
+	private String voiceName;
+
+	@JsonProperty("voice_type")
+	private String voiceType;
+
+	@JsonProperty("download_url")
+	private String downloadUrl;
+
+	@JsonProperty("create_time")
+	@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
+	private Date createTime;
+
+}

core/src/main/java/ai/z/openapi/service/voiceclone/VoiceDeleteRequest.java

@@ -0,0 +1,20 @@
+package ai.z.openapi.service.voiceclone;
+
+import ai.z.openapi.core.model.ClientRequest;
+import ai.z.openapi.service.CommonRequest;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+
+/**
+ * Request parameters for voice deletion API. This class contains the necessary parameters
+ * for deleting a voice, specifically the voice ID.
+ */
+@EqualsAndHashCode(callSuper = true)
+@Data
+public class VoiceDeleteRequest extends CommonRequest implements ClientRequest<VoiceDeleteRequest> {
+
+	@JsonProperty("voice_id")
+	private String voiceId;
+
+}