{"id":30609983,"url":"https://github.com/bytedance/USO","last_synced_at":"2025-08-30T04:07:20.148Z","repository":{"id":312057008,"uuid":"1042644556","full_name":"bytedance/USO","owner":"bytedance","description":"Open-sourced unified customization model","archived":false,"fork":false,"pushed_at":"2025-08-28T09:08:54.000Z","size":15527,"stargazers_count":28,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-08-28T15:35:13.310Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://bytedance.github.io/USO/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bytedance.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-22T10:45:42.000Z","updated_at":"2025-08-28T15:31:45.000Z","dependencies_parsed_at":"2025-08-28T15:35:16.959Z","dependency_job_id":"9cc5ffe5-d60d-41da-82f2-3d6671e9cf0d","html_url":"https://github.com/bytedance/USO","commit_stats":null,"previous_names":["bytedance/uso"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/bytedance/USO","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytedance%2FUSO","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytedance%2FUSO/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytedance%2FUSO/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytedance%2FUSO/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bytedance","download_url":"https://codeload.github.com/bytedance/USO/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytedance%2FUSO/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272800964,"owners_count":24995185,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-30T02:00:09.474Z","response_time":77,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-30T04:02:17.054Z","updated_at":"2025-08-30T04:07:20.141Z","avatar_url":"https://github.com/bytedance.png","language":"Python","funding_links":[],"categories":["\u003cspan id=\"image\"\u003eImage\u003c/span\u003e","Python"],"sub_categories":["\u003cspan id=\"tool\"\u003eLLM (LLM \u0026 Tool)\u003c/span\u003e"],"readme":"\u003ch3 align=\"center\"\u003e\n    \u003cimg src=\"assets/uso.webp\" alt=\"Logo\" style=\"vertical-align: middle; width: 95px; height: auto;\"\u003e\n    \u003c/br\u003e\n    Unified Style and Subject-Driven Generation via Disentangled and Reward Learning\n\u003c/h3\u003e\n\n\u003cp align=\"center\"\u003e \n\u003ca href=\"https://bytedance.github.io/USO/\"\u003e\u003cimg alt=\"Build\" src=\"https://img.shields.io/badge/Project%20Page-USO-blue\"\u003e\u003c/a\u003e \n\u003ca href=\"https://arxiv.org/abs/2508.18966\"\u003e\u003cimg alt=\"Build\" src=\"https://img.shields.io/badge/Tech%20Report-USO-b31b1b.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"https://huggingface.co/bytedance-research/USO\"\u003e\u003cimg src=\"https://img.shields.io/static/v1?label=%F0%9F%A4%97%20Hugging%20Face\u0026message=Model\u0026color=green\"\u003e\u003c/a\u003e\n\u003ca href=\"https://huggingface.co/spaces/bytedance-research/USO\"\u003e\u003cimg src=\"https://img.shields.io/static/v1?label=%F0%9F%A4%97%20Hugging%20Face\u0026message=demo\u0026color=orange\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\u003c/p\u003e\n\n\u003e\u003cp align=\"center\"\u003e \u003cspan style=\"color:#137cf3; font-family: Gill Sans\"\u003eShaojin Wu,\u003c/span\u003e\u003csup\u003e\u003c/sup\u003e\u003c/a\u003e  \u003cspan style=\"color:#137cf3; font-family: Gill Sans\"\u003eMengqi Huang,\u003c/span\u003e\u003c/a\u003e \u003cspan style=\"color:#137cf3; font-family: Gill Sans\"\u003eYufeng Cheng,\u003c/span\u003e\u003csup\u003e\u003c/sup\u003e\u003c/a\u003e  \u003cspan style=\"color:#137cf3; font-family: Gill Sans\"\u003eWenxu Wu,\u003c/span\u003e\u003csup\u003e\u003c/sup\u003e \u003c/a\u003e \u003cspan style=\"color:#137cf3; font-family: Gill Sans\"\u003eJiahe Tian,\u003c/span\u003e\u003csup\u003e\u003c/sup\u003e\u003c/a\u003e \u003cspan style=\"color:#137cf3; font-family: Gill Sans\"\u003eYiming Luo,\u003c/span\u003e\u003csup\u003e\u003c/sup\u003e\u003c/a\u003e \u003cspan style=\"color:#137cf3; font-family: Gill Sans\"\u003eFei Ding,\u003c/span\u003e\u003c/a\u003e \u003cspan style=\"color:#137cf3; font-family: Gill Sans\"\u003eQian He\u003c/span\u003e\u003c/a\u003e \u003cbr\u003e \n\u003e\u003cspan style=\"font-size: 13.5px\"\u003eUXO Team\u003c/span\u003e\u003cbr\u003e \n\u003e\u003cspan style=\"font-size: 12px\"\u003eIntelligent Creation Lab, Bytedance\u003c/span\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"assets/teaser.webp\" width=\"1024\"/\u003e\n\u003c/p\u003e\n\n## 🔥 News\n* **2025.08.28** 🔥 The [demo](https://huggingface.co/spaces/bytedance-research/USO) of USO is released. Try it Now! ⚡️\n* **2025.08.28** 🔥 Update fp8 mode as a primary low vmemory usage support (please scroll down). Gift for consumer-grade GPU users. The peak Vmemory usage is ~16GB now.\n* **2025.08.27** 🔥 The [inference code](https://github.com/bytedance/USO) and [model](https://huggingface.co/bytedance-research/USO) of USO are released.\n* **2025.08.27** 🔥 The [project page](https://bytedance.github.io/USO) of USO is created.\n* **2025.08.27** 🔥 The [technical report](https://arxiv.org/abs/2508.18966) of USO is released.\n\n## 📖 Introduction\nExisting literature typically treats style-driven and subject-driven generation as two disjoint tasks: the former prioritizes stylistic similarity, whereas the latter insists on subject consistency, resulting in an apparent antagonism. We argue that both objectives can be unified under a single framework because they ultimately concern the disentanglement and re-composition of “content” and “style”, a long-standing theme in style-driven research. To this end, we present USO, a Unified framework for Style driven and subject-driven GeneratiOn. First, we construct a large-scale triplet dataset consisting of content images, style images, and their corresponding stylized content images. Second, we introduce a disentangled learning scheme that simultaneously aligns style features and disentangles content from style through two complementary objectives, style-alignment training and content–style disentanglement training. Third, we incorporate a style reward-learning paradigm to further enhance the model’s performance.\n\n## ⚡️ Quick Start\n\n### 🔧 Requirements and Installation\n\nInstall the requirements\n```bash\n## create a virtual environment with python \u003e= 3.10 \u003c= 3.12, like\npython -m venv uso_env\nsource uso_env/bin/activate\n## or\nconda create -n uso_env python=3.10 -y\nconda activate uso_env\n\n## install torch\n## recommended version:\npip install torch==2.4.0 torchvision==0.19.0 --index-url https://download.pytorch.org/whl/cu124 \n\n## then install the requirements by you need\npip install -r requirements.txt # legacy installation command\n```\n\nThen download checkpoints:\n```bash\n# 1. set up .env file\ncp example.env .env\n\n# 2. set your huggingface token in .env (open the file and change this value to your token)\nHF_TOKEN=your_huggingface_token_here\n\n#3. download the necessary weights (comment any weights you don't need)\npip install huggingface_hub\npython ./weights/downloader.py\n```\n- **IF YOU HAVE WEIGHTS, COMMENT OUT WHAT YOU DON'T NEED IN ./weights/downloader.py**\n\n### ✍️ Inference\n* Start from the examples below to explore and spark your creativity. ✨\n```bash\n# the first image is a content reference, and the rest are style references.\n\n# for subject-driven generation\npython inference.py --prompt \"The man in flower shops carefully match bouquets, conveying beautiful emotions and blessings with flowers. \" --image_paths \"assets/gradio_examples/identity1.jpg\" --width 1024 --height 1024\n# for style-driven generation\n# please keep the first image path empty\npython inference.py --prompt \"A cat sleeping on a chair.\" --image_paths \"\" \"assets/gradio_examples/style1.webp\" --width 1024 --height 1024\n# for style-subject driven generation (or set the prompt to empty for layout-preserved generation)\npython inference.py --prompt \"The woman gave an impassioned speech on the podium.\" --image_paths \"assets/gradio_examples/identity2.webp\" \"assets/gradio_examples/style2.webp\" --width 1024 --height 1024\n# for multi-style generation\n# please keep the first image path empty\npython inference.py --prompt \"A handsome man.\" --image_paths \"\" \"assets/gradio_examples/style3.webp\" \"assets/gradio_examples/style4.webp\" --width 1024 --height 1024\n\n# for low vram:\npython inference.py --prompt \"your propmt\" --image_paths \"your_image.jpg\" --width 1024 --height 1024 --offload --model_type flux-dev-fp8 \n```\n* You can also compare your results with the results in the `assets/gradio_examples` folder.\n\n* For more examples, visit our [project page](https://bytedance.github.io/USO) or try the live [demo](https://huggingface.co/spaces/bytedance-research/USO).\n\n### 🌟 Gradio Demo\n\n```bash\npython app.py\n```\n\n**For low vmemory usage**, please pass the `--offload` and `--name flux-dev-fp8` args. The peak memory usage will be 16GB (Single reference) ~ 18GB (Multi references).\n\n```bash\n# please use FLUX_DEV_FP8 replace FLUX_DEV\nexport FLUX_DEV_FP8=\"YOUR_FLUX_DEV_PATH\"\n\npython app.py --offload --name flux-dev-fp8\n```\n\n## 🌈 More examples\nWe provide some prompts and results to help you better understand the model. You can check our [paper](https://arxiv.org/abs/2508.18966) or [project page](https://bytedance.github.io/USO/) for more visualizations.\n\n#### Subject/Identity-driven generation\nIf you want to place a subject into new scene, please use natural language like \"A dog/man/woman is doing...\". If you only want to transfer the style but keep the layout, please an use instructive prompt like \"Transform the style into ... style\". For portraits-preserved generation, USO excels at producing high skin-detail images. A practical guideline: use half-body close-ups for half-body prompts, and full-body images when the pose or framing changes significantly.\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"assets/show_case1.webp\" width=\"1024\"/\u003e\n\u003cp\u003e\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"assets/show_case2.webp\" width=\"1024\"/\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"assets/show_case3.webp\" width=\"1024\"/\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"assets/show_case4.webp\" width=\"1024\"/\u003e\n\u003c/p\u003e\n\n#### Style-driven generation\nJust upload one or two style images, and use natural language to create want you want. USO will generate images follow your prompt and match the style you uploaded.\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"assets/show_case5.webp\" width=\"1024\"/\u003e\n\u003cp\u003e\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"assets/show_case6.webp\" width=\"1024\"/\u003e\n\u003c/p\u003e\n\n#### Style-subject driven generation\nUSO can stylize a single content reference with one or two style refs. For layout-preserved generation, just set the prompt to empty.\n`Layout-preserved generation`\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"assets/show_case7.webp\" width=\"1024\"/\u003e\n\u003cp\u003e\n\n`Layout-shifted generation`\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"assets/show_case8.webp\" width=\"1024\"/\u003e\n\u003c/p\u003e\n\n## 📄 Disclaimer\n\u003cp\u003e\n  We open-source this project for academic research. The vast majority of images \n  used in this project are either generated or from open-source datasets. If you have any concerns, \n  please contact us, and we will promptly remove any inappropriate content. \n  Our project is released under the Apache 2.0 License. If you apply to other base models, \n  please ensure that you comply with the original licensing terms. \n  \u003cbr\u003e\u003cbr\u003eThis research aims to advance the field of generative AI. Users are free to \n  create images using this tool, provided they comply with local laws and exercise \n  responsible usage. The developers are not liable for any misuse of the tool by users.\u003c/p\u003e\n\n## 🚀 Updates\nFor the purpose of fostering research and the open-source community, we plan to open-source the entire project, encompassing training, inference, weights, dataset etc. Thank you for your patience and support! 🌟\n- [x] Release technical report.\n- [x] Release github repo.\n- [x] Release inference code.\n- [x] Release model checkpoints.\n- [x] Release huggingface space demo.\n- Release training code.\n- Release dataset.\n\n##  Citation\nIf USO is helpful, please help to ⭐ the repo.\n\nIf you find this project useful for your research, please consider citing our paper:\n```bibtex\n@article{wu2025uso,\n    title={USO: Unified Style and Subject-Driven Generation via Disentangled and Reward Learning},\n    author={Shaojin Wu and Mengqi Huang and Yufeng Cheng and Wenxu Wu and Jiahe Tian and Yiming Luo and Fei Ding and Qian He},\n    year={2025},\n    eprint={2508.18966},\n    archivePrefix={arXiv},\n    primaryClass={cs.CV},\n}\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbytedance%2FUSO","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbytedance%2FUSO","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbytedance%2FUSO/lists"}