# Uso > Use USO to perform subject driven generations using reference image. ## Overview - **Endpoint**: `https://fal.run/fal-ai/uso` - **Model ID**: `fal-ai/uso` - **Category**: image-to-image - **Kind**: inference **Tags**: image-to-image ## Pricing - **Price**: $0.1 per megapixels For more details, see [fal.ai pricing](https://fal.ai/pricing). ## API Information This model can be used via our HTTP API or more conveniently via our client libraries. See the input and output schema below, as well as the usage examples. ### Input Schema The API accepts the following input parameters: - **`prompt`** (`string`, _optional_): Text prompt for generation. Can be empty for pure style transfer. Default value: `""` - Default: `""` - Examples: "A handsome man." - **`input_image_urls`** (`list`, _required_): List of image URLs in order: [content_image, style_image, extra_style_image]. - Array of string - Examples: ["https://storage.googleapis.com/falserverless/USO/style3.webp","https://storage.googleapis.com/falserverless/USO/style4.webp"] - **`image_size`** (`ImageSize | Enum`, _optional_): The size of the generated image. Default value: `square_hd` - Default: `"square_hd"` - One of: ImageSize | Enum - **`negative_prompt`** (`string`, _optional_): What you don't want in the image. Use it to exclude unwanted elements, styles, or artifacts. Default value: `""` - Default: `""` - Examples: "blurry, low quality, distorted, ugly, bad anatomy", "cartoon, anime, illustration", "" - **`num_inference_steps`** (`integer`, _optional_): Number of denoising steps. More steps can improve quality but increase generation time. Default value: `28` - Default: `28` - Range: `1` to `50` - **`guidance_scale`** (`float`, _optional_): How closely to follow the prompt. Higher values stick closer to the prompt. Default value: `4` - Default: `4` - Range: `1` to `10` - **`keep_size`** (`boolean`, _optional_): Preserve the layout and dimensions of the input content image. Useful for style transfer. - Default: `false` - **`num_images`** (`integer`, _optional_): Number of images to generate in parallel. Default value: `1` - Default: `1` - Range: `1` to `4` - **`seed`** (`integer`, _optional_): Random seed for reproducible generation. Use same seed for consistent results. - **`sync_mode`** (`boolean`, _optional_): If true, wait for generation and upload before returning. Increases latency but provides immediate access to images. - Default: `false` - **`enable_safety_checker`** (`boolean`, _optional_): Enable NSFW content detection and filtering. Default value: `true` - Default: `true` - **`output_format`** (`OutputFormatEnum`, _optional_): Output image format. PNG preserves transparency, JPEG is smaller. Default value: `"png"` - Default: `"png"` - Options: `"jpeg"`, `"png"` **Required Parameters Example**: ```json { "input_image_urls": [ "https://storage.googleapis.com/falserverless/USO/style3.webp", "https://storage.googleapis.com/falserverless/USO/style4.webp" ] } ``` **Full Example**: ```json { "prompt": "A handsome man.", "input_image_urls": [ "https://storage.googleapis.com/falserverless/USO/style3.webp", "https://storage.googleapis.com/falserverless/USO/style4.webp" ], "image_size": "square_hd", "negative_prompt": "blurry, low quality, distorted, ugly, bad anatomy", "num_inference_steps": 28, "guidance_scale": 4, "num_images": 1, "enable_safety_checker": true, "output_format": "png" } ``` ### Output Schema The API returns the following output format: - **`images`** (`list`, _required_): The generated images with applied style and/or subject customization - Array of Image - Examples: [{"height":1024,"content_type":"image/png","url":"https://storage.googleapis.com/falserverless/USO/G6n97WN0goYpXPeiHaBnP.png","width":1024}] - **`seed`** (`integer`, _required_): Seed used for generation - **`has_nsfw_concepts`** (`list`, _required_): NSFW detection results for each generated image - Array of boolean - **`prompt`** (`string`, _required_): The prompt used for generation - **`timings`** (`Timings`, _required_): Performance timings for different stages **Example Response**: ```json { "images": [ { "height": 1024, "content_type": "image/png", "url": "https://storage.googleapis.com/falserverless/USO/G6n97WN0goYpXPeiHaBnP.png", "width": 1024 } ], "prompt": "" } ``` ## Usage Examples ### cURL ```bash curl --request POST \ --url https://fal.run/fal-ai/uso \ --header "Authorization: Key $FAL_KEY" \ --header "Content-Type: application/json" \ --data '{ "input_image_urls": [ "https://storage.googleapis.com/falserverless/USO/style3.webp", "https://storage.googleapis.com/falserverless/USO/style4.webp" ] }' ``` ### Python Ensure you have the Python client installed: ```bash pip install fal-client ``` Then use the API client to make requests: ```python import fal_client def on_queue_update(update): if isinstance(update, fal_client.InProgress): for log in update.logs: print(log["message"]) result = fal_client.subscribe( "fal-ai/uso", arguments={ "input_image_urls": ["https://storage.googleapis.com/falserverless/USO/style3.webp", "https://storage.googleapis.com/falserverless/USO/style4.webp"] }, with_logs=True, on_queue_update=on_queue_update, ) print(result) ``` ### JavaScript Ensure you have the JavaScript client installed: ```bash npm install --save @fal-ai/client ``` Then use the API client to make requests: ```javascript import { fal } from "@fal-ai/client"; const result = await fal.subscribe("fal-ai/uso", { input: { input_image_urls: ["https://storage.googleapis.com/falserverless/USO/style3.webp", "https://storage.googleapis.com/falserverless/USO/style4.webp"] }, logs: true, onQueueUpdate: (update) => { if (update.status === "IN_PROGRESS") { update.logs.map((log) => log.message).forEach(console.log); } }, }); console.log(result.data); console.log(result.requestId); ``` ## Additional Resources ### Documentation - [Model Playground](https://fal.ai/models/fal-ai/uso) - [API Documentation](https://fal.ai/models/fal-ai/uso/api) - [OpenAPI Schema](https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=fal-ai/uso) ### fal.ai Platform - [Platform Documentation](https://docs.fal.ai) - [Python Client](https://docs.fal.ai/clients/python) - [JavaScript Client](https://docs.fal.ai/clients/javascript)