GuideAPI Reference

Java

This guide helps you install and set up the Youzu Java API client.

RequirementsCopied!

  • Java 8 or higher
  • Maven, Gradle, or another build tool

InstallationCopied!

MavenCopied!

Add the following dependency to your pom.xml file:

<dependency>
    <groupId>ai.youzu</groupId>
    <artifactId>youzu-java</artifactId>
    <version>1.0.0</version>
</dependency>

GradleCopied!

Add the following to your build.gradle file:

implementation 'ai.youzu:youzu-java:1.0.0'

AuthenticationCopied!

Initialize the client with your secret key:

import ai.youzu.YouzuClient;
import ai.youzu.YouzuClientBuilder;

// Create a client with your secret key
YouzuClient youzu = YouzuClientBuilder.create()
    .setSecretKey("YOUR_SECRET_KEY")
    .build();

// You can also set optional configurations
YouzuClient customYouzu = YouzuClientBuilder.create()
    .setSecretKey("YOUR_SECRET_KEY")
    .setBaseUrl("https://platform-api.youzu.ai")  // Custom API endpoint
    .setConnectTimeout(30)               // Connect timeout in seconds
    .setReadTimeout(60)                  // Read timeout in seconds
    .build();

Basic UsageCopied!

Image GenerationCopied! 

import ai.youzu.YouzuClient;
import ai.youzu.YouzuClientBuilder;
import ai.youzu.model.generation.GenerationRequest;
import ai.youzu.model.generation.GenerationResponse;
import ai.youzu.exception.YouzuApiException;

public class GenerationExample {
    public static void main(String[] args) {
        YouzuClient youzu = YouzuClientBuilder.create()
            .setSecretKey("YOUR_SECRET_KEY")
            .build();
        
        try {
            // Create a generation request
            GenerationRequest request = new GenerationRequest.Builder()
                .setPrompt("a beautiful sunset over mountains")
                .setWidth(1024)
                .setHeight(1024)
                .setNumOutputs(1)
                .build();
            
            // Generate an image
            GenerationResponse response = youzu.generation().create(request);
            
            // Access the generated image URL
            String imageUrl = response.getUrl();
            System.out.println("Generated image available at: " + imageUrl);
            
        } catch (YouzuApiException e) {
            System.err.println("API Error: " + e.getMessage());
            System.err.println("Error Code: " + e.getErrorCode());
            System.err.println("Status: " + e.getHttpStatusCode());
        } catch (Exception e) {
            System.err.println("Error: " + e.getMessage());
        }
    }
}

Product SearchCopied! 

import ai.youzu.YouzuClient;
import ai.youzu.YouzuClientBuilder;
import ai.youzu.model.product.ProductSearchRequest;
import ai.youzu.model.product.ProductSearchResponse;
import ai.youzu.model.product.Product;
import ai.youzu.exception.YouzuApiException;

import java.io.File;

public class ProductSearchExample {
    public static void main(String[] args) {
        YouzuClient youzu = YouzuClientBuilder.create()
            .setSecretKey("YOUR_SECRET_KEY")
            .build();
        
        try {
            // Path to your image file
            File imageFile = new File("/path/to/image.jpg");
            
            // Create a product search request
            ProductSearchRequest request = new ProductSearchRequest.Builder()
                .setFile(imageFile)
                .build();
            
            // Search for products
            ProductSearchResponse response = youzu.products().search(request);
            
            // Display search results
            for (Product product : response.getProducts()) {
                System.out.println("Product: " + product.getName());
                System.out.println("Price: " + product.getPrice());
                System.out.println("URL: " + product.getUrl());
                System.out.println("-------------------");
            }
            
        } catch (YouzuApiException e) {
            System.err.println("API Error: " + e.getMessage());
        } catch (Exception e) {
            System.err.println("Error: " + e.getMessage());
        }
    }
}

Asynchronous UsageCopied!

The Youzu Java client also supports asynchronous operations:

import ai.youzu.YouzuClient;
import ai.youzu.YouzuClientBuilder;
import ai.youzu.model.generation.GenerationRequest;
import ai.youzu.model.generation.GenerationResponse;

import java.util.concurrent.CompletableFuture;

public class AsyncExample {
    public static void main(String[] args) {
        YouzuClient youzu = YouzuClientBuilder.create()
            .setSecretKey("YOUR_SECRET_KEY")
            .build();
        
        // Create a generation request
        GenerationRequest request = new GenerationRequest.Builder()
            .setPrompt("a beautiful sunset over mountains")
            .build();
        
        // Generate an image asynchronously
        CompletableFuture<GenerationResponse> future = youzu.generation().createAsync(request);
        
        // Add callbacks
        future.thenAccept(response -> {
            System.out.println("Generated image URL: " + response.getUrl());
        }).exceptionally(e -> {
            System.err.println("Error: " + e.getMessage());
            return null;
        });
        
        // Continue with other operations...
        System.out.println("Image generation in progress...");
    }
}

Error HandlingCopied!

The Youzu Java client provides structured error handling:

import ai.youzu.YouzuClient;
import ai.youzu.YouzuClientBuilder;
import ai.youzu.model.generation.GenerationRequest;
import ai.youzu.exception.YouzuApiException;
import ai.youzu.exception.AuthenticationException;
import ai.youzu.exception.RateLimitException;
import ai.youzu.exception.NetworkException;

public class ErrorHandlingExample {
    public static void main(String[] args) {
        YouzuClient youzu = YouzuClientBuilder.create()
            .setSecretKey("YOUR_SECRET_KEY")
            .build();
        
        GenerationRequest request = new GenerationRequest.Builder()
            .setPrompt("a beautiful sunset")
            .build();
        
        try {
            youzu.generation().create(request);
        } catch (AuthenticationException e) {
            System.err.println("Authentication failed: " + e.getMessage());
        } catch (RateLimitException e) {
            System.err.println("Rate limit exceeded: " + e.getMessage());
            System.err.println("Reset at: " + e.getResetAt());
        } catch (YouzuApiException e) {
            System.err.println("API error: " + e.getMessage());
            System.err.println("Error code: " + e.getErrorCode());
            System.err.println("Status: " + e.getHttpStatusCode());
        } catch (NetworkException e) {
            System.err.println("Network error: " + e.getMessage());
        } catch (Exception e) {
            System.err.println("Unexpected error: " + e.getMessage());
        }
    }
}

Using with Spring BootCopied!

For Spring Boot applications, you can create a configuration bean:

import ai.youzu.YouzuClient;
import ai.youzu.YouzuClientBuilder;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.beans.factory.annotation.Value;

@Configuration
public class YouzuConfig {
    
    @Value("${youzu.secret.key}")
    private String secretKey;
    
    @Bean
    public YouzuClient youzuClient() {
        return YouzuClientBuilder.create()
            .setSecretKey(secretKey)
            .build();
    }
}

Then inject the client where needed:

import ai.youzu.YouzuClient;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class GenerationController {
    
    private final YouzuClient youzuClient;
    
    @Autowired
    public GenerationController(YouzuClient youzuClient) {
        this.youzuClient = youzuClient;
    }
    
    @PostMapping("/generate")
    public String generateImage(@RequestParam String prompt) {
        GenerationRequest request = new GenerationRequest.Builder()
            .setPrompt(prompt)
            .build();
            
        GenerationResponse response = youzuClient.generation().create(request);
        return response.getUrl();
    }
}

For more examples and detailed documentation, refer to the Image Generation and Product Search guides.