# Table of Contents - [πŸ‚ Oxen.ai - Oxen.ai](#-oxen-ai-oxen-ai) - [πŸ–ΌοΈ Image Generation - Oxen.ai](#-image-generation-oxen-ai) - [πŸ”₯ Performance - Oxen.ai](#-performance-oxen-ai) - [πŸ’¬ Text Generation - Oxen.ai](#-text-generation-oxen-ai) - [πŸŽ₯ Video Generation - Oxen.ai](#-video-generation-oxen-ai) - [🎨 Image Editing - Oxen.ai](#-image-editing-oxen-ai) - [βš–οΈ Dataset Diffs - Oxen.ai](#-dataset-diffs-oxen-ai) - [πŸ€– Chat Completions - Oxen.ai](#-chat-completions-oxen-ai) - [πŸ‘οΈ Vision Language Models - Oxen.ai](#-vision-language-models-oxen-ai) - [πŸŽ₯ Video Generation - Oxen.ai](#-video-generation-oxen-ai) - [πŸ‘¨β€πŸŽ¨ Image Editing - Oxen.ai](#-image-editing-oxen-ai) - [🏷️ File Metadata - Oxen.ai](#-file-metadata-oxen-ai) - [πŸ–ΌοΈ Image Generation - Oxen.ai](#-image-generation-oxen-ai) - [πŸ“¦ Workspaces - Oxen.ai](#-workspaces-oxen-ai) - [πŸ‘οΈ Vision Language Models - Oxen.ai](#-vision-language-models-oxen-ai) - [πŸ’¬ Language Models - Oxen.ai](#-language-models-oxen-ai) - [Using Models on Oxen.ai - Oxen.ai](#using-models-on-oxen-ai-oxen-ai) - [πŸ“‘ Oxen Server - Oxen.ai](#-oxen-server-oxen-ai) - [🌿 Branches & Merging - Oxen.ai](#-branches-merging-oxen-ai) - [βš™οΈ Setup & Authentication - Oxen.ai](#-setup-authentication-oxen-ai) - [🧹 Maintenance - Oxen.ai](#-maintenance-oxen-ai) - [Repositories on Oxen.ai - Oxen.ai](#repositories-on-oxen-ai-oxen-ai) - [πŸ“Š Datasets - Oxen.ai](#-datasets-oxen-ai) - [πŸ”„ Sync with a Remote - Oxen.ai](#-sync-with-a-remote-oxen-ai) - [βš’οΈ Installation - Oxen.ai](#-installation-oxen-ai) - [πŸš€ Start a Repository - Oxen.ai](#-start-a-repository-oxen-ai) - [πŸ”§ Debugging & Performance - Oxen.ai](#-debugging-performance-oxen-ai) - [Inference API Overview - Oxen.ai](#inference-api-overview-oxen-ai) - [Model Walkthroughs - Oxen.ai](#model-walkthroughs-oxen-ai) - [πŸ“ Track Changes - Oxen.ai](#-track-changes-oxen-ai) - [Chat Completions - Oxen.ai](#chat-completions-oxen-ai) - [πŸ—‚οΈ Workspaces - Oxen.ai](#-workspaces-oxen-ai) - [πŸ’Ύ Version Control - Oxen.ai](#-version-control-oxen-ai) - [Image Generation - Oxen.ai](#image-generation-oxen-ai) - [Async Queue - Oxen.ai](#async-queue-oxen-ai) - [Image Editing - Oxen.ai](#image-editing-oxen-ai) - [Fine-Tuning Models on Oxen.ai - Oxen.ai](#fine-tuning-models-on-oxen-ai-oxen-ai) - [Image Generation - Oxen.ai](#image-generation-oxen-ai) - [Video Generation - Oxen.ai](#video-generation-oxen-ai) - [Topaz Starlight Precise 2.5 - Oxen.ai](#topaz-starlight-precise-2-5-oxen-ai) - [Kling O3 Edit: Video to Video - Oxen.ai](#kling-o3-edit-video-to-video-oxen-ai) - [Video Generation - Oxen.ai](#video-generation-oxen-ai) - [Models - Oxen.ai](#models-oxen-ai) - [Chat Completions - Oxen.ai](#chat-completions-oxen-ai) - [Init - Oxen.ai](#init-oxen-ai) - [Clone - Oxen.ai](#clone-oxen-ai) - [Seedance 2.0: Reference to Video - Oxen.ai](#seedance-2-0-reference-to-video-oxen-ai) - [Tabular diff - Oxen.ai](#tabular-diff-oxen-ai) - [Line diff - Oxen.ai](#line-diff-oxen-ai) - [Text diff - Oxen.ai](#text-diff-oxen-ai) - [Datasets - Oxen.ai](#datasets-oxen-ai) - [Df utils - Oxen.ai](#df-utils-oxen-ai) - [Activate model deployment - Oxen.ai](#activate-model-deployment-oxen-ai) - [Kling O3 Pro: Reference to Video - Oxen.ai](#kling-o3-pro-reference-to-video-oxen-ai) - [Cancel generation - Oxen.ai](#cancel-generation-oxen-ai) - [Diff - Oxen.ai](#diff-oxen-ai) - [Workspace - Oxen.ai](#workspace-oxen-ai) - [Delete custom model - Oxen.ai](#delete-custom-model-oxen-ai) - [Repositories - Oxen.ai](#repositories-oxen-ai) - [Deactivate model deployment - Oxen.ai](#deactivate-model-deployment-oxen-ai) - [Oxen fs - Oxen.ai](#oxen-fs-oxen-ai) - [Repo - Oxen.ai](#repo-oxen-ai) - [Edit image - Oxen.ai](#edit-image-oxen-ai) - [Create chat completion - Oxen.ai](#create-chat-completion-oxen-ai) - [Enqueue generation - Oxen.ai](#enqueue-generation-oxen-ai) - [Get a fine-tune job - Oxen.ai](#get-a-fine-tune-job-oxen-ai) - [Favorite a model - Oxen.ai](#favorite-a-model-oxen-ai) - [Create an evaluation - Oxen.ai](#create-an-evaluation-oxen-ai) - [Create a fine-tune job - Oxen.ai](#create-a-fine-tune-job-oxen-ai) - [Delete a fine-tune job - Oxen.ai](#delete-a-fine-tune-job-oxen-ai) - [Get evaluation status - Oxen.ai](#get-evaluation-status-oxen-ai) - [Get logs for a fine-tune job - Oxen.ai](#get-logs-for-a-fine-tune-job-oxen-ai) - [Get training status for a fine-tune job - Oxen.ai](#get-training-status-for-a-fine-tune-job-oxen-ai) - [Remote repo - Oxen.ai](#remote-repo-oxen-ai) - [Deploy a checkpoint from a fine-tune job - Oxen.ai](#deploy-a-checkpoint-from-a-fine-tune-job-oxen-ai) - [List fine-tunes for a user - Oxen.ai](#list-fine-tunes-for-a-user-oxen-ai) - [Update training status for a fine-tune job - Oxen.ai](#update-training-status-for-a-fine-tune-job-oxen-ai) - [List all fine-tunes accessible to the current user - Oxen.ai](#list-all-fine-tunes-accessible-to-the-current-user-oxen-ai) - [List checkpoints for a fine-tune job - Oxen.ai](#list-checkpoints-for-a-fine-tune-job-oxen-ai) - [Tokenize data for a fine-tune job - Oxen.ai](#tokenize-data-for-a-fine-tune-job-oxen-ai) - [Generate video - Oxen.ai](#generate-video-oxen-ai) - [List fine-tunes in a repository - Oxen.ai](#list-fine-tunes-in-a-repository-oxen-ai) - [Generate image - Oxen.ai](#generate-image-oxen-ai) - [Update a fine-tune job - Oxen.ai](#update-a-fine-tune-job-oxen-ai) - [List in-flight queue items - Oxen.ai](#list-in-flight-queue-items-oxen-ai) - [List fine-tunes for an organization - Oxen.ai](#list-fine-tunes-for-an-organization-oxen-ai) - [Get generation details - Oxen.ai](#get-generation-details-oxen-ai) - [List past generations - Oxen.ai](#list-past-generations-oxen-ai) - [List models - Oxen.ai](#list-models-oxen-ai) - [Async Queue - Oxen.ai](#async-queue-oxen-ai) - [List featured models - Oxen.ai](#list-featured-models-oxen-ai) - [Run a fine-tune job - Oxen.ai](#run-a-fine-tune-job-oxen-ai) - [Get generation status - Oxen.ai](#get-generation-status-oxen-ai) - [List favorite models - Oxen.ai](#list-favorite-models-oxen-ai) - [Search models - Oxen.ai](#search-models-oxen-ai) - [Data frame - Oxen.ai](#data-frame-oxen-ai) - [Stop a running fine-tune job - Oxen.ai](#stop-a-running-fine-tune-job-oxen-ai) - [Update model - Oxen.ai](#update-model-oxen-ai) - [Retrieve model - Oxen.ai](#retrieve-model-oxen-ai) - [Unfavorite a model - Oxen.ai](#unfavorite-a-model-oxen-ai) - [Introduction - Oxen.ai](#introduction-oxen-ai) - [Parameter Guide - Oxen.ai](#parameter-guide-oxen-ai) --- # πŸ‚ Oxen.ai - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/getting-started/intro#content-area) Oxen.ai gives developers, creators, and teams easy access to the latest AI models, plus the data infrastructure to organize, version, collaborate on, and customize the data behind them. Use 200+ image, video, audio, and language models through one API. Save prompts, reference assets, generations, metadata, and training data into collaborative repositories. Track every change, branch experiments, and fine-tune custom models on your proprietary data. ![Oxen.ai Moon Ox Hero](https://mintcdn.com/oxenai/QtlW2oU-RZhG3OQp/images/platform_oxen.png?w=2500&fit=max&auto=format&n=QtlW2oU-RZhG3OQp&q=85&s=a8163940be5a56ffa734254eb390f1ff) Your models are only as good as the data behind them. Oxen helps teams turn raw inputs and generated outputs into organized, reusable, version-controlled assets. [​](https://docs.oxen.ai/getting-started/intro#-use-any-model) ⚑️ Use Any Model ---------------------------------------------------------------------------------- Access 200+ models through a unified API instead of integrating with each provider separately. Build your own product experiences on top of Oxen while keeping model inputs, outputs, and metadata stored in a data repository for auditability, reproducibility, and collaboration. Oxen.ai has models of every modality (text, images, videos, audio) from the major labs, and more. Explore the [list of supported models](https://oxen.ai/ai/models) to see what you can build. [​](https://docs.oxen.ai/getting-started/intro#-customize-your-models) 🌾 Customize Your Models -------------------------------------------------------------------------------------------------- Customization can start simple: managing prompts, context, reference images, and generated outputs. If prompting isn’t enough, fine-tune the model weights themselves on your proprietary datasets. In both cases, your data is what makes the model yours. Fine-tune open source models for many modalities (text, images, videos) on your proprietary data. Oxen gives you the tools to version, collaborate, and customize the data behind your models. [​](https://docs.oxen.ai/getting-started/intro#-version-your-data) πŸ’Ύ Version Your Data ------------------------------------------------------------------------------------------ Track the provenance of prompts, images, videos, audio, text, labels, metadata, generations, and training examples in repositories built for large datasets. Oxen gives you git-like version control for data that can scale to terabytes. We built the version control system to be [blazing fast](https://docs.oxen.ai/examples/data/performance) , [open source](https://github.com/Oxen-AI/Oxen) , and extensible for anyone to build upon. It can be used to version any type of data, not just machine learning datasets. It scales up to monorepos with [millions of files and terabytes of data](https://docs.oxen.ai/examples/data/performance) . [​](https://docs.oxen.ai/getting-started/intro#-collaborate-with-your-team) 🀝 Collaborate With Your Team ------------------------------------------------------------------------------------------------------------ Built on top of the [open source](https://github.com/Oxen-AI/Oxen) Oxen version control system, Oxen.ai gives your team a [web hub](https://oxen.ai/) to work with your data, prompts, and generations at scale. Browse datasets, review generated outputs, and experiment across branches. Every contribution is versioned, so you can see who changed what, when, and why, and discard changes when an experiment doesn’t pan out. For teams with stricter requirements around data residency, compliance, or IP, Oxen.ai offers private deployments in your VPC or fully on-prem. Your proprietary data, prompts, and model weights stay in your environment, while your team gets the same collaborative tooling. Reach out to [hello@oxen.ai](mailto:hello@oxen.ai) to learn more about private deployments. [​](https://docs.oxen.ai/getting-started/intro#-own-your-ai) πŸ€– Own Your AI ------------------------------------------------------------------------------ At Oxen.ai, we believe you should **own your AI**. Owning your AI means making the model uniquely yours. For image and video generation, that might mean consistent style, characters, products, or brand identity. For language models, it might mean better accuracy, lower cost, stronger privacy, or deeper domain expertise. It also means owning the data behind the model. Your prompts, reference images, generations, labels, and training data live in a versioned repository, and you can read or write any of it through the [Python API](https://docs.oxen.ai/python-api/index) , [HTTP API](https://docs.oxen.ai/http-api/index) , [command line](https://docs.oxen.ai/getting-started/install) , or [open source server](https://docs.oxen.ai/getting-started/oxen-server) . No matter what kind of model you are building with, you should be able to train it, version it, deploy it, and improve it on your terms. [​](https://docs.oxen.ai/getting-started/intro#-why-build-oxen) 🌾 Why Build Oxen? ------------------------------------------------------------------------------------- Oxen was built by a team of machine learning engineers, who have spent countless hours in their careers managing datasets and training models. We have used many different tools, but none of them were as easy to use and as ergonomic as we would like. Production grade AI applications are constantly juggling models, datasets, and code, and it’s easy to get lost. Let alone the late nights installing the proper cuda and pytorch versions. If you have every been stuck dumping massive model weights and datasets to S3 in tarballs with little visibility, we feel your pain. Oxen is the tool we wish we had to abstract away the infrastructure and focus on the fun parts of building AI applications. [​](https://docs.oxen.ai/getting-started/intro#-why-the-name-oxen) πŸ‚ Why the name Oxen? ------------------------------------------------------------------------------------------- β€œOxen” comes from the fact that we take care of the grunt work of the infrastructure for you. Oxen love will plow, maintain, and version your data and models like a good farmer tends to their fields 🌾. During the agricultural revolution, the oxen pulling plows offloaded work and helped people specialize and start working on other important societal tasks. Let Oxen take care of the heavy infrastructure work so you can focus on solving the higher-level problems that matter to your product. [πŸ“– Overview](https://docs.oxen.ai/getting-started/inference) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # πŸ–ΌοΈ Image Generation - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/examples/inference/image_generation#content-area) ### [​](https://docs.oxen.ai/examples/inference/image_generation#image-generation) Image Generation The image generation endpoint allows you to generate images from text prompts. Simply provide a prompt describing the image you want to create. To see the list of models that support image generation, visit the [Models](https://www.oxen.ai/ai/models?modalities=text-to-image) page and filter by β€œText to Image”. cURL Python curl -X POST \ https://hub.oxen.ai/api/ai/images/generate \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OXEN_API_KEY" \ -d '{ "model": "Qwen/Qwen-Image", "prompt": "A majestic ox standing in a field at sunset", "num_inference_steps": 28 }' [​](https://docs.oxen.ai/examples/inference/image_generation#parameters) Parameters -------------------------------------------------------------------------------------- * **model**: The model identifier to use for image generation (e.g., `Qwen/Qwen-Image`) * **prompt**: Text description of the image you want to generate * **num\_inference\_steps**: Number of inference steps (optional, defaults vary by model) [πŸ‘οΈ Vision Language Models](https://docs.oxen.ai/examples/inference/vision_language_models) [🎨 Image Editing](https://docs.oxen.ai/examples/inference/image_editing) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # πŸ”₯ Performance - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/examples/data/performance#content-area) [​](https://docs.oxen.ai/examples/data/performance#-1-million-files-benchmark) πŸ–ΌοΈ 1 Million Files Benchmark =============================================================================================================== When we first started working on Oxen.ai, we were inspired by making a tool that would make it easy to collaborate on large datasets that power modern AI research. One dataset that comes to mind is the original [ImageNet](https://image-net.org/) dataset. This dataset spans 1000 object classes and contains > 1,000,000 training images and 100,000 test images. It commonly gets shared as a tarball, zip file, or gets dumped to S3 without much visibility into the data itself. ![ImageNet](https://mintcdn.com/oxenai/s_o9ZlhOEkYJf27_/images/ImageNet.png?w=2500&fit=max&auto=format&n=s_o9ZlhOEkYJf27_&q=85&s=06a3de5d62516a0670e5a0bc96cf3e67) A version control system (VCS) would be a much better way to share and iterate on datasets like ImageNet. This is an example of a dataset that hasn’t been updated since it’s initial release. Backing the dataset with a VCS would allow people to collaborate on the dataset without duplicating data all over the place. In order to do this effectively, the VCS needs to be fast to make the developer experience worth using. Not an easy task, but one we were willing to plow through at Oxen.ai πŸ‚ [​](https://docs.oxen.ai/examples/data/performance#-the-raw-numbers) πŸ“Š The Raw Numbers ------------------------------------------------------------------------------------------ To create this benchmark, we took the 1 million+ images from ImageNet and added them to Oxen, DVC, Git-LFS, and S3. The total time is to get the files from A (local filesystem) to B (remote storage) successfully. The steps to reproduce and the machine specs are in the sections below. Here are the results in ranked order from fastest to slowest. | Tool | Time | Can view data? | | --- | --- | --- | | **πŸ‚ Oxen.ai** | 1 hour and 30 mins | βœ… Yes | | **Tarball + S3** | 2 hours 21 mins | ❌ No | | **aws s3 cp** | 2 hours 48 mins | ❌ No | | **DVC + Local** | 3 hours | ❌ No | | **DVC + S3** | 4 hours and 51 mins | βœ… Yes w/ Other Tools | | **Git-LFS** | 20 hours | ❌ No | Notice that **Oxen is faster than even the laziest of methods**, creating a tarball and uploading it to S3, but with the benefits of being able to view, query, and compare versions of the data. If you would like us to add any other tools to the benchmark, please let us know! [​](https://docs.oxen.ai/examples/data/performance#-hardware-and-network) βš™οΈ Hardware and Network ---------------------------------------------------------------------------------------------------- All of the benchmarks were executed on a `t3.2xlarge` EC2 instance with `4 vCPUs` and `16.0 GB of RAM` and a `1TB EBS` volume attached. We found that the size of the EBS volume did impact the IOPs for adding and committing data for all tools. All of the network transfer was within us-west-1 within AWS to S3. [​](https://docs.oxen.ai/examples/data/performance#-view-the-data) πŸ‘€ View the Data -------------------------------------------------------------------------------------- One of the other advantages of using Oxen.ai, besides raw speed, is that you can view, query and collaborate on the data as soon as you’ve pushed it to the [web hub](https://oxen.ai/) . Feel free to explore the end result [here](https://oxen.ai/datasets/ImageNet-1k) in Oxen.ai. ![ImageNet-Oxen-DataFrame](https://mintcdn.com/oxenai/s_o9ZlhOEkYJf27_/images/ImageNet-Oxen-DataFrame.png?w=2500&fit=max&auto=format&n=s_o9ZlhOEkYJf27_&q=85&s=1ed688351f06df0d44c7ad27086e8aba) [​](https://docs.oxen.ai/examples/data/performance#-why-not-git) 🧐 Why not Git? ----------------------------------------------------------------------------------- Everybody knows and loves Git. But we also know that it isn’t exactly suited to version data. Trying to add multi-gigabyte datasets can quickly blowup storage costs and cause serious slowdown. And that isn’t really Git’s purpose, either - GitHub, for instance, doesn’t even accept files larger than 100 megabytes. Over the years, however, several attempts have been made to extend Git to gigabyte or even terabyte scale. In 2015 Git-LFS support was added to GitHub, which speeds up pulls by downloading files lazily, replacing tracked files with pointers and retrieving their content upon checkout. Data Version Control (DVC) came out in 2017, employing a similar concept but storing the file contents externally to Git. In theory it sounds great to tie your VCS to the most popular version control system in the world in git. But in practice, it is a bit like trying to fill a swimming pool with a straw. You can do it, but you are tied to the limitations of the git protocols. [​](https://docs.oxen.ai/examples/data/performance#-how-does-oxen-ai-work) πŸ‚ How does Oxen.ai work? ------------------------------------------------------------------------------------------------------- With Oxen.ai, we take a different approach. Rather than trying to extend Git, we built Oxen, taking inspiration from Git where we can. We didn’t want to make you learn a completely new tool. If you know how to use git, you know how to use Oxen. But we also designed Oxen specifically to make versioning large amounts of data as fast as possible. Under the hood, Oxen uses Merkle trees, smart network protocols and fast hashing algorithms to reduce the amount of data our repositories store. Unbound by Git, however, we’re also able to employ several other optimizations that make Oxen fast such as block-level deduplication, compression, iterating on subtrees, and more. Some of these optimizations are still under development, but we’re excited to share what we have so far, and you can find a deeper dive and list of the upcoming features [here](https://oxen-ai.github.io/) . All of the code is open source and available on [GitHub](https://github.com/oxen-ai/Oxen) . We appreciate any feedback you have and welcome any stars and contributions! * * * [​](https://docs.oxen.ai/examples/data/performance#-running-the-experiments) πŸƒ Running the Experiments ========================================================================================================== To give you a sense of the process as well as point out the advantages & challenges associated with each method, we ran the following experiments below, listed from slowest to fastest. [​](https://docs.oxen.ai/examples/data/performance#git-+-lfs-20-hours) Git + LFS (~20 hours) ----------------------------------------------------------------------------------------------- Git-LFS is a popular first tool to try since it is already in the Git ecosystem. The problem is that it is painfully slow when it comes to adding, committing, and pushing non-text files. It can also be a bit annoying to remember which files are tracked under LFS vs just regular Git. Many times have I accidentally committed a multi-GB file to git and wondered why my push was taking so long. Removing files from the git merkle tree is a whole other pain. Steps to reproduce: git init git lfs install git lfs track "*.jpg" git add .gitattributes git add images # 61 minutes git commit -m "adding images" # 11 minutes git push origin main # 19 hours Total time: `20+ hours` Adding and committing data locally is not terribly slow (still slower than Oxen). But it does have to hash and copy every file into the hidden `.git` directory. The combination of using a slow hashing algorithm and copying large files makes git-lfs slower than it has to be on `add` and `commit`. The real killer here though is the push πŸ₯±. Pushing data to the remote takes over 20 hours in the case of ImageNet, even on the same network as our other tests. [​](https://docs.oxen.ai/examples/data/performance#dvc-+-s3-backend-5-hours) DVC + S3 Backend (~5 hours) ----------------------------------------------------------------------------------------------------------- DVC is a popular tool, tightly integrated with the Git ecosystem and can be configured for multiple storage backends. You’ll see that you have to toggle back and forth between DVC and git with 11 commands to remember and execute. It is easy to make a mistake and track the wrong things in your git repo as well as simply wrap your head around the fact that you are using two different tools to version your data. Steps to reproduce: git init dvc init git status git commit -m "Initialize DVC" dvc add images/ # Executed in 132.12 mins git add images.dvc .gitignore git commit -m "adding images" git remote add origin https://github.com/owner/repository.git dvc remote add --default datastore s3://my-bucket git push origin main dvc push # Executed in 159.55 mins Total Time: `4 hours and 51 mins` As you can see, DVC is not as slow as Git-LFS, but it is significantly more commands to remember and execute. [​](https://docs.oxen.ai/examples/data/performance#dvc-+-local-storage-backend-3-hours) DVC + Local Storage Backend (~3 hours) --------------------------------------------------------------------------------------------------------------------------------- We wanted to do another test with DVC without any network transfer, purely to test the protocol overhead. Transferring to S3 may not be the best apples to apples comparison, since Oxen also compresses and deduplicates data on the network transfer. git init dvc init git status git commit -m "Initialize DVC" dvc add images/ # Executed in 132.12 mins git add images.dvc .gitignore git commit -m "adding images" dvc remote add -d myremote /home/ubuntu/dvc-remote git push origin main dvc push # Executed in 49.53 mins Total Time: `3 hours` As we’ll see below, Oxen is faster than DVC even if you drop the overhead of network transfer. [​](https://docs.oxen.ai/examples/data/performance#tarball-+-s3-2-hours-21-mins) Tarball + S3 (~2 hours 21 mins) ------------------------------------------------------------------------------------------------------------------- I like to call this one, β€œF’ it, let’s just create a tarball and upload it to S3”. Easy to remember, easy to use, but not very efficient nor effective when it comes to iterating on data. time tar czf imagenet-images.tar.gz images/ # Executed in 114.66 mins time aws s3 cp imagenet-images.tar.gz s3://imagenet-tarball # Executed in 27.13 mins Total Time: `2 hours 21 mins` This may work well for cold storage of data you may rarely want to view again. But for anything else, Oxen is a much better tool. Oxen smartly compresses and creates smaller data chunks behind the scenes while transferring your data across the network, taking advantage of the network bandwidth and reducing the amount of time it takes to upload and download data. [​](https://docs.oxen.ai/examples/data/performance#aws-s3-cp-2-hours-48-mins) aws s3 cp (~2 hours 48 mins) ------------------------------------------------------------------------------------------------------------- You may be asking yourself, well if the tarball takes so long to create, why not just use the `aws s3 cp` command with the `--recursive` flag? time aws s3 cp --recursive images s3://imagenet-files # Executed in 168.28 mins Total Time: `2 hours 48 mins` This is a bit slower overall than the tarball method, and you still have the same problems of iterating on and viewing the data. By looking at the logs, it looks like the s3 sdk is syncing the files one by one, which accounts for the slowness. [​](https://docs.oxen.ai/examples/data/performance#oxen-ai-1-hour-and-30-mins) Oxen.ai (~1 hour and 30 mins) --------------------------------------------------------------------------------------------------------------- With Oxen, if you know how to use git, there are no extra commands to remember. With the same commands as plain old git you can initialize, add, commit, and push your data to the remote. Steps to reproduce: oxen init oxen add images # Executed in 41.35 mins oxen commit -m "adding images" # Executed in 50.75 secs oxen config --set-remote origin https://hub.oxen.ai/datasets/ImageNet-1k oxen push # Executed in 49.11 mins Total Time πŸ”₯: `1 hour and 30 mins` If you are curious how Oxen works under the hood, we are working on a detailed technical writeup that dives into the Merkle tree, block-level deduplication, and more [here](https://oxen-ai.github.io/) . [​](https://docs.oxen.ai/examples/data/performance#try-oxen-ai-for-yourself) Try Oxen.ai for Yourself ======================================================================================================== If you would like to try Oxen.ai for yourself, you can sign up for a free account [here](https://oxen.ai/) . All of the code is open source and available on [GitHub](https://github.com/oxen-ai/Oxen) . Let us know what you think by joining our [Discord](https://discord.com/invite/s3tBEn7Ptg) . [πŸ“¦ Workspaces](https://docs.oxen.ai/examples/data/workspaces) [βš–οΈ Dataset Diffs](https://docs.oxen.ai/concepts/diffs) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # πŸ’¬ Text Generation - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/examples/fine-tuning/text_generation#content-area) This tutorial will show you how to fine-tune an LLM for text generation. Text generation is useful for tasks like classification like sentiment analysis where you have a single input and output you want the model to learn. Small language models are great for tasks like this because they are fast and cheap to fine-tune and run. If your application needs to maintain a history of chat messages\[\] as context for the model, you should follow the [Chat Completions](https://docs.oxen.ai/examples/fine-tuning/chat_completions) tutorial. [​](https://docs.oxen.ai/examples/fine-tuning/text_generation#upload-your-dataset) Upload Your Dataset --------------------------------------------------------------------------------------------------------- For this example, we are teaching the model to classify financial sentiment from text. You can follow along with the [Tutorials/FinancialSentiment](https://www.oxen.ai/Tutorials/FinancialSentiment/file/main/train_financial_sentiment.parquet) dataset containing 2000 rows of text and their corresponding sentiment labels. The dataset has one column for the prompt and one for the sentiment label (positive, negative, or neutral). Oxen supports datasets in a variety of formats, including jsonl, csv, and parquet. ![datasets-page](https://mintcdn.com/oxenai/ccInAwcxb-C1RCGU/images/fine_tuning/text-generation/dataset.png?w=2500&fit=max&auto=format&n=ccInAwcxb-C1RCGU&q=85&s=6706940635369ad28be552b8f84fcff0) [​](https://docs.oxen.ai/examples/fine-tuning/text_generation#fine-tuning-the-model) Fine-Tuning The Model ------------------------------------------------------------------------------------------------------------- Once you have uploaded your dataset, click the β€œActions” button and select β€œFine-tune a model”. ![Fine-tune button](https://mintcdn.com/oxenai/ccInAwcxb-C1RCGU/images/fine_tuning/text-generation/fine-tune-action.png?w=2500&fit=max&auto=format&n=ccInAwcxb-C1RCGU&q=85&s=e29012133ccb097fc4b9b7ebab8a8eb6) Next select your base model, the prompt source, the response source, whether you’d like to use LoRA or not, and if you want advanced control over the fine-tune. For this example, we are using the [Qwen3-0.6B](https://www.oxen.ai/ai/models/qwen-qwen3-0-6b) model, which is small and fast to fine-tune. ![Fine-tune first page](https://mintcdn.com/oxenai/ccInAwcxb-C1RCGU/images/fine_tuning/text-generation/fine-tune-qwen3-0.6b.png?w=2500&fit=max&auto=format&n=ccInAwcxb-C1RCGU&q=85&s=f648abcc9257472e60c6dcac9d9e66d5) For our Advance Options, you can have control over hyper-parameters and model specifications like learning rate, batch size, and number of epochs. ![Advanced options photo](https://mintcdn.com/oxenai/T4_0EQB1ENVXiGMM/images/fine_tuning/text-generation/advanced-settings.png?w=2500&fit=max&auto=format&n=T4_0EQB1ENVXiGMM&q=85&s=2e160df057e2a4326953fbea321a84cb) [​](https://docs.oxen.ai/examples/fine-tuning/text_generation#monitoring-the-fine-tune) Monitoring the Fine-Tune ------------------------------------------------------------------------------------------------------------------- While we’re fine-tuning your model, you’ll be able to see the configuration, logs, and metrics of the fine-tuning. ![Metrics example](https://mintcdn.com/oxenai/GvHCMKbbr_BpHEwk/images/fine_tuning/fine-tune-loss.png?w=2500&fit=max&auto=format&n=GvHCMKbbr_BpHEwk&q=85&s=0eccd01e926eaa0294c0f3603d634302) [​](https://docs.oxen.ai/examples/fine-tuning/text_generation#deploying-the-model) Deploying the Model --------------------------------------------------------------------------------------------------------- Once your fine-tuning is complete, go to the info page and click β€œDeploy”. Oxen.ai will spin up a dedicated endpoint for your model to access via a chat interface or through the API. ![Deploy example](https://mintcdn.com/oxenai/ccInAwcxb-C1RCGU/images/fine_tuning/text-generation/deploy-button.png?w=2500&fit=max&auto=format&n=ccInAwcxb-C1RCGU&q=85&s=83507976a1a86b5e5260e1e7c7029fd9) After the model is deployed, you can click the β€œChat with this model” button to open a chat interface. ![fine-tuned chatbot](https://mintcdn.com/oxenai/ccInAwcxb-C1RCGU/images/fine_tuning/text-generation/chat-button.png?w=2500&fit=max&auto=format&n=ccInAwcxb-C1RCGU&q=85&s=b41a619d5f50fc81354cf5a9bcce4cca) This will bring up a chat interface where you can test your model to see how it performs. ![fine-tuned chatbot](https://mintcdn.com/oxenai/ccInAwcxb-C1RCGU/images/fine_tuning/text-generation/chat-interface.png?w=2500&fit=max&auto=format&n=ccInAwcxb-C1RCGU&q=85&s=8e6ec03e713a167060600fd1a35694b0) [​](https://docs.oxen.ai/examples/fine-tuning/text_generation#model-api) Model API ------------------------------------------------------------------------------------- You can integrate it into your application using the API. The API is OpenAI compatible, so you can use any OpenAI client library to interact with it. The base URL for the API is `https://hub.oxen.ai/api/ai`. curl -X POST https://hub.oxen.ai/api/ai/chat/completions \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "your-model-id", "messages": [{"role": "user", "content": "The company went bankrupt last week."}] }' Make sure to replace `your-model-id` with the ID of your fine-tuned model. [​](https://docs.oxen.ai/examples/fine-tuning/text_generation#next-steps) Next Steps --------------------------------------------------------------------------------------- Feel free to join our [Discord](https://discord.com/invite/s3tBEn7Ptg) and ask us or the community any questions you have, we have a community of developers and machine learning experts who are happy to help you out. [πŸ“– Overview](https://docs.oxen.ai/getting-started/fine-tuning) [πŸ€– Chat Completions](https://docs.oxen.ai/examples/fine-tuning/chat_completions) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # πŸŽ₯ Video Generation - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/examples/inference/video_generation#content-area) ### [​](https://docs.oxen.ai/examples/inference/video_generation#video-generation) Video Generation The video generation endpoint allows you to generate videos from text prompts. Simply provide a prompt describing the video you want to create. To see the list of models that support video generation, visit the [Models](https://www.oxen.ai/ai/models?modalities=text-to-video) page and filter by β€œText to Video”. Video generation can take a few minutes to generate, depending on the model. So we recommend using the `run_fast` parameter to speed up the process. We are working on async video generation, reach out at [support@oxen.ai](mailto:support@oxen.ai) if you want early access. cURL Python curl -X POST \ https://hub.oxen.ai/api/ai/videos/generate \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OXEN_API_KEY" \ -d '{ "model": "wan-2.2-t2v-fast", "prompt": "An ox walking in a field", "run_fast": true }' [​](https://docs.oxen.ai/examples/inference/video_generation#parameters) Parameters -------------------------------------------------------------------------------------- * **model**: The model identifier to use for video generation (e.g., `wan-2.2-t2v-fast`) * **prompt**: Text description of the video you want to generate * **run\_fast**: Whether to use fast generation mode (optional, defaults to `true`) [🎨 Image Editing](https://docs.oxen.ai/examples/inference/image_editing) [πŸ“– Overview](https://docs.oxen.ai/getting-started/data) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # 🎨 Image Editing - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/examples/inference/image_editing#content-area) ### [​](https://docs.oxen.ai/examples/inference/image_editing#image-editing) Image Editing The image editing endpoint allows you to edit images using AI models. Simply provide an input image URL and a prompt describing the edits you want to make. To see the list of models that support image editing, visit the [Models](https://www.oxen.ai/ai/models?modalities=image-to-image) page and filter by β€œImage to Image”. cURL Python curl -X POST \ https://hub.oxen.ai/api/ai/images/edit \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OXEN_API_KEY" \ -d '{ "model": "Qwen/Qwen-Image-Edit", "input_image": "https://example.com/image.png", "prompt": "Add a funny hat to the ox", "num_inference_steps": 28 }' For models that support multiple input images, you can pass an array of image URLs: cURL (multiple images) Python (multiple images) curl -X POST \ https://hub.oxen.ai/api/ai/images/edit \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OXEN_API_KEY" \ -d '{ "model": "Qwen/Qwen-Image-Edit", "input_image": [\ "https://example.com/image1.png",\ "https://example.com/image2.png"\ ], "prompt": "Add a funny hat to the ox", "num_inference_steps": 28 }' [​](https://docs.oxen.ai/examples/inference/image_editing#parameters) Parameters ----------------------------------------------------------------------------------- * **model**: The model identifier to use for image editing (e.g., `Qwen/Qwen-Image-Edit`) * **input\_image**: URL of the input image(s) you want to edit. Can be a string (single image URL) or an array of strings (multiple image URLs) for models that support multiple images as input * **prompt**: Text description of the edits you want to make * **num\_inference\_steps**: Number of inference steps (optional, defaults vary by model) [​](https://docs.oxen.ai/examples/inference/image_editing#playground-interface) Playground Interface ------------------------------------------------------------------------------------------------------- The model playground allows you to quickly test out the boundaries of any model in the UI. This is a great way to experiment with different prompts and see how the model performs before integrating it into your application. ![Image editing playground](https://mintcdn.com/oxenai/ww25tVPcZSq1nsp-/images/inference/image-editing/playground.png?w=2500&fit=max&auto=format&n=ww25tVPcZSq1nsp-&q=85&s=2a2530ed3cf591dc59fcb43378a4aeb9) The generated images automatically get saved to a dataset that you can share with your team, download and use to train your own model, or use in your application. [πŸ–ΌοΈ Image Generation](https://docs.oxen.ai/examples/inference/image_generation) [πŸŽ₯ Video Generation](https://docs.oxen.ai/examples/inference/video_generation) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # βš–οΈ Dataset Diffs - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/concepts/diffs#content-area) Oxen.ai has built in tools to help you find differences in your datasets. It is as simple as running the `oxen diff` command with the path to your datasets. CLI Python oxen diff dataset.csv -o diff.csv Column changes: + label (str) Row changes: Ξ” 1 (modified) + 3 (added) - 2 (removed) shape: (6, 7) +-------------+-----+-----+-------+--------+-------------+-------------------+ | file | x | y | width | height | label.right | .oxen.diff.status | | --- | --- | --- | --- | --- | --- | --- | | str | i64 | i64 | i64 | i64 | str | str | +-------------+-----+-----+-------+--------+-------------+-------------------+ | image_0.jpg | 0 | 0 | 10 | 10 | cat | modified | | image_1.jpg | 1 | 2 | 10 | 20 | null | removed | | image_1.jpg | 200 | 100 | 10 | 20 | dog | added | | image_2.jpg | 4 | 10 | 20 | 20 | null | removed | | image_3.jpg | 4 | 10 | 20 | 20 | dog | added | | image_4.jpg | 10 | 10 | 10 | 10 | dog | added | +-------------+-----+-----+-------+--------+-------------+-------------------+ Under the hood Oxen.ai is using a combination of hashing and diffing algorithms to find the differences in your datasets. This allows you to quickly find changes in your datasets, whether they are rows, columns, or individual cells. Oxen’s diff tool tries to strike a balance between being easy to use and being flexible enough to handle complex datasets. [​](https://docs.oxen.ai/concepts/diffs#diff-types) Diff Types ================================================================= Oxen.ai currently supports a [TextDiff](https://docs.oxen.ai/python-api/diff/text_diff) and a [TabularDiff](https://docs.oxen.ai/python-api/diff/tabular_diff) data type. The `TabularDiff` data type is used to represent the differences in tabular data, such as CSV, TSV, or Parquet files. The `TextDiff` data type is used to represent the differences in text files, such as markdown, code, or configuration files. In the future, we plan to add support for other data types such as images, audio, and video. [​](https://docs.oxen.ai/concepts/diffs#diff-command-syntax) Diff Command Syntax =================================================================================== The `oxen diff` command supports multiple syntax patterns similar to Git: * `oxen diff` - Compare working tree with HEAD * `oxen diff ` - Compare specific file in working tree with HEAD * `oxen diff ` - Compare commit with HEAD * `oxen diff ..` - Compare two commits using range syntax * `oxen diff ` - Compare two commits * `oxen diff [--] [...]` - Compare commit with HEAD for specific paths * `oxen diff .. [--] [...]` - Compare two commits for specific paths * `oxen diff file1 file2` - Compare two local files (not in repository) The `..` separator can be used to specify commit ranges, making it easy to compare different versions of your data. [​](https://docs.oxen.ai/concepts/diffs#pick-your-tooling) Pick Your Tooling =============================================================================== All the functionality below is available through the [πŸ–₯️ Command Line](https://docs.oxen.ai/getting-started/command-line/start_repository) , [πŸ¦€ Rust Library](https://crates.io/crates/liboxen) , [🐍 Python Library](https://docs.oxen.ai/python-api) , as well as the [🌎 Web Interface](https://oxen.ai/) . This guide will focus on the command line tooling, but the same principles apply to the other interfaces. Using the [Oxen.ai Hub](https://oxen.ai/) you can quickly visualize and navigate the changes in your datasets with an easy to use interface. Sign up for free πŸ‘‰ [here](https://oxen.ai/register) . ![Data Diff](https://mintcdn.com/oxenai/s_o9ZlhOEkYJf27_/images/data-frames/data-diff.png?w=2500&fit=max&auto=format&n=s_o9ZlhOEkYJf27_&q=85&s=0b045d354cce56a91e788bf68ea752b6) We will build up from simple examples to more complex ones. Starting from adding and removing rows, to modifying rows, to detecting schema changes, and finally providing specific target fields you are interested in. All the data below can be found in the [datasets/diff-examples repository](https://www.oxen.ai/datasets/diff-examples) . [​](https://docs.oxen.ai/concepts/diffs#let%E2%80%99s-build-a-dataset) Let’s Build a Dataset =============================================================================================== In order to demonstrate how to use the `oxen diff` command, we will need a dataset to work with. Imagine we are collecting a dataset for fine-tuning a Large Language Model (LLM). This dataset will have a set of `prompts` and a `category` that they belong to. Create a new file called `dataset.csv` and add the following data to it. prompt,category What is the capital of France?,geography What is 2+10?,math What is the capital of Germany?,geography What is the best python library for http requests?,programming Tell me a story about an ox.,story If you are not familiar with the `oxen df` command it is a handy tool to manipulate and inspect tabular data. You can use it with any CSV, TSV, Parquet, or line delimited JSON file. CLI Python oxen df dataset.csv shape: (5, 2) +-----------------------------------+-------------+ | prompt | category | | --- | --- | | str | str | +-----------------------------------+-------------+ | What is the capital of France? | geography | | What is 2+10? | math | | What is the capital of Germany? | geography | | What is the best python library … | programming | | Tell me a story about an ox. | story | +-----------------------------------+-------------+ In order to return to this initial version of the data at any point, let’s add and commit it to a local Oxen repository. CLI Python oxen init oxen add dataset.csv oxen commit -m "Initial dataset" [​](https://docs.oxen.ai/concepts/diffs#adding-rows) Adding Rows ------------------------------------------------------------------- Let’s start with a completely additive workflow as if we are collecting a large datasets of prompts. Add a row to the dataset by simply appending to the file. echo "20*20,math" >> dataset.csv If you want to see the changes between the current version of your file and the previous version, you can use the `oxen diff` command. By default, Oxen compares the working tree with the HEAD commit (the last committed version). CLI Python oxen diff dataset.csv Row changes: + 1 (added) shape: (1, 3) +--------+----------+-------------------+ | prompt | category | .oxen.diff.status | | --- | --- | --- | | str | str | str | +--------+----------+-------------------+ | 20*20 | math | added | +--------+----------+-------------------+ As you can see Oxen found the one added row and augmented the data frame with an `.oxen.diff.status` column to show the status of the row. There are three possible values for the `.oxen.diff.status` column: * `added` * `removed` * `modified` [​](https://docs.oxen.ai/concepts/diffs#removing-rows) Removing Rows ----------------------------------------------------------------------- Next remove the first entry of the file to see how Oxen handles deletions. We will use the `sed` command with the in place flag `-i` to remove the first row from the file. sed -i '' '2d' dataset.csv (Note: the `-i ''` flag is for MacOS, if you are using Linux you can simply use `-i`.) Since the file is a CSV with a header row, you will need to remove the second row hence `2d`. Verify that the first row was removed by using the `oxen diff` command. CLI Python oxen diff dataset.csv Row changes: + 1 (added) - 1 (removed) shape: (2, 3) +--------------------------------+-----------+-------------------+ | prompt | category | .oxen.diff.status | | --- | --- | --- | | str | str | str | +--------------------------------+-----------+-------------------+ | What is the capital of France? | geography | removed | | 20*20 | math | added | +--------------------------------+-----------+-------------------+ [​](https://docs.oxen.ai/concepts/diffs#modifing-rows) Modifing Rows ----------------------------------------------------------------------- This is great for adding and removing rows, but what about modifying rows? Say we change the `category` of β€œgeography” to be a more generic β€œtrivia” category and add a new prompt to it β€œWhat is the fastest land animal?”. Edit the `datasets.csv` file to look like this: prompt,category What is 2+10?,math What is the capital of Germany?,trivia What is the best python library for http requests?,programming Tell me a story about an ox.,story 20*20,math What is the fastest land animal?,trivia If we run the `oxen diff` command again, we will see the changes. Row changes: + 3 (added) - 2 (removed) shape: (5, 3) +----------------------------------+-----------+-------------------+ | prompt | category | .oxen.diff.status | | --- | --- | --- | | str | str | str | +----------------------------------+-----------+-------------------+ | What is the capital of France? | geography | removed | | What is the capital of Germany? | geography | removed | | 20*20 | math | added | | What is the capital of Germany? | trivia | added | | What is the fastest land animal? | trivia | added | +----------------------------------+-----------+-------------------+ You’ll notice that for every row we modified we end up having +1 addition and +1 removal. This is because Oxen is treating the modified row as one added row and one removed row. [​](https://docs.oxen.ai/concepts/diffs#specifying-keys) Specifying Keys --------------------------------------------------------------------------- The reason that the above example treats the modified row as a new row and a removed row is because both the `prompt` and `category` columns being considered keys under the hood. `oxen diff` hashes the combination of keys in order to find differences in the data. The default keys are all the common columns between the two versions of the datasets. If you have a unique identifier for each row, you can use the `--keys` (or `-k`) flag to specify the column or columns that should be used as the primary keys. CLI Python oxen diff dataset.csv -k prompt Row changes: Ξ” 1 (modified) + 2 (added) - 1 (removed) shape: (4, 4) +----------------------------------+---------------+----------------+-------------------+ | prompt | category.left | category.right | .oxen.diff.status | | --- | --- | --- | --- | | str | str | str | str | +----------------------------------+---------------+----------------+-------------------+ | 20*20 | null | math | added | | What is the capital of France? | geography | null | removed | | What is the capital of Germany? | geography | trivia | modified | | What is the fastest land animal? | null | trivia | added | +----------------------------------+---------------+----------------+-------------------+ Great! This collapsed our added and removed row into a single modified row. The category column has now been split into two columns, `category.left` and `category.right`, to show the old and new values. Assumming these changes look good, you can add and commit the changes to your local repository. CLI Python oxen add dataset.csv oxen commit -m "Added and removed rows" [​](https://docs.oxen.ai/concepts/diffs#adding-columns) Adding Columns ------------------------------------------------------------------------- Adding and removing rows is great, but what about changes to the schema itself? Instead of using the prompt as a key, let’s add an `id` column to the dataset and use that as the key. Let’s also add an `answer` column to the dataset, so that we can evaluate the responses. Update your raw csv with the new columns like so: id,prompt,answer,category 0,What is 2+10?,12,math 1,What is the capital of Germany?,Berlin,trivia 2,What is the best python library for http requests?,requests,programming 3,Tell me a story about an ox.,I am sorry I cannot do that.,story 4,20*20,400,math 5,What is the fastest land animal?,cheetah,trivia Now if you run the `oxen diff` command, you will see that it automatically detects the added columns and displays the new values in `id.right` and `answer.right`. CLI Python oxen diff dataset.csv Column changes: + id (i64) + answer (str) Row changes: Ξ” 6 (modified) shape: (6, 5) +-----------------------------------+-------------+----------+------------------------------+-------------------+ | prompt | category | id.right | answer.right | .oxen.diff.status | | --- | --- | --- | --- | --- | | str | str | i64 | str | str | +-----------------------------------+-------------+----------+------------------------------+-------------------+ | 20*20 | math | 4 | 400 | modified | | What is 2+10? | math | 0 | 12 | modified | | What is the best python library … | programming | 2 | requests | modified | | Tell me a story about an ox. | story | 3 | I am sorry I cannot do that. | modified | | What is the capital of Germany? | trivia | 1 | Berlin | modified | | What is the fastest land animal? | trivia | 5 | cheetah | modified | +-----------------------------------+-------------+----------+------------------------------+-------------------+ Removing a column would show the values in columns called `.left` to show the values in columns that are now missing. If you are happy with the changes, you can add and commit the changes to your local repository. CLI Python oxen add dataset.csv oxen commit -m "Added id and answer column" [​](https://docs.oxen.ai/concepts/diffs#specifying-compares) Specifying Compares ----------------------------------------------------------------------------------- Not only can you specify keys to narrow down the scope of what fields oxen hashes, but you can also specify columns to compare with the `--compares` (`-c`) flag. This specifies the fields oxen compares. You can think of the keys as the fields that are hashed to create a unique id to tell if a row was added or removed. The compares are the fields that are compared to check if a row was modified. By default if you specify a single key, the rest of the columns become the compares. If you specify multiple keys, the compares are all the columns that are not keys. To see this in action, let’s add one row, remove one row, and modify 3 existing ones to demonstrate how this works. In this case we will only modify values of the `answer` column. Overwrite the `dataset.csv` file with the following data. id,prompt,answer,category 0,What is 2+10?,12,math 1,What is the capital of Germany?,The capital of Germany is Berlin,trivia 3,Tell me a story about an ox.,I am sorry Hal.,story 4,20*20,20*20=400,math 5,What is the fastest land animal?,cheetah,trivia 6,What is Oxen.ai?,Imagine git - but can handle large datasets,trivia Since we only modified the answers in this dataset and not the category or the prompt, we can use the `-c` flag to specify that we are only interested in changes in the `answer` column. CLI Python oxen diff dataset.csv -k id,prompt -c answer Row changes: Ξ” 3 (modified) + 1 (added) - 1 (removed) shape: (5, 5) +-----+-----------------------------+----------------------------+------------------------+-------------------+ | id | prompt | answer.left | answer.right | .oxen.diff.status | | --- | --- | --- | --- | --- | | i64 | str | str | str | str | +-----+-----------------------------+----------------------------+------------------------+-------------------+ | 1 | What is the capital of | The capital of Germany is | Berlin | modified | | | Germany? | Berlin | | | | 2 | What is the best python | null | requests | added | | | library … | | | | | 3 | Tell me a story about an | I am sorry Hal. | I am sorry I cannot do | modified | | | ox. | | that. | | | 4 | 20*20 | 20*20=400 | 400 | modified | | 6 | What is Oxen.ai? | Imagine git - but can | null | removed | | | | handle lar… | | | +-----+-----------------------------+----------------------------+------------------------+-------------------+ Contrast this with a default diff which will show 8 changes, 4 added and 4 removed, and you can see the id field is duplicated because we are flagging one addition and one removal for each changed row. CLI Python oxen diff dataset.csv Row changes: + 4 (added) - 4 (removed) shape: (8, 5) +-----+----------------------------------+----------------------------------+-------------+-------------------+ | id | prompt | answer | category | .oxen.diff.status | | --- | --- | --- | --- | --- | | i64 | str | str | str | str | +-----+----------------------------------+----------------------------------+-------------+-------------------+ | 1 | What is the capital of Germany? | Berlin | trivia | added | | 1 | What is the capital of Germany? | The capital of Germany is Berlin | trivia | removed | | 2 | What is the best python library | requests | programming | added | | | … | | | | | 3 | Tell me a story about an ox. | I am sorry Hal. | story | removed | | 3 | Tell me a story about an ox. | I am sorry I cannot do that. | story | added | | 4 | 20*20 | 20*20=400 | math | removed | | 4 | 20*20 | 400 | math | added | | 6 | What is Oxen.ai? | Imagine git - but can handle | trivia | removed | | | | lar… | | | +-----+----------------------------------+----------------------------------+-------------+-------------------+ A diff that only specifies a key will show the correct number of changes, but it may have many columns that are not relevant to the changes you are interested in. This is because under the hood Oxen infers the compares to be the remaining columns. Having more control over the compares is where the `-c` flag comes in handy. To see how this works, try using the `-k` flag on the same dataset without any compares. CLI Python oxen diff dataset.csv -k id Row changes: Ξ” 3 (modified) + 1 (added) - 1 (removed) shape: (5, 7) +-----+-----------------+-----------------+-----------------+---------------+----------------+----------------+ | id | prompt | answer.left | answer.right | category.left | category.right | .oxen.diff.sta | | --- | --- | --- | --- | --- | --- | tus | | i64 | str | str | str | str | str | --- | | | | | | | | str | +-----+-----------------+-----------------+-----------------+---------------+----------------+----------------+ | 1 | What is the | The capital of | Berlin | trivia | trivia | modified | | | capital of | Germany is | | | | | | | Germany? | Berlin | | | | | | 2 | What is the | null | requests | null | programming | added | | | best python | | | | | | | | library … | | | | | | | 3 | Tell me a story | I am sorry Hal. | I am sorry I | story | story | modified | | | about an ox. | | cannot do that. | | | | | 4 | 20*20 | 20*20=400 | 400 | math | math | modified | | 6 | What is | Imagine git - | null | trivia | null | removed | | | Oxen.ai? | but can handle | | | | | | | | lar… | | | | | +-----+-----------------+-----------------+-----------------+---------------+----------------+----------------+ The above output is `(5 rows x 7 columns)` which isn’t too bad, but if you have a dataset with many columns, it can quickly become overwhelming with irrelevant information. If you know where to look, you can use the `-c` flag to narrow down the scope of the diff. [​](https://docs.oxen.ai/concepts/diffs#saving-results) Saving Results ------------------------------------------------------------------------- The `--output` (`-o`) flag can be used to save the results of the diff to a new file. This is useful if you want to save the results of the diff to a new file for further inspection or to share with others. CLI Python oxen diff dataset.csv -o diff.csv The above command will save the results of the diff to a new file called `diff.csv`. You can then load it into a jupyter notebook, pandas, or even back into Oxen to do more analysis on the results. [​](https://docs.oxen.ai/concepts/diffs#real-world-example) Real World Example --------------------------------------------------------------------------------- To drive all these features home, imagine you have taken the dataset above and run it through an LLM with a prompt to get the responses. You have saved the results in a new file called `model_results.csv`. Below is an example script that runs the prompts through `gpt-3.5-turbo` and saves the results to a new file. This script uses the `openai` python package to interact with the OpenAI API. [process\_csv\_with\_openai.py](https://www.oxen.ai/datasets/diff-examples/file/main/process_with_openai.py) import csv import time from openai import OpenAI import argparse import os client = OpenAI( # This is the default and can be omitted api_key=os.environ.get("OPENAI_API_KEY"), ) def process_csv_with_gpt4(input_csv, output_csv): print(f'Processing {input_csv} with GPT-4 and writing to {output_csv}') with open(input_csv, mode='r', encoding='utf-8') as infile, open(output_csv, mode='w', newline='', encoding='utf-8') as outfile: reader = csv.DictReader(infile) fieldnames = ['id', 'prompt', 'answer', 'category', 'response', 'is_correct', 'model', 'inference_time'] writer = csv.DictWriter(outfile, fieldnames=fieldnames) writer.writeheader() for row in reader: start_time = time.time() print(f'Processing row: {row}') chat_completion = client.chat.completions.create( messages=[\ {\ "role": "user",\ "content": row['prompt'],\ }\ ], model="gpt-3.5-turbo", ) end_time = time.time() inference_time = end_time - start_time # Simplified correctness check; customize based on your needs print(f'Chat completion: {chat_completion}') response = chat_completion.choices[0].message.content.strip() is_correct = 'yes' if row['answer'].lower() in response.lower() else 'no' writer.writerow({ 'id': row['id'], 'prompt': row['prompt'], 'answer': row['answer'], 'category': row['category'], 'response': response, 'is_correct': is_correct, 'model': 'gpt-3.5-turbo', # Adjust based on the model used 'inference_time': inference_time }) # main if __name__ == '__main__': # argparse can be used to accept input/output file names from command line parser = argparse.ArgumentParser(description='Process CSV with GPT-4') parser.add_argument('input_csv', help='Input CSV file') parser.add_argument('output_csv', help='Output CSV file') args = parser.parse_args() process_csv_with_gpt4(args.input_csv, args.output_csv) Run this script on the `dataset.csv` file to get the `model_results.csv` file. python process_csv_with_openai.py dataset.csv model_results.csv Quickly inspect the `model_results.csv` file with the `oxen df` command to make sure the csv was created correctly. oxen df model_results.csv Output: shape: (6, 8) +-----+--------------------------+------------------------+-------------+--------------------------------+------------+-------+----------------+ | id | prompt | answer | category | response | is_correct | model | inference_time | | --- | --- | --- | --- | --- | --- | --- | --- | | i64 | str | str | str | str | str | str | f64 | +-----+--------------------------+------------------------+-------------+--------------------------------+------------+-------+----------------+ | 0 | What is 2+10? | 12 | math | 2+10=12 | yes | gpt-4 | 0.750142 | | 1 | What is the capital of | Berlin | trivia | Berlin | yes | gpt-4 | 0.428595 | | | Germany? | | | | | | | | 2 | What is the best python | requests | programming | There is no one best library | yes | gpt-4 | 3.663857 | | | library … | | | for… | | | | | 3 | Tell me a story about an | I am sorry I cannot do | story | Once upon a time in a small | no | gpt-4 | 7.15331 | | | ox. | that. | | vill… | | | | | 4 | 20*20 | 400 | math | 400 | yes | gpt-4 | 0.422363 | | 5 | What is the fastest land | cheetah | trivia | The fastest land animal is the | yes | gpt-4 | 0.91197 | | | animal? | | | c… | | | | +-----+--------------------------+------------------------+-------------+--------------------------------+------------+-------+----------------+ This dataset has the same `id`, `prompt`, `answer`, and `category` columns as the original dataset, but it also has some additional columns such as `response`, `is_correct`, `model`, and `inference_time`. Add and commit the model results to your local repository. oxen add model_results.csv oxen commit -m "Added model results" Let’s say you tweaked the prompt and wanted to run the dataset through the LLM again. Since you have the results versioned in your local repository, you can fearlessly overwrite the file and run the `oxen diff` command to see the differences. Overwrite the `model_results.csv` file with the new results. id,prompt,answer,category,response,is_correct,model,inference_time 0,What is 2+10?,12,math,12,true,model-2,0.21 1,What is the capital of Germany?,Berlin,trivia,Berlin,true,model-2,0.12 2,What is the best python library for http requests?,requests,programming,requests,true,model-2,0.31 3,Tell me a story about an ox.,I am sorry I cannot do that.,story,I am sorry I cannot do that.,true,model-2,0.23 4,20*20,400,math,400,true,model-2,0.09 5,What is the fastest land animal?,cheetah,trivia,cheetah,true,model-2,0.41 If we do a base diff without any flags, we will see that every row is has been marked as added and removed, since the `model` and `inference_time` columns could be different for each row. CLI Python oxen diff dataset.csv Row changes: + 6 (added) - 6 (removed) shape: (12, 9) +-----+----------------------------------+---------+----------+---+------------+---------+----------------+-------------------+ | id | prompt | answer | category | … | is_correct | model | inference_time | .oxen.diff.status | | --- | --- | --- | --- | | --- | --- | --- | --- | | i64 | str | str | str | | bool | str | f64 | str | +-----+----------------------------------+---------+----------+---+------------+---------+----------------+-------------------+ | 4 | 20*20 | 400 | math | … | true | model-2 | 0.09 | added | | 4 | 20*20 | 400 | math | … | true | model-1 | 0.1 | removed | | 0 | What is 2+10? | 12 | math | … | true | model-2 | 0.21 | added | | 0 | What is 2+10? | 12 | math | … | true | model-1 | 0.23 | removed | | … | … | … | … | … | … | … | … | … | | 1 | What is the capital of Germany? | Berlin | trivia | … | true | model-2 | 0.12 | added | | 1 | What is the capital of Germany? | Berlin | trivia | … | false | model-1 | 0.11 | removed | | 5 | What is the fastest land animal? | cheetah | trivia | … | true | model-1 | 0.4 | removed | | 5 | What is the fastest land animal? | cheetah | trivia | … | true | model-2 | 0.41 | added | +-----+----------------------------------+---------+----------+---+------------+---------+----------------+------------ This is clearly not what we want. We want to see the differences in the `response` and `is_correct` columns, and ignore the `model` and `inference_time` columns. In combination with the `--keys` flag, you can use the `--compares` (or `-c`) flag to specify the columns you are interested in. CLI Python oxen diff model_results.csv -k id,prompt,answer -c response,is_correct Row changes: Ξ” 2 (modified) shape: (2, 8) +-----+----------------+----------------+----------------+----------------+----------------+----------------+---------------+ | id | prompt | answer | response.left | response.right | is_correct.lef | is_correct.rig | .oxen.diff.st | | --- | --- | --- | --- | --- | t | ht | atus | | i64 | str | str | str | str | --- | --- | --- | | | | | | | bool | bool | str | +-----+----------------+----------------+----------------+----------------+----------------+----------------+---------------+ | 1 | What is the | Berlin | Munich | Berlin | false | true | modified | | | capital of | | | | | | | | | Germany? | | | | | | | | 3 | Tell me a | I am sorry I | Once upon a | I am sorry I | false | true | modified | | | story about an | cannot do | time | cannot do | | | | | | ox. | that. | | that. | | | | +-----+----------------+----------------+----------------+----------------+----------------+----------------+---------------+ This now narrows down the scope of the diff to only the `response` and `is_correct` columns. We can see that the new model has a different response for the prompts `1` and `3`. Diff allows us to quickly narrow down the responses that model 1 and model 2 disagree on, and which ones are correct. [​](https://docs.oxen.ai/concepts/diffs#next-up-comparing-different-files) Next Up: Comparing Different Files ---------------------------------------------------------------------------------------------------------------- Now that you understand the basics of the diff command, you may be wondering if you can compare different files or different commits. The answer is yes! [​](https://docs.oxen.ai/concepts/diffs#comparing-different-files) Comparing Different Files ----------------------------------------------------------------------------------------------- You can compare two local files (that may not be in the repository) by passing both file paths: CLI Python oxen diff model_results_1.csv model_results_2.csv [​](https://docs.oxen.ai/concepts/diffs#comparing-different-commits) Comparing Different Commits --------------------------------------------------------------------------------------------------- You can also compare the same file across different commits or branches using commit identifiers: CLI Python # Compare a specific commit with HEAD oxen diff abc123 dataset.csv # Compare two commits using range syntax oxen diff abc123..def456 dataset.csv # Compare two commits oxen diff abc123 def456 dataset.csv # Compare branches oxen diff main..feature-branch dataset.csv This is useful for tracking how your dataset has evolved over time, comparing different versions of model results, or understanding what changed between branches. You can find all the example data used in this guide in the [datasets/diff-examples repository](https://www.oxen.ai/datasets/diff-examples) . [Next: Comparing Different Files](https://docs.oxen.ai/concepts/compare) [πŸ”₯ Performance](https://docs.oxen.ai/examples/data/performance) [🏷️ File Metadata](https://docs.oxen.ai/concepts/file_metadata) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # πŸ€– Chat Completions - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/examples/fine-tuning/chat_completions#content-area) This tutorial will show you how to fine-tune an LLM on a history of messages. If you have traces from a chat application or have curated a dataset, you can use them to fine-tune a model to be more accurate, faster, or tailored to your use-case. Often a small, specialized model can outperform a larger, more general model for a specific use-case when it comes to latency, accuracy, and cost. [​](https://docs.oxen.ai/examples/fine-tuning/chat_completions#upload-your-dataset) Upload Your Dataset ---------------------------------------------------------------------------------------------------------- For this example, we are teaching the model to answer questions based on context that is supplied in the system prompt. You can follow along with the [Tutorials/CoQA](https://www.oxen.ai/Tutorials/CoQA/file/main/train_coqa.jsonl) dataset containing over 7,000 rows of chat messages. Each row of the dataset contains a conversation between a user and an assistant. ![dataset](https://mintcdn.com/oxenai/cXqZfdhecMqwRHTK/images/fine_tuning/chat-completions/dataset.png?w=2500&fit=max&auto=format&n=cXqZfdhecMqwRHTK&q=85&s=7bc68072eabf1892cae07267312c8bd3) This particular dataset focuses on multi-turn conversations. Each example starts by grounding some context taken from a news article or a Wikipedia article. The user then asks a question about the context, and the assistant answers the question. There are multiple back and forth exchanges between the user and the assistant, each question building on the previous one. Here’s a few examples from the paper to give you an idea of the task. ![coqa-questions](https://mintcdn.com/oxenai/cXqZfdhecMqwRHTK/images/fine_tuning/chat-completions/coqa-questions.png?w=2500&fit=max&auto=format&n=cXqZfdhecMqwRHTK&q=85&s=deae375c2e62718f121b14471400e219) Notice that you would not be able to answer the second question without the first question being answered first. [​](https://docs.oxen.ai/examples/fine-tuning/chat_completions#dataset-format) Dataset Format ------------------------------------------------------------------------------------------------ Oxen.ai supports datasets in a variety of file formats, including jsonl, csv, and parquet. The only requirement is that you have a column where each row is a list of messages. Each message is an dictionary with a `role` and `content` key. The `role` can be β€œsystem”, β€œuser”, or β€œassistant”. The `content` is the message content. { "conversations": [\ {\ "messages": [\ {"role": "system", "content": "You are a helpful assistant that answers questions based on the provided context."},\ {"role": "user", "content": "What is the easiest way to fine-tune a model?"},\ {"role": "assistant", "content": "Oxen.ai allows you to fine-tune a model with a few clicks. Just upload your dataset, select your base model, and click 'Fine-tune'."},\ {"role": "user", "content": "What modalities does Oxen.ai support?"},\ {"role": "assistant", "content": "Oxen.ai supports text, image, and video generation."}\ ]\ }\ ] } [​](https://docs.oxen.ai/examples/fine-tuning/chat_completions#fine-tuning-the-model) Fine-Tuning The Model -------------------------------------------------------------------------------------------------------------- Once you have uploaded your dataset, click the β€œActions” button and select β€œFine-tune a model”. ![Fine-tune button](https://mintcdn.com/oxenai/cXqZfdhecMqwRHTK/images/fine_tuning/chat-completions/fine-tune-action.png?w=2500&fit=max&auto=format&n=cXqZfdhecMqwRHTK&q=85&s=3116f1e0dd86da0994372083f8e709c2) Next select your base model, the messages source, whether you’d like to use LoRA or not. We recommend starting with a smaller model like [Qwen3-0.6B](https://www.oxen.ai/ai/models/qwen-qwen3-0-6b) for faster iteration, or a larger model like [Llama 3.1 8B](https://www.oxen.ai/ai/models/meta-llama-3-1-8b-instruct) for better performance on complex conversations. ![Fine-tune first page](https://mintcdn.com/oxenai/ccInAwcxb-C1RCGU/images/fine_tuning/text-generation/fine-tune-qwen3-0.6b.png?w=2500&fit=max&auto=format&n=ccInAwcxb-C1RCGU&q=85&s=f648abcc9257472e60c6dcac9d9e66d5) For our Advance Options, you can have control over hyper-parameters and model specifications like learning rate, batch size, and number of epochs. These settings can help you optimize for your specific use case, whether you prioritize training speed, model accuracy, or computational efficiency. ![Advanced options photo](https://mintcdn.com/oxenai/T4_0EQB1ENVXiGMM/images/fine_tuning/text-generation/advanced-settings.png?w=2500&fit=max&auto=format&n=T4_0EQB1ENVXiGMM&q=85&s=2e160df057e2a4326953fbea321a84cb) [​](https://docs.oxen.ai/examples/fine-tuning/chat_completions#monitoring-the-fine-tune) Monitoring the Fine-Tune -------------------------------------------------------------------------------------------------------------------- While we’re fine-tuning your model, you’ll be able to see the configuration, logs, and metrics of the fine-tuning. This helps you track the model’s progress and identify if you need to adjust any hyperparameters or stop training early if the model has converged. ![Metrics example](https://mintcdn.com/oxenai/GvHCMKbbr_BpHEwk/images/fine_tuning/fine-tune-loss.png?w=2500&fit=max&auto=format&n=GvHCMKbbr_BpHEwk&q=85&s=0eccd01e926eaa0294c0f3603d634302) [​](https://docs.oxen.ai/examples/fine-tuning/chat_completions#deploying-the-model) Deploying the Model ---------------------------------------------------------------------------------------------------------- Once your fine-tuning is complete, go to the info page and click β€œDeploy”. Oxen.ai will spin up a dedicated endpoint for your model to access via a chat interface or through the API. After the model is deployed, you can click the β€œChat with this model” button to open a chat interface where you can test multi-turn conversations. ![fine-tuned chatbot](https://mintcdn.com/oxenai/cXqZfdhecMqwRHTK/images/fine_tuning/chat-completions/chat-button.png?w=2500&fit=max&auto=format&n=cXqZfdhecMqwRHTK&q=85&s=535d62bf8667baa7303f3e7d99d0d668) This will bring up a chat interface where you can test your model with back-and-forth conversations to see how it maintains context across multiple turns. ![fine-tuned chatbot](https://mintcdn.com/oxenai/cXqZfdhecMqwRHTK/images/fine_tuning/chat-completions/chat-interface.png?w=2500&fit=max&auto=format&n=cXqZfdhecMqwRHTK&q=85&s=1a14915d0c90e7f019443034dbae12f2) [​](https://docs.oxen.ai/examples/fine-tuning/chat_completions#model-api) Model API -------------------------------------------------------------------------------------- You can integrate it into your application using the API. The API is OpenAI compatible, so you can use any OpenAI client library to interact with it. The base URL for the API is `https://hub.oxen.ai/api`. For chat completions, you’ll send a list of messages that includes the conversation history. Each message should have a `role` (either β€œuser”, β€œassistant”, or β€œsystem”) and `content`. curl -X POST https://hub.oxen.ai/api/ai/chat/completions \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "your-model-id", "messages": [\ {"role": "system", "content": "You are a helpful assistant that answers questions based on the provided context."},\ {"role": "user", "content": "What is the capital of France?"},\ {"role": "assistant", "content": "The capital of France is Paris."},\ {"role": "user", "content": "What is its population?"}\ ] }' Make sure to replace `your-model-id` with the ID of your fine-tuned model. The model will use the entire conversation history to generate contextually appropriate responses. [​](https://docs.oxen.ai/examples/fine-tuning/chat_completions#next-steps) Next Steps ---------------------------------------------------------------------------------------- Feel free to join our [Discord](https://discord.com/invite/s3tBEn7Ptg) and ask us or the community any questions you have, we have a community of developers and machine learning experts who are happy to help you out. [πŸ’¬ Text Generation](https://docs.oxen.ai/examples/fine-tuning/text_generation) [πŸ‘οΈ Vision Language Models](https://docs.oxen.ai/examples/fine-tuning/image_understanding) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # πŸ‘οΈ Vision Language Models - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/examples/fine-tuning/image_understanding#content-area) Oxen.ai allows you to fine-tune a Vision Language Model (VLM) to understand images and videos. Fine-tuned VLMs are great way to process data at scale with high throughput, low latency, and high accuracy in your domain. When you can’t describe your task in a text prompt, you can fine-tune a VLM to understand it. [​](https://docs.oxen.ai/examples/fine-tuning/image_understanding#preparing-the-dataset) Preparing the dataset ----------------------------------------------------------------------------------------------------------------- When fine-tuning a VLM, you need a dataset that contains the images, user prompts, and responses that are expected from the VLM. The dataset format can be a csv, jsonl, or parquet file with a column that contains the _relative path_ to the image in the repository. To see an example of the dataset format, check out the [Tutorials/Geometry3K](https://www.oxen.ai/Tutorials/Geometry3K/file/main/train.parquet) dataset. Each row in this dataset should have an associated image in the repository stored at `images/train/image_{n}.png`. ![Dataset Format](https://mintcdn.com/oxenai/yUwAxpiUabhBLMLm/images/fine_tuning/image-understanding/dataset.png?w=2500&fit=max&auto=format&n=yUwAxpiUabhBLMLm&q=85&s=1eb045208502ad6cf2f7e34547e61d57) To upload the dataset you can use the [oxen command line interface](https://docs.oxen.ai/getting-started/command-line/start_repository) . Here’s an example of creating a repository from the command line and uploading data: # Navigate to the directory containing your dataset cd path/to/data # Set your username and repository name export USERNAME=YOUR_USERNAME export REPO_NAME=YOUR_REPO_NAME # Create a new repository on the remote server oxen create-remote --name $USERNAME/$REPO_NAME # Set the remote origin to the new repository oxen config --set-remote origin https://hub.oxen.ai/$USERNAME/$REPO_NAME # Add the dataset to the repository oxen add . # Push the dataset to the remote server oxen push [​](https://docs.oxen.ai/examples/fine-tuning/image_understanding#rendering-images) Rendering Images ------------------------------------------------------------------------------------------------------- In order to view the images, you will need to enable image rendering on your images column. Click the β€œβœοΈβ€ edit button above the dataset, then edit the column to enable image rendering. The video below shows the whole process. Your browser does not support the video tag. [​](https://docs.oxen.ai/examples/fine-tuning/image_understanding#fine-tuning-a-model) Fine-tuning a model ------------------------------------------------------------------------------------------------------------- With your images labeled and you are happy with the quality and quantity, it is time to kick off your first fine-tune. Click the β€œActions” button and select β€œFine-Tune a Model”. ![Kick off Fine-Tune](https://mintcdn.com/oxenai/yUwAxpiUabhBLMLm/images/fine_tuning/image-understanding/fine-tune-action.png?w=2500&fit=max&auto=format&n=yUwAxpiUabhBLMLm&q=85&s=6907e36fb4260a414f5ef526d96fcc24) This will take you to the fine-tune page where you can select the model you want to fine-tune. Select the `Image to Text` task, and select the `Qwen/Qwen3-VL-2B-Instruct` model. Make sure the β€œImage” column is set to the proper `image` column, and the β€œPrompt” and β€œResponse” columns are set to the inputs and outputs you expect. ![Select Task](https://mintcdn.com/oxenai/yUwAxpiUabhBLMLm/images/fine_tuning/image-understanding/select-task.png?w=2500&fit=max&auto=format&n=yUwAxpiUabhBLMLm&q=85&s=59c5d4595fdbbb5b04d27d22a5b3474a) All you have to do now is click β€œStart Fine-Tune”, sit back, grab a coffee, and watch the model learn. [​](https://docs.oxen.ai/examples/fine-tuning/image_understanding#deploying-the-model) Deploying the Model ------------------------------------------------------------------------------------------------------------- Once the model is trained, you can deploy it to the cloud and start using it in your applications. Click the β€œDeploy” button and we will spin up a dedicated GPU instance for you. ![Deploy Model](https://mintcdn.com/oxenai/yUwAxpiUabhBLMLm/images/fine_tuning/image-understanding/deploy-model.png?w=2500&fit=max&auto=format&n=yUwAxpiUabhBLMLm&q=85&s=d56f5299ad37c8c15d4ab6b4fe4efedc) Once the model is deployed, you can chat with it in the UI or via the API. Replace the `model` name with the name of your deployed model. curl -X POST \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "oxen:ox-comfortable-sapphire-locust", "messages": [\ {\ "role": "user",\ "content": [\ {\ "type": "text",\ "text": "What is in this image?"\ },\ {\ "type": "image_url",\ "image_url": {\ "url": "https://oxen.ai/assets/images/homepage/hero-ox.png"\ }\ }\ ]\ }\ ] }' https://hub.oxen.ai/api/ai/chat/completions For more ways to call the API, check out the [inference](https://docs.oxen.ai/examples/inference/vision_language_models) examples. [​](https://docs.oxen.ai/examples/fine-tuning/image_understanding#downloading-the-weights) Downloading the Weights --------------------------------------------------------------------------------------------------------------------- One of the benefits of using Oxen.ai is we give you the flexibility of deploying to our cloud or managing your own infrastructure. If you want to download the model weights, you can click the path to the model weights and download them. CLI Python oxen download user-name/repo-name path/to/model.safetensors --revision COMMIT_OR_BRANCH [​](https://docs.oxen.ai/examples/fine-tuning/image_understanding#need-help-fine-tuning) Need Help Fine-Tuning? ------------------------------------------------------------------------------------------------------------------ If you need help fine-tuning your model, contact us at [hello@oxen.ai](mailto:hello@oxen.ai) and we are happy to help you get started. [πŸ€– Chat Completions](https://docs.oxen.ai/examples/fine-tuning/chat_completions) [πŸ–ΌοΈ Image Generation](https://docs.oxen.ai/examples/fine-tuning/image_generation) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # πŸŽ₯ Video Generation - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/examples/fine-tuning/video_generation#content-area) Oxen.ai allows you to fine-tune a video generation model to generate higher quality videos with consistent brand assets, characters, products, or your own style with no infrastructure setup required. Fine-tune your models with a few clicks, deploy your model to an endpoint, and own all your weights to download and use anywhere. ![Video Generation](https://mintcdn.com/oxenai/UqDpJG7fRRB6Mpg9/images/fine_tuning/text-to-video/will-smith.gif?s=71803f6bd69417ec56eecc226f1520c2) [​](https://docs.oxen.ai/examples/fine-tuning/video_generation#example-generating-videos-of-an-actor) Example: Generating Videos of an Actor ----------------------------------------------------------------------------------------------------------------------------------------------- In this example, we are going to fine-tune WAN 2.2 to be able to generate videos of a specific character or actor. We will be using the actor β€œWill Smith” in our example to see if we can get the model to generate a high quality video of him eating spaghetti. You’ll see in the image on the left that at the start of the fine-tune WAN has no concept of β€œWill Smith” the actor, and by the end (image on the right) we have captured his face and expression. ![Will Smith Before and After](https://mintcdn.com/oxenai/T4_0EQB1ENVXiGMM/images/fine_tuning/text-to-video/will-smith-before-after.png?w=2500&fit=max&auto=format&n=T4_0EQB1ENVXiGMM&q=85&s=3916d5196f9c864684c13b3b549a9098) [​](https://docs.oxen.ai/examples/fine-tuning/video_generation#creating-the-training-dataset) Creating the Training Dataset ------------------------------------------------------------------------------------------------------------------------------ When fine-tuning video generation models, you need a dataset that contains the images and descriptions of the images. The model will learn the style and character from the image and describe alone, then can extrapolate to the rest of the video. The expected format is a csv, jsonl or parquet file with a column that contains the _relative path_ to the image in the repository, and a column that contains the description of the image. ![Will Smith Dataset](https://mintcdn.com/oxenai/T4_0EQB1ENVXiGMM/images/fine_tuning/text-to-video/will-smith-dataset.png?w=2500&fit=max&auto=format&n=T4_0EQB1ENVXiGMM&q=85&s=0bd62d0fa725dc514543d280f5af10f8) There are two columns where each row contains: 1. `image` - the relative path to the image in the oxen repository 2. `prompt` - the description of the image in the row In order to get started, create a repository, then click the β€œAdd Files” button. ![Add Files](https://mintcdn.com/oxenai/T4_0EQB1ENVXiGMM/images/fine_tuning/text-to-video/add-files.png?w=2500&fit=max&auto=format&n=T4_0EQB1ENVXiGMM&q=85&s=ce8f0bc1180dedc837d039309d396d67) Then you can drag and drop a zip file of images which will be automatically unzipped into your repository. Write a commit message before uploading so that your team can know why you added these images. This will be handy when iterating on your training datasets. Once your images have been uploaded, navigate into the folder and click the β€œFolder to Dataset” button. ![Folder to Dataset](https://mintcdn.com/oxenai/T4_0EQB1ENVXiGMM/images/fine_tuning/text-to-video/folder-to-dataset-button.png?w=2500&fit=max&auto=format&n=T4_0EQB1ENVXiGMM&q=85&s=94b97189828463799c688f1579c12698) This will grab all of the relative paths from the folder, and create a parquet file with a column called `image` that contains the relative path to the image. ![Folder to Dataset](https://mintcdn.com/oxenai/T4_0EQB1ENVXiGMM/images/fine_tuning/text-to-video/folder-to-dataset.png?w=2500&fit=max&auto=format&n=T4_0EQB1ENVXiGMM&q=85&s=89a65f42b5e4437984143dddb52de356) To view the images, you will need to enable image rendering on the `image` column. Click the β€œβœοΈβ€ edit button above the dataset, then edit the column to enable image rendering. The video below shows the whole process. Your browser does not support the video tag. [​](https://docs.oxen.ai/examples/fine-tuning/video_generation#auto-captioning-the-images) Auto-Captioning the Images ------------------------------------------------------------------------------------------------------------------------ Now that we have a dataset, we need to create a description for each image. We can do this by clicking the β€œActions” button and selecting β€œRun Inference”. ![Run Inference](https://mintcdn.com/oxenai/GvHCMKbbr_BpHEwk/images/data-frames/run-inference.png?w=2500&fit=max&auto=format&n=GvHCMKbbr_BpHEwk&q=85&s=f5ab338d8b7e18a0490a6deb360d00f3) You will need to select a model that is able to go from `image -> text` from the dropdown on the left. Then write a prompt that describes what you want in the caption and any formatting you want to apply. ![Run Inference](https://mintcdn.com/oxenai/T4_0EQB1ENVXiGMM/images/fine_tuning/text-to-video/caption-dataset-sample.png?w=2500&fit=max&auto=format&n=T4_0EQB1ENVXiGMM&q=85&s=c49b5a4f21b0f59bd994146144ec05c9) In this case, we are using the prompt: Describe what the actor is doing and wearing in one sentence or less. Each sentence should start with "Will Smith is" {file_path} Note: You must supply the curly braces `{}` around the `file_path` column in the prompt to know what column to use for the image. When you feed good about your prompt after looking at your samples click the β€œNext ->” button to decide where you want to save the results. By default, the results will create a new version of the existing file. Now sit back and relax as the model captions your images 😌 β˜•οΈ. ![Run Inference](https://mintcdn.com/oxenai/T4_0EQB1ENVXiGMM/images/fine_tuning/text-to-video/captioning.png?w=2500&fit=max&auto=format&n=T4_0EQB1ENVXiGMM&q=85&s=5ab8d57034a646cd0176f6e0b8b2ee9b) Once the model has finished captioning the images, you can see the captions in the specified column. Click the button to β€œView File at Commit” to return to the dataset viewer. ![Captions](https://mintcdn.com/oxenai/UqDpJG7fRRB6Mpg9/images/fine_tuning/text-to-video/captioning-finished.png?w=2500&fit=max&auto=format&n=UqDpJG7fRRB6Mpg9&q=85&s=60f91cab668b8e4ddf49911544621838) If you want to further refine your prompts, you can always click the β€œβœοΈβ€ edit button on the dataset viewer and hand label the captions. [​](https://docs.oxen.ai/examples/fine-tuning/video_generation#kicking-off-the-fine-tune) Kicking off the Fine-Tune ---------------------------------------------------------------------------------------------------------------------- With your images labeled and you are happy with the quality and quantity, it is time to kick off your first fine-tune. Click the β€œActions” button and select β€œFine-Tune a Model”. ![Kick off Fine-Tune](https://mintcdn.com/oxenai/T4_0EQB1ENVXiGMM/images/fine_tuning/text-to-video/fine-tune-a-model-button.png?w=2500&fit=max&auto=format&n=T4_0EQB1ENVXiGMM&q=85&s=674369ab66936120d5f748bb08422786) This will take you to the fine-tune page where you can select the model you want to fine-tune. First select the β€œFine-Tune Task” of `Video Generation`. Then select the `Wan-AI/Wan2.2-T2V-A14B-Diffusers` model. Make sure the β€œImage” column is set to `file_path` column, and the β€œPrompt” column is set to `caption` column. In the β€œSamples” section you can specify a few prompts that you want to test out as the model is training. This will help you get a feel for how the model is performing and make sure it is learning what you want. ![Write Prompts](https://mintcdn.com/oxenai/T4_0EQB1ENVXiGMM/images/fine_tuning/text-to-video/fine-tune-prompts.png?w=2500&fit=max&auto=format&n=T4_0EQB1ENVXiGMM&q=85&s=513e9fa9a834146ac692486c996d6ac1) [​](https://docs.oxen.ai/examples/fine-tuning/video_generation#watching-the-model-learn) Watching the Model Learn -------------------------------------------------------------------------------------------------------------------- As your model is training, Oxen will automatically sample videos that you specified in the β€œSamples” section in the previous step. You can see that the model is starting to learn the actor’s face and expression after a couple hundred steps. Your browser does not support the video tag. [​](https://docs.oxen.ai/examples/fine-tuning/video_generation#deploying-the-model) Deploying the Model ---------------------------------------------------------------------------------------------------------- When the model has finished training, you can deploy it to a new model by clicking the β€œDeploy Model” button. The deployment will take a few minutes to complete. ![Deploy the Model](https://mintcdn.com/oxenai/T4_0EQB1ENVXiGMM/images/fine_tuning/text-to-video/deploy-model.png?w=2500&fit=max&auto=format&n=T4_0EQB1ENVXiGMM&q=85&s=34df25e548fde98dd8072dfbc0ffcaaa) Once the model is deployed, you can use it in the playground or via the API. Replace the `model` name with the name of your deployed model. curl -X POST \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "oxen:ox-comfortable-sapphire-locust", "prompt": "An ox walking in a field", "run_fast": true }' https://hub.oxen.ai/api/ai/videos/generate [​](https://docs.oxen.ai/examples/fine-tuning/video_generation#using-the-playground) Using the Playground ------------------------------------------------------------------------------------------------------------ Click the β€œOpen Playground” button to use the model in the playground. This allows you to prompt the model with different images and prompts to see how it performs. ![Playground](https://mintcdn.com/oxenai/T4_0EQB1ENVXiGMM/images/fine_tuning/text-to-video/playground.png?w=2500&fit=max&auto=format&n=T4_0EQB1ENVXiGMM&q=85&s=fc246a0436b92c366434f69352432ed5) The playground will save a history of your prompts and images so that you can refer back to them later. [​](https://docs.oxen.ai/examples/fine-tuning/video_generation#exporting-the-model) Exporting the Model ---------------------------------------------------------------------------------------------------------- All of the model weights are stored back in your repository when the fine-tune is complete. Navigate to the fine-tune info tab, and you will see a link to the model weights. This is helpful if you want to download the weights to run in ComfyUI or your own infrastructure. ![Info Tab](https://mintcdn.com/oxenai/T4_0EQB1ENVXiGMM/images/fine_tuning/text-to-video/info-tab.png?w=2500&fit=max&auto=format&n=T4_0EQB1ENVXiGMM&q=85&s=ce7074e59560bfc6d8cd83fbf9222589) This will take you to the file viewer where you can download the model safetensors. ![File Viewer](https://mintcdn.com/oxenai/T4_0EQB1ENVXiGMM/images/fine_tuning/image-generation/file-viewer.png?w=2500&fit=max&auto=format&n=T4_0EQB1ENVXiGMM&q=85&s=7b71ab43393083ae36670916e24b83ab) You can also automatically download the weights with the [oxen cli](https://docs.oxen.ai/getting-started/command-line/start_repository) or [python library](https://docs.oxen.ai/python-api) . CLI Python oxen download user-name/repo-name path/to/model.safetensors --revision COMMIT_OR_BRANCH [​](https://docs.oxen.ai/examples/fine-tuning/video_generation#need-help-fine-tuning) Need Help Fine-Tuning? --------------------------------------------------------------------------------------------------------------- If you need help fine-tuning your model, contact us at [hello@oxen.ai](mailto:hello@oxen.ai) and we are happy to help you get started. [πŸ‘¨β€πŸŽ¨ Image Editing](https://docs.oxen.ai/examples/fine-tuning/image_editing) [βš’οΈ Installation](https://docs.oxen.ai/getting-started/install) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # πŸ‘¨β€πŸŽ¨ Image Editing - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/examples/fine-tuning/image_editing#content-area) Oxen.ai allows you to get higher quality image edits with consistent brand assets, characters, products, or your own style with no infrastructure setup required. Fine-tune your models with a few clicks, track results during training, and own all your weights to download and use anywhere. [​](https://docs.oxen.ai/examples/fine-tuning/image_editing#the-task) The Task --------------------------------------------------------------------------------- For this example, we are going to fine-tune Qwen-Image-Edit to be able to turn a photo of a Yeti Mug from a product catalogue into a photo of the mug being used in the wild. The input images will be the mug we want in the scene on a black background (left) and the output will be the mug in a beautiful scene (right). ![Reference Image](https://mintcdn.com/oxenai/T4_0EQB1ENVXiGMM/images/fine_tuning/image-edit/yeti_reference_image.png?w=2500&fit=max&auto=format&n=T4_0EQB1ENVXiGMM&q=85&s=9968449207a4c84f29722332bf2f7142) The prompt that generated the image on the right was _β€œa red headed woman sipping from the mug outdoors”_. Notice we did not have to say β€œyeti mug”, but instead we teach the model that β€œmug” in our context should always be the mug from the reference image. [​](https://docs.oxen.ai/examples/fine-tuning/image_editing#creating-a-repository) Creating a Repository ----------------------------------------------------------------------------------------------------------- Oxen.ai repositories are used to store and [version](https://docs.oxen.ai/examples/data/versioning) your data and models. We can create a new repository by clicking the β€œCreate New Repository” button in your Oxen.ai dashboard. ![Create Repository](https://mintcdn.com/oxenai/GvHCMKbbr_BpHEwk/images/fine_tuning/fine-tune-create-repo.png?w=2500&fit=max&auto=format&n=GvHCMKbbr_BpHEwk&q=85&s=7d2834a6b15ab25b7b7aee252597d40b) You will upload your dataset to the repository, and when the fine-tune is complete, the model weights will be saved to the repository on a branch. By versioning your data and models together, you can always track the data that was used to train the model. [​](https://docs.oxen.ai/examples/fine-tuning/image_editing#uploading-the-dataset) Uploading the Dataset ----------------------------------------------------------------------------------------------------------- From your repository, you can click the β€œAdd File” button to upload your dataset. The upload supports unpacking zip files if you want to upload a directory of images. ![Upload Dataset](https://mintcdn.com/oxenai/T4_0EQB1ENVXiGMM/images/fine_tuning/fine-tune-upload-file.png?w=2500&fit=max&auto=format&n=T4_0EQB1ENVXiGMM&q=85&s=87e8ae35fec43c13d7a3d9d949c9dcf9) For image editing models, you will need three things: 1. Input images 2. Reference images 3. Prompts for the edits or changes we want to make Start by collecting the input images, reference images, and uploading them to the repository. You will also need a csv file that will contain the prompts for the edits or changes we want to make. [​](https://docs.oxen.ai/examples/fine-tuning/image_editing#formatting-the-dataset) Formatting the Dataset ------------------------------------------------------------------------------------------------------------- When you upload tabular data files (like CSV, JSONL, or Parquet) to Oxen.ai, they get superpowers. For example, you can enable image rendering on your image columns to show as thumbnails in the dataset. To view the images, click the β€œβœοΈβ€ edit button above the dataset, then edit the column to enable image rendering. The video below shows the whole process. Your browser does not support the video tag. This lets you view images, reference images, and prompts all in one place. ![Yeti Images Dataset](https://mintcdn.com/oxenai/T4_0EQB1ENVXiGMM/images/fine_tuning/image-edit/yeti_data_frame.png?w=2500&fit=max&auto=format&n=T4_0EQB1ENVXiGMM&q=85&s=2bce42f444d0742d80c3364257cbfaa7) In this case we have one column called `image` that represents the output we want, and a column called `control_image` that represents the reference image that we want to feed as input. There is a third column for the `prompt` that describes the edits or changes we want to make. The image column needs to contain the **relative path** to the image from the root of the repository. For example, if the image is in the `images` folder, the path should be `images/image_0.png`. [​](https://docs.oxen.ai/examples/fine-tuning/image_editing#kicking-off-the-fine-tune) Kicking off the Fine-Tune ------------------------------------------------------------------------------------------------------------------- The other superpower your csv file gets is that you can kick off a fine-tune from the dataset page. Click the β€œActions” button and select β€œFine-Tune a Model”. ![Kick off Fine-Tune](https://mintcdn.com/oxenai/T4_0EQB1ENVXiGMM/images/fine_tuning/image-edit/yeti_fine_tune_a_model_button.png?w=2500&fit=max&auto=format&n=T4_0EQB1ENVXiGMM&q=85&s=b11b60ad74af6c127a287e66b9c2f39b) This will take you to the fine-tune page where you can select the model you want to fine-tune. Select the β€œQwen-Image-Edit” model, and make sure the β€œControl Image” column is set to `control_image` column, the β€œImage” column is set to `image` column, and the β€œPrompt” column is set to `prompt` column. ![Kick off Fine-Tune](https://mintcdn.com/oxenai/T4_0EQB1ENVXiGMM/images/fine_tuning/image-edit/select_model.png?w=2500&fit=max&auto=format&n=T4_0EQB1ENVXiGMM&q=85&s=340f19449983d1efaef2c90ff91181ba) You can also upload some test images and prompts that will be used as samples during the fine-tune. [​](https://docs.oxen.ai/examples/fine-tuning/image_editing#advanced-parameters) Advanced Parameters ------------------------------------------------------------------------------------------------------- Click the β€œAdvanced Parameters” button to see the advanced parameters for the fine-tune. You can set the learning rate, batch size, number of steps, and other parameters here. ![Fine-Tune Parameters](https://mintcdn.com/oxenai/T4_0EQB1ENVXiGMM/images/fine_tuning/image-edit/advanced_parameters.png?w=2500&fit=max&auto=format&n=T4_0EQB1ENVXiGMM&q=85&s=6789fc801650f923634eddbfbf930bd0) One of the best parts of fine-tuning with Oxen.ai is that we track all your experiments for you, so that you can always refer back to the parameters that worked best for future fine-tunes. [​](https://docs.oxen.ai/examples/fine-tuning/image_editing#monitoring-the-fine-tune) Monitoring the Fine-Tune ----------------------------------------------------------------------------------------------------------------- While the model is training, you can monitor the progress by clicking the β€œSamples” tab. This will show you the images that the model has generated so far. ![Monitor the Fine-Tune](https://mintcdn.com/oxenai/T4_0EQB1ENVXiGMM/images/fine_tuning/image-edit/monitor_the_fine_tune.png?w=2500&fit=max&auto=format&n=T4_0EQB1ENVXiGMM&q=85&s=eebc74682586a77a5f45724e86719642) [​](https://docs.oxen.ai/examples/fine-tuning/image_editing#deploying-the-model) Deploying the Model ------------------------------------------------------------------------------------------------------- When the model has finished training, you can deploy it to a new model by clicking the β€œDeploy Model” button. ![Deploy the Model](https://mintcdn.com/oxenai/T4_0EQB1ENVXiGMM/images/fine_tuning/image-edit/deploy-model-button.png?w=2500&fit=max&auto=format&n=T4_0EQB1ENVXiGMM&q=85&s=90ac2212c90a4812d91a1d7b11ead4a6) Once the model is deployed, you can use it in the playground or via the API. curl -X POST \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "model": "oxen:ox-busy-scarlet-beaver", "input_image": "https://hub.oxen.ai/api/repos/ox/Oxen-Character-Simple-Vector-Graphic/file/main/images/reference/bloxy_white_bg.png", "prompt": "Add a funny hat to the ox", "num_inference_steps": 20 }' https://hub.oxen.ai/api/ai/images/edit [​](https://docs.oxen.ai/examples/fine-tuning/image_editing#using-the-playground) Using the Playground --------------------------------------------------------------------------------------------------------- Click the β€œOpen Playground” button to use the model in the playground. This allows you to prompt the model with different images and prompts to see how it performs. ![Before and After](https://mintcdn.com/oxenai/T4_0EQB1ENVXiGMM/images/fine_tuning/image-edit/playground.png?w=2500&fit=max&auto=format&n=T4_0EQB1ENVXiGMM&q=85&s=4515268659c7df1e56b096cd91d425e7) The playground will save a history of your prompts and images so that you can refer back to them later. [​](https://docs.oxen.ai/examples/fine-tuning/image_editing#exporting-the-model) Exporting the Model ------------------------------------------------------------------------------------------------------- All of the model weights are stored back in your repository when the fine-tune is complete. Navigate to the fine-tune info tab, and you will see a link to the model weights. This is helpful if you want to download the weights to run in ComfyUI or your own infrastructure. ![Info Tab](https://mintcdn.com/oxenai/T4_0EQB1ENVXiGMM/images/fine_tuning/image-generation/info-tab.png?w=2500&fit=max&auto=format&n=T4_0EQB1ENVXiGMM&q=85&s=dca3def3e9f2503447ca5ccb7c2d99bd) This will take you to the file viewer where you can download the model safetensors. ![File Viewer](https://mintcdn.com/oxenai/T4_0EQB1ENVXiGMM/images/fine_tuning/image-generation/file-viewer.png?w=2500&fit=max&auto=format&n=T4_0EQB1ENVXiGMM&q=85&s=7b71ab43393083ae36670916e24b83ab) You can also automatically download the weights with the [oxen cli](https://docs.oxen.ai/getting-started/command-line/start_repository) or [python library](https://docs.oxen.ai/python-api) . CLI Python oxen download user-name/repo-name path/to/model.safetensors --revision COMMIT_OR_BRANCH [​](https://docs.oxen.ai/examples/fine-tuning/image_editing#need-help-fine-tuning) Need Help Fine-Tuning? ------------------------------------------------------------------------------------------------------------ If you need help fine-tuning your model, contact us at [hello@oxen.ai](mailto:hello@oxen.ai) and we are happy to help you get started. [πŸ–ΌοΈ Image Generation](https://docs.oxen.ai/examples/fine-tuning/image_generation) [πŸŽ₯ Video Generation](https://docs.oxen.ai/examples/fine-tuning/video_generation) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # 🏷️ File Metadata - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/concepts/file_metadata#content-area) [​](https://docs.oxen.ai/concepts/file_metadata#data-type-detection) Data Type Detection ------------------------------------------------------------------------------------------- By default, Oxen.ai will detect the data type of a file based on the file extension and content type. The default data types are: * `tabular` -> `csv`, `tsv`, `jsonl`, `parquet`, `arrow` * `text` -> `txt` * `image` -> `png`, `jpg`, `jpeg`, `gif`, `bmp`, `tiff`, `webp` * `video` -> `mp4`, `mov` * `audio` -> `mp3`, `wav`, `m4a`, `ogg`, `flac` [​](https://docs.oxen.ai/concepts/file_metadata#tabular-data) Tabular Data ----------------------------------------------------------------------------- When you add a tabular file to Oxen, it automatically detects and versions the schema of any tabular data. This is done by using [Polars](https://www.pola.rs/) under the hood to infer the column names and datatypes. To list all the schemas that have been detected and committed, you can use the `oxen schemas` subcommand. oxen schemas Output: +-----------------------+------+----------------------------------+------------------------+ | path | name | hash | fields | +==========================================================================================+ | annotations/train.csv | ? | 53732ea1c2a9ba5807bd59978ebb69f5 | [file, ..., is_fluffy] | |-----------------------+------+----------------------------------+------------------------| | annotations/test.csv | ? | 36d0edc8779f42e30b0d630aa83bc83c | [file, ..., height] | +-----------------------+------+----------------------------------+------------------------+ The schema detection is done on a per file basis. This means that if you have a directory of csv or parquet files, each file will have its own schema. [​](https://docs.oxen.ai/concepts/file_metadata#view-schema) View Schema --------------------------------------------------------------------------- To view a specific schema, you can pass in a schema hash, name, or path to the `oxen schemas` command. oxen schemas annotations/train.csv Output: +--------+-------+----------+ | name | dtype | metadata | +===========================+ | file | str | | |--------+-------+----------| | label | str | | |--------+-------+----------| | min_x | f64 | | |--------+-------+----------| | min_y | f64 | | |--------+-------+----------| | width | i64 | | |--------+-------+----------| | height | i64 | | +--------+-------+----------+ [​](https://docs.oxen.ai/concepts/file_metadata#add-schema) Add Schema ------------------------------------------------------------------------- Schemas are automatically detected when you add `csv`, `tsv`, `jsonl`, `parquet`, and `arrow` files to Oxen. Before a schema is committed, you can see the detected schemas in the `oxen status` command. oxen add annotations/train.csv oxen status Output: On branch main -> 503591398980c485 Directories to be committed added: annotations with 1 file Files to be committed: (use "oxen restore --staged ..." to unstage) modified: annotations/train.csv Schemas to be committed (use "oxen schemas show --staged " to view staged schema) detected schema: annotations/train.csv 23d86a4c1481b817b57ee8ccd7d9016b To view more detailed information about the detected schema, use the `--staged` flag on the `oxen schemas` command. oxen schemas --staged annotations/train.csv Output: annotations/train.csv 23d86a4c1481b817b57ee8ccd7d9016b +-----------+-------+----------+ | name | dtype | metadata | +==============================+ | file | str | | |-----------+-------+----------| | label | str | | |-----------+-------+----------| | min_x | f64 | | |-----------+-------+----------| | min_y | f64 | | |-----------+-------+----------| | width | f64 | | |-----------+-------+----------| | height | f64 | | |-----------+-------+----------| | is_fluffy | str | | |-----------+-------+----------| | breed | str | | +-----------+-------+----------+ To view how Polars interprets the schema before adding the file, you can use the `oxen df` command with the `--schema` flag. oxen df annotations/train.csv --schema Output: +-----------+-------+ | column | dtype | +===================+ | file | str | |-----------+-------| | label | str | |-----------+-------| | min_x | f64 | |-----------+-------| | min_y | f64 | |-----------+-------| | width | f64 | |-----------+-------| | height | f64 | |-----------+-------| | is_fluffy | str | |-----------+-------| | breed | str | +-----------+-------+ [​](https://docs.oxen.ai/concepts/file_metadata#additional-metadata) Additional Metadata ------------------------------------------------------------------------------------------- You can also add additional information to the schema. This is useful if you want to provide context about the data for a UI, data fetching, or any other reason. Notice the empty column `metadata` in the schema above. You can add arbitrary JSON blobs to the schema itself, as well as each column. Metadata may provide useful information for your end application: * Transforms you want to perform. * How you want to render the data. * Information about the data itself, such as a description of the schema or colun. [​](https://docs.oxen.ai/concepts/file_metadata#schema-metadata) Schema Metadata ----------------------------------------------------------------------------------- At the root of each schema is an `Optional` metadata value. This is useful for adding information about the schema itself. For example, you can add a description of the schema or a json blob that gives context to a data renderer. oxen schemas add annotations/train.csv -m '{"task": "bounding_box", "description": "Extracting bounding boxes from images"}' You will see the additional metadata listed above the schema if it is added. "annotations/train.csv" {"task": "bounding_box", "description": "Extracting bounding boxes from images"} +-----------+-------+----------+ | name | dtype | metadata | +==============================+ | file | str | | |-----------+-------+----------| | label | str | | |-----------+-------+----------| | min_x | f64 | | |-----------+-------+----------| | min_y | f64 | | |-----------+-------+----------| | width | f64 | | |-----------+-------+----------| | height | f64 | | |-----------+-------+----------| | is_fluffy | str | | |-----------+-------+----------| | breed | str | | +-----------+-------+----------+ [​](https://docs.oxen.ai/concepts/file_metadata#column-metadata) Column Metadata ----------------------------------------------------------------------------------- You can also add metadata to specific columns. Say you wanted to add information to the `file` column about the root directory of the images, you could do the following: oxen schemas add annotations/train.csv -c 'file' -m '{"root": "images/"}' Output: "annotations/train.csv" +-----------+-------+---------------------+ | name | dtype | metadata | +=========================================+ | file | str | {"root": "images/"} | |-----------+-------+---------------------| | label | str | | |-----------+-------+---------------------| | min_x | f64 | | |-----------+-------+---------------------| | min_y | f64 | | |-----------+-------+---------------------| | width | f64 | | |-----------+-------+---------------------| | height | f64 | | |-----------+-------+---------------------| | is_fluffy | str | | |-----------+-------+---------------------| | breed | str | | +-----------+-------+---------------------+ The `-c` flag stands for `column` and the `-m` flag stands for `metadata`. The metadata is a JSON blob that can be used to store any information you want. The [OxenHub UI](https://oxen.ai/) uses schema metadata to render more complex datatypes in the UI. For example viewing inline images directly in a dataframe. ![OxenHub UI](https://mintcdn.com/oxenai/GvHCMKbbr_BpHEwk/images/datasets/image_net_train.png?w=2500&fit=max&auto=format&n=GvHCMKbbr_BpHEwk&q=85&s=18f7340cc87dee54b9a4369cd7b79a28) [​](https://docs.oxen.ai/concepts/file_metadata#commit-the-schema) Commit The Schema --------------------------------------------------------------------------------------- Schemas changes will not be saved until you commit them. To view the schemas staged for commit, you can use the `--staged` flag. oxen schemas --staged Output: +-----------------------+------+----------------------------------+--------------------+ | path | name | hash | fields | +======================================================================================+ | annotations/train.csv | ? | 9d1fac486f95120403d7f18232fa5520 | [file, ..., breed] | +-----------------------+------+----------------------------------+--------------------+ You can then commit the schema to the dataframe with the `commit` subcommand. oxen commit -m "Overriding schema for annotations/train.csv" These changes are persistent across commits and will be carried forward. [​](https://docs.oxen.ai/concepts/file_metadata#name-schema) Name Schema --------------------------------------------------------------------------- It is nice to have human readable names to refer to schemas by. Use the `oxen schemas name` command to name a schema. oxen schemas name annotations/train.csv bounding_box [​](https://docs.oxen.ai/concepts/file_metadata#remove-schema) Remove Schema ------------------------------------------------------------------------------- If you have accidentally staged a schema, you can remove it with the `oxen schemas rm` command. oxen schemas rm annotations/train.csv --staged [​](https://docs.oxen.ai/concepts/file_metadata#render-images) Render Images ------------------------------------------------------------------------------- Oxen.ai can render images through the webhub if you add the proper schema metadata. oxen schemas add data.csv -c 'file' --render image Under the hood this applied a metadata blob to the column, telling Oxen to render an image. More verbosely it would look like: oxen schemas add data.csv -c 'file' -m '{ "_oxen": { "render": { "func": "image" } } }' [​](https://docs.oxen.ai/concepts/file_metadata#render-links) Render Links ----------------------------------------------------------------------------- Oxen.ai can render links to other files through the webhub if you add the proper schema metadata. oxen schemas add data.csv -c 'file' --render link Under the hood this applied a metadata blob to the column, telling Oxen to render an link. More verbosely it would look like: oxen schemas add data.csv -c 'file' -m '{ "_oxen": { "render": { "func": "link" } } }' [βš–οΈ Dataset Diffs](https://docs.oxen.ai/concepts/diffs) [πŸ“– Overview](https://docs.oxen.ai/getting-started/fine-tuning) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # πŸ–ΌοΈ Image Generation - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/examples/fine-tuning/image_generation#content-area) Oxen.ai allows you to fine-tune an image generation model to create higher quality images with consistent brand assets, characters, products, or your own style with no infrastructure setup required. Fine-tune your models with a few clicks, track results during training, and own all your weights to download and use anywhere. [​](https://docs.oxen.ai/examples/fine-tuning/image_generation#the-task) The Task ------------------------------------------------------------------------------------ For this example, we are going to fine-tune [Qwen-Image](https://www.oxen.ai/ai/models/qwen-image) to be able to generate images of models wearing a specific outfit. ![Reference Image](https://mintcdn.com/oxenai/T4_0EQB1ENVXiGMM/images/fine_tuning/image-generation/nike-models.jpg?w=2500&fit=max&auto=format&n=T4_0EQB1ENVXiGMM&q=85&s=5c116d3c483ab9c18bc05ef889ee2ed6) [​](https://docs.oxen.ai/examples/fine-tuning/image_generation#dataset-format) Dataset Format ------------------------------------------------------------------------------------------------ When fine-tuning image generation models, you need a dataset that contains the images and descriptions of the images. The expected format is a csv, jsonl, or parquet file with a column that contains the _relative path_ to the image in the repository, and a column that contains the description of the image. ![Dataset Format](https://mintcdn.com/oxenai/T4_0EQB1ENVXiGMM/images/fine_tuning/image-generation/dataset-format.png?w=2500&fit=max&auto=format&n=T4_0EQB1ENVXiGMM&q=85&s=0196122dfa4ece5a07c3242048ef0576) We’ll walk through the process of creating a dataset with the images and captions in the following sections. [​](https://docs.oxen.ai/examples/fine-tuning/image_generation#creating-a-repository) Creating a Repository -------------------------------------------------------------------------------------------------------------- Oxen.ai repositories are used to store and version your data and models. We can create a new repository by clicking the β€œCreate New Repository” button in your Oxen.ai dashboard. ![Create Repository](https://mintcdn.com/oxenai/GvHCMKbbr_BpHEwk/images/fine_tuning/fine-tune-create-repo.png?w=2500&fit=max&auto=format&n=GvHCMKbbr_BpHEwk&q=85&s=7d2834a6b15ab25b7b7aee252597d40b) You will upload your dataset to the repository, and when the fine-tune is complete, the model weights will be saved to a branch in the repository. By versioning your data and models together, you can always track the data that was used to train the model. [​](https://docs.oxen.ai/examples/fine-tuning/image_generation#uploading-the-images) Uploading the Images ------------------------------------------------------------------------------------------------------------ From your repository, you can click the β€œAdd File” button to upload your dataset of images. If you upload a zip file, it will automatically be unpacked into the repository in the specified directory. Note: When uploading your images, organize your files in a folder by specifying a β€œTarget Directory” when uploading the files. ![Upload Dataset](https://mintcdn.com/oxenai/S-Fh7jS1NMc3HM8D/images/fine_tuning/fine-tune-images-zip.png?w=2500&fit=max&auto=format&n=S-Fh7jS1NMc3HM8D&q=85&s=7628fc45dbdf3d8d3bc35a078247d445) [​](https://docs.oxen.ai/examples/fine-tuning/image_generation#turn-your-images-into-a-dataset) Turn Your Images into a Dataset ---------------------------------------------------------------------------------------------------------------------------------- In order to fine-tune in Oxen.ai, you need a csv, jsonl, or parquet file that contains the images and their captions. With your images uploaded, you can convert the directory of images into a dataset that can be used for the fine-tune. Navigate to the directory of images and click the β€œFolder to Dataset” button. ![Folder to Dataset](https://mintcdn.com/oxenai/GvHCMKbbr_BpHEwk/images/fine_tuning/fine-tune-folder-to-dataset-button.png?w=2500&fit=max&auto=format&n=GvHCMKbbr_BpHEwk&q=85&s=cccff2a41401b35a6554958138d7ae20) This will grab all of the relative paths from the folder and create a parquet file with a column called `file_path` that contains the relative path to the image. ![Folder to Dataset](https://mintcdn.com/oxenai/GvHCMKbbr_BpHEwk/images/fine_tuning/fine-tune-folder-to-dataset-conversion.png?w=2500&fit=max&auto=format&n=GvHCMKbbr_BpHEwk&q=85&s=2d2df4af021b1826f7ff396371e89348) In order to view the images, you will need to enable image rendering on the `file_path` column. Click the β€œβœοΈβ€ edit button above the dataset, then edit the column to enable image rendering. The video below shows the whole process. Your browser does not support the video tag. [​](https://docs.oxen.ai/examples/fine-tuning/image_generation#captioning-the-images) Captioning The Images -------------------------------------------------------------------------------------------------------------- In order for the fine-tune to learn a mapping from text to images, we’ll need a prompt column that contains a description of each image. Oxen.ai makes it easy to run models on each row of the dataset in order to automatically generate captions. Click the β€œActions” button above the dataset, then select β€œRun Inference”. ![Run Inference](https://mintcdn.com/oxenai/GvHCMKbbr_BpHEwk/images/data-frames/run-inference.png?w=2500&fit=max&auto=format&n=GvHCMKbbr_BpHEwk&q=85&s=f5ab338d8b7e18a0490a6deb360d00f3) You will need to select a model that is able to go from β€œimage” to β€œtext” from the dropdown on the left. ![Run Inference](https://mintcdn.com/oxenai/GvHCMKbbr_BpHEwk/images/evaluations/image-to-text-captions.png?w=2500&fit=max&auto=format&n=GvHCMKbbr_BpHEwk&q=85&s=ee3b54dfbc1089cf3a80e9d7a6bab741) Now write a prompt that describes what you want in the caption and any formatting you want to apply. Describe the model and the clothing that the model is wearing as if you are writing a prompt for an image generation model. The prompt should be one sentence in length and include the gender as "male" or "female". Also describe their hair color and skin tone (white, tan, black, latina, asian). Only describe the person and outfit. The prompt should start with something like "A male Nike model wearing" or "A female Nike model wearing" {file_path} Note: You must supply the curly braces `{}` around the `file_path` column in the prompt to know what column to use for the image. When you feel good about your prompt after looking at your samples click the β€œNext ->” button to decide where you want to save the results. By default, the results will create a new version of the existing file. ![Run Inference](https://mintcdn.com/oxenai/GvHCMKbbr_BpHEwk/images/evaluations/image-to-text-committing.png?w=2500&fit=max&auto=format&n=GvHCMKbbr_BpHEwk&q=85&s=c6aeda8541c177d70e3dc8e083d536d5) Now sit back and relax as the model captions your images 😌 β˜•οΈ. ![Run Inference](https://mintcdn.com/oxenai/GvHCMKbbr_BpHEwk/images/evaluations/image-to-text-progress.png?w=2500&fit=max&auto=format&n=GvHCMKbbr_BpHEwk&q=85&s=6dd4a88d00314f30be6c92b362857ed8) [​](https://docs.oxen.ai/examples/fine-tuning/image_generation#kicking-off-the-fine-tune) Kicking off the Fine-Tune ---------------------------------------------------------------------------------------------------------------------- With our images captioned, now we can kick off the fine-tune! Click the β€œActions” button and select β€œFine-Tune a Model”. ![Kick off Fine-Tune](https://mintcdn.com/oxenai/T4_0EQB1ENVXiGMM/images/fine_tuning/image-generation/fine-tune-a-model-button.png?w=2500&fit=max&auto=format&n=T4_0EQB1ENVXiGMM&q=85&s=722b227a3104c6c35c82126c65ee94af) This will take you to the fine-tune page where you can select the model you want to fine-tune. Select the β€œQwen-Image” model, and make sure the β€œImage” column is set to the `file_path` column, and the β€œPrompt” column is set to the `caption` column. ![Write Prompts](https://mintcdn.com/oxenai/T4_0EQB1ENVXiGMM/images/fine_tuning/image-generation/fine-tune-write-prompts.png?w=2500&fit=max&auto=format&n=T4_0EQB1ENVXiGMM&q=85&s=e024aeba2fb2af3f948ba4995c1765ca) To monitor the fine-tune, you can provide a few sample prompts that will be used to generate images during the fine-tune. [​](https://docs.oxen.ai/examples/fine-tuning/image_generation#advanced-parameters) Advanced Parameters ---------------------------------------------------------------------------------------------------------- Click the β€œAdvanced Parameters” button to see the advanced parameters for the fine-tune. You can set the learning rate, batch size, number of steps, and other parameters here. One of the best parts of fine-tuning with Oxen.ai is that we track all your experiments for you, so that you can always refer back to the parameters that worked best for future fine-tunes. ![Fine-Tune Parameters](https://mintcdn.com/oxenai/T4_0EQB1ENVXiGMM/images/fine_tuning/image-generation/advanced-params.png?w=2500&fit=max&auto=format&n=T4_0EQB1ENVXiGMM&q=85&s=59665c4f06d3aa02501e55d3bb7ba99d) Click the β€œStart Fine-Tune” button and you are off to the races! [​](https://docs.oxen.ai/examples/fine-tuning/image_generation#monitoring-the-fine-tune) Monitoring the Fine-Tune -------------------------------------------------------------------------------------------------------------------- As the model is training, you can monitor the progress by clicking the β€œSamples” tab. This will show you the images that the model has generated so far. ![Monitor the Fine-Tune](https://mintcdn.com/oxenai/T4_0EQB1ENVXiGMM/images/fine_tuning/image-generation/monitor_the_fine_tune.png?w=2500&fit=max&auto=format&n=T4_0EQB1ENVXiGMM&q=85&s=e812b7e600103971802c5d56bc58aaa7) [​](https://docs.oxen.ai/examples/fine-tuning/image_generation#deploying-the-model) Deploying the Model ---------------------------------------------------------------------------------------------------------- When the model has finished training, you can deploy it to a new model by clicking the β€œDeploy Model” button. The deployment will take a few minutes to complete. ![Deploy the Model](https://mintcdn.com/oxenai/T4_0EQB1ENVXiGMM/images/fine_tuning/image-generation/model-deploying.png?w=2500&fit=max&auto=format&n=T4_0EQB1ENVXiGMM&q=85&s=b7e5f2fdc6a077a6c1acb7c4bd009922) Once the model is deployed, you can use it in the playground or via the API. curl -X POST \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "model": "oxen:ox-brave-jade-gecko", "prompt": "A majestic ox standing in a field at sunset", "num_inference_steps": 28 }' https://hub.oxen.ai/api/ai/images/generate [​](https://docs.oxen.ai/examples/fine-tuning/image_generation#using-the-playground) Using the Playground ------------------------------------------------------------------------------------------------------------ Click the β€œOpen Playground” button to use the model in the playground. This allows you to prompt the model with different images and prompts to see how it performs. ![Playground](https://mintcdn.com/oxenai/T4_0EQB1ENVXiGMM/images/fine_tuning/image-generation/playground.png?w=2500&fit=max&auto=format&n=T4_0EQB1ENVXiGMM&q=85&s=93267ea64ff8ed34e9a0ed4a54aa6e3f) The playground will save a history of your prompts and images so that you can refer back to them later. [​](https://docs.oxen.ai/examples/fine-tuning/image_generation#exporting-the-model) Exporting the Model ---------------------------------------------------------------------------------------------------------- All of the model weights are stored back in your repository when the fine-tune is complete. Navigate to the fine-tune info tab, and you will see a link to the model weights. This is helpful if you want to download the weights to run in ComfyUI or your own infrastructure. ![Info Tab](https://mintcdn.com/oxenai/T4_0EQB1ENVXiGMM/images/fine_tuning/image-generation/info-tab.png?w=2500&fit=max&auto=format&n=T4_0EQB1ENVXiGMM&q=85&s=dca3def3e9f2503447ca5ccb7c2d99bd) This will take you to the file viewer where you can download the model `.safetensors` file. ![File Viewer](https://mintcdn.com/oxenai/T4_0EQB1ENVXiGMM/images/fine_tuning/image-generation/file-viewer.png?w=2500&fit=max&auto=format&n=T4_0EQB1ENVXiGMM&q=85&s=7b71ab43393083ae36670916e24b83ab) You can also automatically download the weights with the [oxen cli](https://docs.oxen.ai/getting-started/command-line/start_repository) or [python library](https://docs.oxen.ai/python-api) . CLI Python oxen download user-name/repo-name path/to/model.safetensors --revision COMMIT_OR_BRANCH [​](https://docs.oxen.ai/examples/fine-tuning/image_generation#need-help-fine-tuning) Need Help Fine-Tuning? --------------------------------------------------------------------------------------------------------------- If you need help fine-tuning your model, contact us at [hello@oxen.ai](mailto:hello@oxen.ai) and we are happy to help you get started. [πŸ‘οΈ Vision Language Models](https://docs.oxen.ai/examples/fine-tuning/image_understanding) [πŸ‘¨β€πŸŽ¨ Image Editing](https://docs.oxen.ai/examples/fine-tuning/image_editing) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # πŸ“¦ Workspaces - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/examples/data/workspaces#content-area) A workspace is like a working directory that lives on the Oxen server. You can `add`, `rm`, and modify files in a workspace and then commit those changes in bulk, without ever cloning the repository to your local machine. Under the hood, every workspace is pinned to a specific commit on a branch. All staged changes are computed relative to that commit. Staged changes survive server restarts, but they are **not** part of the repository’s commit history until you commit the workspace, so they can be deleted without leaving a trace. [​](https://docs.oxen.ai/examples/data/workspaces#why-use-a-workspace) Why use a workspace? ---------------------------------------------------------------------------------------------- Reach for a workspace when you want to: * **Edit a repository that’s too large to clone.** Stage changes to a 100GB+ repo without copying it to your machine. * **Bulk-import data without keeping a local copy.** `oxen workspace add` uploads directly to the server, so you don’t pay the disk cost of writing every file into a local `.oxen` store first. * **Batch many changes into a single commit.** Add, remove, and modify dozens of files server-side, then land them as one atomic commit. * **Let multiple clients contribute to one staged commit.** A named workspace can be written to by several processes or users before anyone commits β€” useful for workflows like labeling UIs, ingestion services, or agents producing training data. * **Keep a long-lived staging area across multiple commits.** Named workspaces persist after commit and fast-forward to the new commit, so the same workspace can be reused over and over. If you’re working in a repo small enough to clone and just want the normal `add β†’ commit β†’ push` flow, you don’t need a workspace β€” see the [Version Control guide](https://docs.oxen.ai/examples/data/versioning) instead. [​](https://docs.oxen.ai/examples/data/workspaces#quick-start) Quick start ----------------------------------------------------------------------------- ### [​](https://docs.oxen.ai/examples/data/workspaces#add-to-an-existing-repo-without-cloning-it) Add to an existing repo without cloning it Imagine a repository with 1 million images. Instead of cloning the data, init an empty local repo, point it at the remote, and write directly to a workspace. CLI Python oxen init oxen config --set-remote origin https://hub.oxen.ai/ox/ImageNet-1k oxen workspace create --name add_image --branch main # Stage a single file into the images/ directory of the workspace oxen workspace add /path/to/my_images/image.jpg --directory images/ --workspace-name add_image # See what's staged oxen workspace status --workspace-name add_image # Commit the staged changes to main oxen workspace commit -m "Add new image to images/ directory" -n add_image -b main ### [​](https://docs.oxen.ai/examples/data/workspaces#bulk-import-data-into-a-fresh-repo) Bulk-import data into a fresh repo `oxen workspace add` never writes data to your local machine β€” files stream directly to the remote. This avoids the disk and time cost of `add β†’ commit β†’ push`, which would otherwise copy every file into a local `.oxen` store first. CLI Python oxen init oxen config --create-remote --host hub.oxen.ai --scheme https --name ox/ImageNet-1k oxen workspace create # Create a workspace to import the data. This will return a workspace ID oxen workspace add images/ --workspace-id [WORKSPACE_ID] oxen workspace commit -m "Import 1 million images" -w [WORKSPACE_ID] Workspaces can also be driven through the [HTTP API](https://docs.oxen.ai/http-api/workspaces/get-or-create-workspace) β€” useful when you’re building a custom client (labeling UI, ingestion daemon, agent, etc.) that needs to write to a repo without shipping the Oxen CLI or Python SDK. [​](https://docs.oxen.ai/examples/data/workspaces#how-it-works) How it works ------------------------------------------------------------------------------- Every workspace references a specific commit, the same way a branch does. All your staged operations are recorded as a diff against that base commit. When you commit a workspace: 1. Oxen applies your staged diff on top of the workspace’s base commit to produce a new commit. 2. That new commit is added to a target branch on the remote (see [Committing changes](https://docs.oxen.ai/examples/data/workspaces#committing-changes) for how the target is chosen). 3. If the target branch has advanced past the workspace’s base commit, Oxen attempts to merge. Conflicts cause the commit to fail and you’ll need to resolve them before retrying. Because workspaces are commit-scoped, two workspaces created from the same branch at different times can see completely different views of the repo. That’s intentional β€” it gives you isolation while staging β€” but it also means a long-lived workspace can drift from the branch tip and accumulate conflicts. [​](https://docs.oxen.ai/examples/data/workspaces#creating-a-workspace) Creating a workspace ----------------------------------------------------------------------------------------------- A workspace is created against a remote repository, and optionally against a specific branch. Python CLI from oxen import RemoteRepo from oxen import Workspace repo = RemoteRepo("ox/CatDogBBox") workspace = Workspace(repo, "add-images") If no branch is provided, the default branch (usually `main`) is used. Python CLI from oxen import RemoteRepo from oxen import Workspace repo = RemoteRepo("ox/CatDogBBox") workspace = Workspace(repo) The workspace is pinned to whatever commit the branch points at when you create it. You can only create workspaces from branches that already exist on the remote. ### [​](https://docs.oxen.ai/examples/data/workspaces#named-vs-unnamed-workspaces) Named vs. unnamed workspaces Every workspace has an auto-generated **id**. You can optionally also give it a human-readable **name**. Python CLI from oxen import RemoteRepo from oxen import Workspace repo = RemoteRepo("ox/CatDogBBox") workspace = Workspace(repo, name="my-workspace-name") The name matters because of two behavioral differences: | | Unnamed workspace | Named workspace | | --- | --- | --- | | Lifetime after commit | Deleted | Persists, fast-forwarded to the new commit | | Best for | One-shot imports, throwaway staging | Long-lived staging, multi-commit or multi-client workflows | Use a **named** workspace when you expect to make multiple commits from the same workspace, or when several processes/users will share it. Use an **unnamed** workspace for one-off imports where you don’t need it to stick around. ### [​](https://docs.oxen.ai/examples/data/workspaces#identifying-a-workspace-in-cli-commands) Identifying a workspace in CLI commands Most workspace commands need to know _which_ workspace you’re targeting. You can reference a workspace by either its id or its name: * `--workspace-id ` (short: `-w`) β€” reference by the auto-generated id returned from `oxen workspace create`. * `--workspace-name ` (short: `-n`) β€” reference by the name you set with `--name` at create time. [​](https://docs.oxen.ai/examples/data/workspaces#listing-workspaces) Listing workspaces ------------------------------------------------------------------------------------------- List the workspaces on a remote with `oxen workspace list`. oxen workspace list -r my_remote # Defaults to `origin` if no remote is provided [​](https://docs.oxen.ai/examples/data/workspaces#adding-files) Adding files ------------------------------------------------------------------------------- `oxen workspace add` streams a file’s contents directly to the server and stages it on the workspace. Python CLI from oxen import RemoteRepo from oxen import Workspace repo = RemoteRepo("ox/CatDogBBox") workspace = Workspace(repo, "add-images") workspace.add("/path/to/image.png") status = workspace.status() print(status.added_files()) ### [​](https://docs.oxen.ai/examples/data/workspaces#unstaging-a-file) Unstaging a file To remove a file you’ve staged on the workspace (without touching the base repo), unstage it with `oxen workspace rm --staged`. CLI oxen workspace rm --staged image.jpg -w my-workspace-id ### [​](https://docs.oxen.ai/examples/data/workspaces#deleting-a-file-from-the-base-repo) Deleting a file from the base repo `oxen workspace rm` **without** `--staged` stages a deletion of a file that exists in the base repo. When you commit the workspace, that file will be removed from the branch. Use `--staged` if you only want to unstage a previously added file. CLI Python oxen workspace rm image.jpg -w my-workspace-id [​](https://docs.oxen.ai/examples/data/workspaces#committing-changes) Committing changes ------------------------------------------------------------------------------------------- Commit a workspace to land its staged changes as a new commit on the remote. Python CLI from oxen import RemoteRepo from oxen import Workspace repo = RemoteRepo("ox/CatDogBBox") workspace = Workspace(repo, "add_images") workspace.commit("adding an image using a workspace", "add_images") If you don’t provide a target branch, the commit will be made to a new branch on the remote. Python CLI from oxen import RemoteRepo from oxen import Workspace repo = RemoteRepo("ox/CatDogBBox") workspace = Workspace(repo, "my_branch") workspace.commit("adding an image using a workspace") # No branch is provided, so this will create a new branch After a successful commit: * An **unnamed** workspace is deleted. * A **named** workspace is fast-forwarded to point at the new commit, so you can keep using it. If merge conflicts are detected (because the target branch has advanced past the workspace’s base commit), the commit will fail. [πŸ“Š Datasets](https://docs.oxen.ai/examples/data/datasets) [πŸ”₯ Performance](https://docs.oxen.ai/examples/data/performance) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # πŸ‘οΈ Vision Language Models - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/examples/inference/vision_language_models#content-area) [​](https://docs.oxen.ai/examples/inference/vision_language_models#what-are-vlms) What are VLMs? --------------------------------------------------------------------------------------------------- Vision language models extend the ability of language models to understand image and video data. As input they can accept images and videos as well as a text prompt, and as output they can generate text. For example, instead of training a classifier from scratch, you can pass in your list of categories and a description what to look for in the prompt, and let the VLM take care of the rest. Here is the [list of supported models](https://www.oxen.ai/ai/models?modalities=image-to-text,video-to-text) . [​](https://docs.oxen.ai/examples/inference/vision_language_models#image-understanding) Image Understanding -------------------------------------------------------------------------------------------------------------- The `/ai/chat/completions` endpoint supports vision language models for image understanding. If you want to send an image to a model that supports vision such as Qwen3-VL, Qwen3.5, or Gemini 3 Pro/Flash, you can add a message with the `image_url` type. ### [​](https://docs.oxen.ai/examples/inference/vision_language_models#using-image-urls) Using Image URLs cURL (image url) curl -X POST https://hub.oxen.ai/api/ai/chat/completions \ -H "Authorization: Bearer $OXEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gemini-3-1-pro-preview", "messages": [\ {\ "role": "user",\ "content": [\ {\ "type": "text",\ "text": "What is in this image?"\ },\ {\ "type": "image_url",\ "image_url": {\ "url": "https://oxen.ai/assets/images/homepage/hero-ox.png"\ }\ }\ ]\ }\ ] }' ### [​](https://docs.oxen.ai/examples/inference/vision_language_models#using-base64-encoded-images) Using Base64 Encoded Images You can also directly pass in the base64 encoded image. cURL (base64 encoded image) curl -X POST https://hub.oxen.ai/api/ai/chat/completions \ -H "Authorization: Bearer $OXEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet-4-6", "messages": [\ {\ "role": "user",\ "content": [\ {\ "type": "text",\ "text": "What is in this image?"\ },\ {\ "type": "image_url",\ "image_url": {\ "url": "data:image/jpeg;base64,YOUR_BASE64_ENCODED_IMAGE_HERE"\ }\ }\ ]\ }\ ] }' ### [​](https://docs.oxen.ai/examples/inference/vision_language_models#python-example) Python Example From python this would look like: Python import openai import os import base64 # Read and encode the image to base64 def encode_image(image_path): with open(image_path, "rb") as image_file: return base64.b64encode(image_file.read()).decode('utf-8') # Initialize the client client = openai.OpenAI( api_key=os.getenv("OXEN_API_KEY"), base_url="https://hub.oxen.ai/api/ai" ) # Encode your image base64_image = encode_image("path/to/your/image.jpg") # Send the request with base64 encoded image response = client.chat.completions.create( model="claude-sonnet-4-6", messages=[\ {\ "role": "user",\ "content": [\ {\ "type": "text",\ "text": "What is in this image?"\ },\ {\ "type": "image_url",\ "image_url": {\ "url": f"data:image/jpeg;base64,{base64_image}"\ }\ }\ ]\ }\ ] ) print(response.choices[0].message.content) [​](https://docs.oxen.ai/examples/inference/vision_language_models#video-understanding) Video Understanding -------------------------------------------------------------------------------------------------------------- The `/ai/chat/completions` endpoint also supports video understanding through vision language models. To send a video to a model that supports video understanding, you can add a message with the `video_url` type. ### [​](https://docs.oxen.ai/examples/inference/vision_language_models#using-video-urls) Using Video URLs cURL (video url) curl -X POST https://hub.oxen.ai/api/ai/chat/completions \ -H "Authorization: Bearer $OXEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gemini-3-flash-preview", "messages": [\ {\ "role": "user",\ "content": [\ {\ "type": "text",\ "text": "What is happening in this video?"\ },\ {\ "type": "video_url",\ "video_url": {\ "url": "https://example.com/path/to/video.mp4"\ }\ }\ ]\ }\ ] }' ### [​](https://docs.oxen.ai/examples/inference/vision_language_models#using-base64-encoded-videos) Using Base64 Encoded Videos You can also directly pass in the base64 encoded video. cURL (base64 encoded video) curl -X POST https://hub.oxen.ai/api/ai/chat/completions \ -H "Authorization: Bearer $OXEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gemini-3-flash-preview", "messages": [\ {\ "role": "user",\ "content": [\ {\ "type": "text",\ "text": "Describe the main events in this video."\ },\ {\ "type": "video_url",\ "video_url": {\ "url": "data:video/mp4;base64,YOUR_BASE64_ENCODED_VIDEO_HERE"\ }\ }\ ]\ }\ ] }' ### [​](https://docs.oxen.ai/examples/inference/vision_language_models#python-example-2) Python Example From python this would look like: Python import openai import os import base64 # Read and encode the video to base64 def encode_video(video_path): with open(video_path, "rb") as video_file: return base64.b64encode(video_file.read()).decode('utf-8') # Initialize the client client = openai.OpenAI( api_key=os.getenv("OXEN_API_KEY"), base_url="https://hub.oxen.ai/api/ai" ) # Encode your video base64_video = encode_video("path/to/your/video.mp4") # Send the request with base64 encoded video response = client.chat.completions.create( model="gemini-3-flash-preview", messages=[\ {\ "role": "user",\ "content": [\ {\ "type": "text",\ "text": "What is happening in this video?"\ },\ {\ "type": "video_url",\ "video_url": {\ "url": f"data:video/mp4;base64,{base64_video}"\ }\ }\ ]\ }\ ] ) print(response.choices[0].message.content) [​](https://docs.oxen.ai/examples/inference/vision_language_models#playground-interface) Playground Interface ---------------------------------------------------------------------------------------------------------------- Want to test out prompts without writing any code? You can use the [playground interface](https://www.oxen.ai/ai/models/claude-sonnet-4-6) to chat with a model. This is a great way to kick the tires of a base model or a model you [fine-tuned](https://docs.oxen.ai/getting-started/fine-tuning) after deploying it. ![Chat Interface](https://mintcdn.com/oxenai/SmBr7Qh__934K7rJ/images/inference/image-to-text/playground.png?w=2500&fit=max&auto=format&n=SmBr7Qh__934K7rJ&q=85&s=982d2995cacbb55189fcf03d05ab5bef) [​](https://docs.oxen.ai/examples/inference/vision_language_models#fine-tuning-vlms) Fine-Tuning VLMs -------------------------------------------------------------------------------------------------------- Oxen.ai also allows you to fine-tune vision language models on your own data. This is a great way to get a model that is tailored to your specific use case. ![Fine-Tuning](https://mintcdn.com/oxenai/GvHCMKbbr_BpHEwk/images/fine_tuning/fine-tune-home.png?w=2500&fit=max&auto=format&n=GvHCMKbbr_BpHEwk&q=85&s=6a3b0d30730148cc365e9d73ccb673dc) Once the model has been fine-tuned, you can easily deploy the model behind an inference endpoint and start the evaluation loop over again. Learn more about [fine-tuning VLMs](https://docs.oxen.ai/examples/fine-tuning/image_understanding) . [πŸ’¬ Language Models](https://docs.oxen.ai/examples/inference/chat_completions) [πŸ–ΌοΈ Image Generation](https://docs.oxen.ai/examples/inference/image_generation) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # πŸ’¬ Language Models - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/examples/inference/chat_completions#content-area) [​](https://docs.oxen.ai/examples/inference/chat_completions#quick-start) Quick Start ---------------------------------------------------------------------------------------- The Oxen.ai chat completions API is fully [OpenAI-compatible](https://platform.openai.com/docs/api-reference/chat) . You can use the OpenAI SDK, `curl`, or any HTTP client that speaks the OpenAI chat format. **Base URL:** `https://hub.oxen.ai/api/ai` **Endpoint:** `POST /ai/chat/completions` Browse [all available models](https://www.oxen.ai/ai/models) . cURL Python (OpenAI SDK) curl -X POST https://hub.oxen.ai/api/ai/chat/completions \ -H "Authorization: Bearer $OXEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet-4-6", "messages": [\ {"role": "user", "content": "What is a great name for an ox?"}\ ] }' [​](https://docs.oxen.ai/examples/inference/chat_completions#authentication) Authentication ---------------------------------------------------------------------------------------------- Every request requires a Bearer token in the `Authorization` header. You can find your API key in your [account settings](https://www.oxen.ai/settings/profile) . Authorization: Bearer $OXEN_API_KEY ![API key](https://mintcdn.com/oxenai/iXdgSU_j00SuyDvU/images/auth_key.png?w=2500&fit=max&auto=format&n=iXdgSU_j00SuyDvU&q=85&s=fa0b3fb3dec23a1dd60f7505f9b49f5c) [​](https://docs.oxen.ai/examples/inference/chat_completions#response-format) Response Format ------------------------------------------------------------------------------------------------ The API returns an OpenAI-compatible JSON response: { "id": "chatcmpl-af41f027-e4d5-4c4b-ac40-625fb4ebfb1e", "object": "chat.completion", "created": 1774040155, "model": "claude-sonnet-4-6", "choices": [\ {\ "index": 0,\ "message": {\ "role": "assistant",\ "content": "How about \"Beauregard\"?"\ },\ "finish_reason": "stop"\ }\ ], "usage": { "prompt_tokens": 11, "completion_tokens": 4, "total_tokens": 15 } } | Field | Description | | --- | --- | | `id` | Unique identifier for the completion | | `object` | Always `"chat.completion"` | | `created` | Unix timestamp of when the completion was created | | `model` | The model that generated the response | | `choices` | Array of completion choices (typically one) | | `choices[].message.content` | The generated text | | `choices[].finish_reason` | Why generation stopped: `"stop"` (natural end) or `"length"` (hit `max_tokens`) | | `usage` | Token counts for the request | [​](https://docs.oxen.ai/examples/inference/chat_completions#parameters) Parameters -------------------------------------------------------------------------------------- | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `model` | string | _required_ | Model name, e.g. `"claude-sonnet-4-6"`, `"gpt-5-4-2026-03-05"`, `"gemini-3-1-flash-lite-preview"` | | `messages` | array | _required_ | Array of message objects with `role` and `content` | | `max_tokens` | integer | model default | Maximum number of tokens to generate | | `temperature` | float | model default | Sampling temperature (0-2). Lower is more deterministic. | | `stream` | boolean | `false` | Enable [streaming](https://docs.oxen.ai/examples/inference/chat_completions#streaming)
with server-sent events | ### [​](https://docs.oxen.ai/examples/inference/chat_completions#messages) Messages Each message in the `messages` array has a `role` and `content`: | Role | Description | | --- | --- | | `system` | Sets the behavior and context for the model | | `user` | The user’s input | | `assistant` | Previous model responses (for multi-turn conversations) | { "messages": [\ {"role": "system", "content": "You are a helpful assistant."},\ {"role": "user", "content": "What is the capital of France?"},\ {"role": "assistant", "content": "The capital of France is Paris."},\ {"role": "user", "content": "What is its population?"}\ ] } [​](https://docs.oxen.ai/examples/inference/chat_completions#streaming) Streaming ------------------------------------------------------------------------------------ Set `"stream": true` to receive responses as server-sent events (SSE). Each event is a `chat.completion.chunk` object with a `delta` instead of a `message`. cURL Python (OpenAI SDK) curl -X POST https://hub.oxen.ai/api/ai/chat/completions \ -H "Authorization: Bearer $OXEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gemini-3-1-flash-lite-preview", "messages": [\ {"role": "user", "content": "Write a haiku about data."}\ ], "stream": true }' Each SSE line is prefixed with `data:` and contains a JSON chunk: data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1774040190,"model":"gemini-3-1-flash-lite-preview","choices":[{"index":0,"delta":{"content":"hello"},"finish_reason":null}]} The stream ends with: data: [DONE] [​](https://docs.oxen.ai/examples/inference/chat_completions#vision) Vision ------------------------------------------------------------------------------ Models that support vision (such as `gemini-3-1-pro-preview` or `claude-sonnet-4-6`) accept images in the `messages` array. For full details and examples including base64 encoding and video understanding, see [Vision Language Models](https://docs.oxen.ai/examples/inference/vision_language_models) . cURL Python (OpenAI SDK) curl -X POST https://hub.oxen.ai/api/ai/chat/completions \ -H "Authorization: Bearer $OXEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gemini-3-1-pro-preview", "messages": [\ {\ "role": "user",\ "content": [\ {"type": "text", "text": "What is in this image?"},\ {"type": "image_url", "image_url": {"url": "https://oxen.ai/assets/images/homepage/hero-ox.png"}}\ ]\ }\ ] }' [​](https://docs.oxen.ai/examples/inference/chat_completions#tool-use) Tool use ---------------------------------------------------------------------------------- Tool calling (function calling) follows the same [OpenAI Chat Completions tool format](https://platform.openai.com/docs/guides/function-calling) . You send a `tools` array describing each function’s JSON Schema; the model may reply with `tool_calls` instead of plain text. You execute those functions in your app, then send the results back in new `tool` messages so the model can finish the answer. | Concept | Description | | --- | --- | | `tools` | Array of `{ "type": "function", "function": { "name", "description", "parameters" } }` objects. `parameters` is a JSON Schema object for the arguments. | | `tool_choice` | Optional. `"auto"` (default) lets the model decide; `"none"` disables tools; or force a specific function with `{"type": "function", "function": {"name": "..."}}`. | | Assistant `tool_calls` | When `finish_reason` is `"tool_calls"`, `choices[0].message.tool_calls` lists each call with `id`, `function.name`, and `function.arguments` (a JSON string). | | `tool` messages | Each result uses `role: "tool"`, `tool_call_id` matching the call’s `id`, and `content` as a string (often JSON your tool returned). | ### [​](https://docs.oxen.ai/examples/inference/chat_completions#raw-curl-first-request-tools-only) Raw `curl`: first request (tools only) The model may respond with `tool_calls` instead of user-facing `content`: curl -X POST https://hub.oxen.ai/api/ai/chat/completions \ -H "Authorization: Bearer $OXEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-5-4-2026-03-05", "messages": [\ {"role": "user", "content": "What is the weather in Paris?"}\ ], "tools": [\ {\ "type": "function",\ "function": {\ "name": "get_weather",\ "description": "Get current weather for a city",\ "parameters": {\ "type": "object",\ "properties": {\ "city": {"type": "string", "description": "City name"}\ },\ "required": ["city"]\ }\ }\ }\ ] }' Example assistant payload (abbreviated): { "choices": [\ {\ "finish_reason": "tool_calls",\ "index": 0,\ "message": {\ "content": null,\ "role": "assistant",\ "tool_calls": [\ {\ "function": {\ "arguments": "{\"city\":\"Paris\"}",\ "name": "get_weather"\ },\ "id": "call_GRNwPXnbuQW4Sa3QNB3FYkYw",\ "index": 0,\ "type": "function"\ }\ ]\ }\ }\ ], "created": 1774809792, "id": "chatcmpl-1ce4aeac-6c34-468a-ba6b-b96c5372a1dc", "model": "gpt-5-4-2026-03-05", "object": "chat.completion", "usage": { "completion_tokens": 67, "prompt_tokens": 572, "total_tokens": 639 } } Run your function locally, then call the API again with the full transcript: original messages, the assistant message including `tool_calls`, and one `tool` message per call. Replace IDs and `tool_calls` with values from the first response. Repeat until `finish_reason` is `"stop"` (or `"length"`) and there are no new `tool_calls`. ### [​](https://docs.oxen.ai/examples/inference/chat_completions#follow-up-request-curl-and-openai-python-sdk) Follow-up request: `curl` and OpenAI Python SDK The follow-up HTTP body matches what the OpenAI SDK builds when you append assistant and `tool` messages in a loop. cURL Python (OpenAI SDK) curl -X POST https://hub.oxen.ai/api/ai/chat/completions \ -H "Authorization: Bearer $OXEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-5-4-2026-03-05", "messages": [\ {\ "role": "user",\ "content": "What is the weather in Paris?"\ },\ {\ "role": "assistant",\ "content": null,\ "tool_calls": [\ {\ "id": "call_01ABC",\ "type": "function",\ "function": {\ "name": "get_weather",\ "arguments": "{\"city\": \"Paris\"}"\ }\ }\ ]\ },\ {\ "role": "tool",\ "tool_call_id": "call_01ABC",\ "content": "{\"temperature_c\": 18, \"conditions\": \"Partly cloudy\"}"\ }\ ], "tools": [\ {\ "type": "function",\ "function": {\ "name": "get_weather",\ "description": "Get current weather for a city",\ "parameters": {\ "type": "object",\ "properties": {\ "city": {\ "type": "string",\ "description": "City name"\ }\ },\ "required": ["city"]\ }\ }\ }\ ] }' [​](https://docs.oxen.ai/examples/inference/chat_completions#errors) Errors ------------------------------------------------------------------------------ The API returns errors as JSON with an `error` object and a standard HTTP status code. | Status | Meaning | | --- | --- | | `400` | Bad request (missing model, empty messages, invalid parameters) | | `401` | Invalid or missing API key | | `429` | Rate limit exceeded | | `500` | Internal server error | { "error": { "message": "You must specify a model to call" } } [πŸ“– Overview](https://docs.oxen.ai/getting-started/inference) [πŸ‘οΈ Vision Language Models](https://docs.oxen.ai/examples/inference/vision_language_models) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Using Models on Oxen.ai - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/getting-started/inference#content-area) [​](https://docs.oxen.ai/getting-started/inference#model-api) Model API -------------------------------------------------------------------------- Oxen.ai’s API allows you to start building on top of the [latest models](https://oxen.ai/ai/models) and deploy [fine-tuned models](https://docs.oxen.ai/getting-started/fine-tuning) with a single API. If a model is too slow, costly, inaccurate, or if you want full control of the weights, you can use our [one-click interface to fine-tune](https://docs.oxen.ai/getting-started/fine-tuning) and deploy a custom model using the same interface. [​](https://docs.oxen.ai/getting-started/inference#all-your-modalities-in-one-place) All your modalities, in one place ------------------------------------------------------------------------------------------------------------------------- Whether you want to generate text, images, or videos, Oxen.ai has you covered. If you want any other modality or model, reach out at [support@oxen.ai](mailto:support@oxen.ai) and we’ll be happy to add your use-case to the platform. Checkout the documentation for each modality to learn more about how to use them. Chat Completions ---------------- Generate a response based on a user text prompt. Image Generation ---------------- Generate images based on a user prompt. Image Editing ------------- Edit an image based on a user prompt and a reference image. Video Generation ---------------- Generate a video based on a user prompt. [πŸ‚ Oxen.ai](https://docs.oxen.ai/getting-started/intro) [πŸ’¬ Language Models](https://docs.oxen.ai/examples/inference/chat_completions) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # πŸ“‘ Oxen Server - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/getting-started/oxen-server#content-area) You can deploy your own `oxen-server` instance on your own infrastructure, or use the hosted version on [OxenHub](https://oxen.ai/) . If you want to kick the tires of Oxen in the privacy of your own infrastructure, we recommend you setup a local server. oxen-server start -p 3000 -i 0.0.0.0 The hosted solution comes with a [UI](https://oxen.ai/) and the benefits of not having to setup infrastructure yourself. [Sign up here](https://oxen.ai/register) to get started. ![OxenHub](https://mintcdn.com/oxenai/s_o9ZlhOEkYJf27_/images/ImageNet-Oxen-Files.png?w=2500&fit=max&auto=format&n=s_o9ZlhOEkYJf27_&q=85&s=8db40c975111a3e5d4698120c621e86f) [​](https://docs.oxen.ai/getting-started/oxen-server#-install) βš™οΈ Install ---------------------------------------------------------------------------- To setup a local Oxen Server instance, first install the `oxen-server` binary. ### [​](https://docs.oxen.ai/getting-started/oxen-server#mac-os) Mac OS On Mac-OS you can use [Homebrew](https://brew.sh/) to install the binary. brew tap Oxen-AI/oxen-server brew install oxen-server ### [​](https://docs.oxen.ai/getting-started/oxen-server#ubuntu) Ubuntu On Ubuntu you can download the latest .deb file from our [GitHub Releases](https://github.com/Oxen-AI/Oxen/releases) and install it. wget https://github.com/Oxen-AI/Oxen/releases/latest/download/oxen-server-ubuntu-latest.deb sudo dpkg -i oxen-server-ubuntu-latest.deb ### [​](https://docs.oxen.ai/getting-started/oxen-server#docker) Docker To run the server in a docker container, download the latest .tar file from our [GitHub Releases](https://github.com/Oxen-AI/Oxen/releases) and run the following commands. wget https://github.com/Oxen-AI/Oxen/releases/latest/download/oxen-server-docker.tar docker load < oxen-server-docker.tar docker run -d -v /path/to/my/data:/var/oxen/data -p 80:3001 oxen/oxen-server:latest To install on other platforms, follow the [installation instructions](https://docs.oxen.ai/getting-started/install) . [​](https://docs.oxen.ai/getting-started/oxen-server#-start-server) 🏎️ Start Server --------------------------------------------------------------------------------------- The server can be run with access token authentication turned on or off. The server runs with no authentication by default. oxen-server start To enable authentication, generate a token to give it to the user to access to the server oxen-server add-user --email YOUR_EMAIL --name YOUR_NAME Output: User access token created: XXXXXXXX To give user access have them run the command `oxen config --auth ` You may have different authentication tokens for different hosts. From the client side, you can setup an auth token per host with the `config` command. If you ever need to debug or edit the tokens manually, they are stored in the `~/.config/oxen/auth_config.toml` file. oxen config --auth cat ~/.config/oxen/auth_config.toml To run the server with authentication, use the `-a` flag oxen-server start -a [​](https://docs.oxen.ai/getting-started/oxen-server#-sync-directory) πŸ—‚οΈ Sync Directory ------------------------------------------------------------------------------------------- The default directory that Oxen stores data is `/tmp/oxen_sync`, which is not a good idea for production. To change it set the `SYNC_DIR` environment variable to a path. export SYNC_DIR=/var/oxen/data oxen-server start -a Output: Running πŸ‚ server on 0.0.0.0:3000 Syncing to directory: /var/oxen/data [2022-06-08T10:00:48Z INFO actix_server::builder] Starting 8 workers [2022-06-08T10:00:48Z INFO actix_server::server] Actix runtime found; starting in Actix runtime If you want to change the default `IP ADDRESS` and `PORT` you can do so by passing them in with the `-i` and `-p` parameters. oxen-server start -i 0.0.0.0 -p 4321 [​](https://docs.oxen.ai/getting-started/oxen-server#-debug-logs) 🐞 Debug Logs ---------------------------------------------------------------------------------- The oxen server provides debug logs, which are off by default. You can turn these on with the RUST\_LOG variable. export RUST_LOG="debug" You can also set RUST\_LOG to `info` or `warn` for more restrictive debug logs. Be aware, turning on debug logs can significantly slow down some metadata-heavy operations like `oxen commit` [​](https://docs.oxen.ai/getting-started/oxen-server#-create-a-repository) πŸ“ Create a Repository ---------------------------------------------------------------------------------------------------- Assuming you have already installed the `oxen` CLI, you can create a remote repository on the server. oxen create-remote --name my_namespace/repo_name --host localhost:3000 --scheme http Note: The host and scheme are optional and default to `hub.oxen.ai` and `https` respectively. If you are running a local server, you can set the host to `localhost:3000` and the scheme to `http`. You can either clone data from this remote repository, or push data to it. [​](https://docs.oxen.ai/getting-started/oxen-server#-file-storage) πŸ—„οΈ File Storage --------------------------------------------------------------------------------------- When you create a remote repository, Oxen will create a directory for it on the server. The directory structure is `$SYNC_DIR///.oxen`. ls /var/oxen/data/my_namespace/repo_name/.oxen Output: config.toml history/ refs/ tree/ versions/ All of the metadata and versioned files for a repository are stored in the `.oxen` directory. This directory mirrors the `.oxen` directory in your local repository, so that logic can be reused between the client and server. [​](https://docs.oxen.ai/getting-started/oxen-server#-configureable-storage-backend) πŸ’Ύ Configureable Storage Backend ------------------------------------------------------------------------------------------------------------------------ Oxen allows you to configure the storage backend of self-hosted oxen servers. By default, a repository’s version files are stored in the `.oxen/versions/files` folder, but this can be changed by using the `--storage-backend` and `--storage-backend-path` parameters oxen create-remote --name ox/test_repo --host localhost:3000 --scheme http --storage-backend local --storage-backend-path ~/mountpoint/ox/test_repo/version/files This is useful if you have a large amount of data and you want to store it on a virtual file system. If you set `--storage-backend-path` to a location on your VFS, files that you push to the remote will be stored there. Depending on your VFS, this can slow down some upload and download operations. [​](https://docs.oxen.ai/getting-started/oxen-server#-upload-data) ⬆️ Upload Data ------------------------------------------------------------------------------------ To upload data to the server, you can use the `oxen` CLI to initialize a local repository, add data to it, and push it to the server. # Create a directory for the new dataset mkdir my-dataset cd my-dataset # Initialize a local repository oxen init # Add data to the repository echo "prompt,response" > data.csv oxen add data.csv # Commit the changes oxen commit -m "Initial commit" If you look in your local repository, you will see the `.oxen` directory. ls .oxen Output: config.toml history/ refs/ tree/ versions/ You can set the remote to the server by running the following command. This will update the `config.toml` file in your local repository. oxen config --set-remote origin http://localhost:3000/my_namespace/repo_name If you look at the `config.toml` file, you will see the remote set. cat .oxen/config.toml Output: remote_name = "origin" [[remotes]] name = "origin" url = "http://localhost:3000/my_namespace/repo_name" Once a remote is set you can push your changes to the server. oxen push origin main You can change the remote (origin) and the branch (main) to whichever remote and branch you want to push. [​](https://docs.oxen.ai/getting-started/oxen-server#-clone-data) ⬇️ Clone Data ---------------------------------------------------------------------------------- Clone the empty repository: oxen clone http:///my_namespace/repo_name [​](https://docs.oxen.ai/getting-started/oxen-server#api-spec) API Spec -------------------------------------------------------------------------- The server has a REST API that can be used to interact with the server. The API is documented [here](https://docs.oxen.ai/http-api) . [Workspace](https://docs.oxen.ai/python-api/workspace) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # 🌿 Branches & Merging - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/getting-started/command-line/branches#content-area) Branches let you take a snapshot of your data, experiment freely, and merge the results back without affecting the original. The commands map closely to git. [​](https://docs.oxen.ai/getting-started/command-line/branches#create-a-branch) Create a Branch -------------------------------------------------------------------------------------------------- Create a new branch and check it out in one step with `oxen checkout -b`. oxen checkout -b feature [​](https://docs.oxen.ai/getting-started/command-line/branches#list-branches) List Branches ---------------------------------------------------------------------------------------------- To list the branches in your repository (highlighting the one you’re on), use `oxen branch`. oxen branch To see branches that exist on the remotes, add `--remote`. oxen branch --remote To delete a branch, use `oxen branch --delete`. This fails if the branch has changes that haven’t been merged. oxen branch --delete feature Use `-D` to force-delete a branch. oxen branch -D feature [​](https://docs.oxen.ai/getting-started/command-line/branches#switch-between-branches) Switch Between Branches ------------------------------------------------------------------------------------------------------------------ Use `oxen checkout` to switch branches. This restores the working directory to the HEAD commit of the branch you’re checking out. oxen checkout main You can also check out a specific commit. oxen checkout COMMIT_ID [​](https://docs.oxen.ai/getting-started/command-line/branches#merge-branches) Merge Branches ------------------------------------------------------------------------------------------------ Merge another branch into your current branch with `oxen merge`. This creates a merge commit, or fails if there are conflicts to resolve. oxen merge TARGET_BRANCH If you’re collaborating, you may instead want to open a merge request through the [Oxen.ai web UI](https://oxen.ai/) . ![Oxen.ai merge request](https://mintcdn.com/oxenai/Bb9kRFujEIMk3du0/images/merge_request.png?w=2500&fit=max&auto=format&n=Bb9kRFujEIMk3du0&q=85&s=66856a28d7d85b8cd8d76974f4adc740) [πŸ“ Track Changes](https://docs.oxen.ai/getting-started/command-line/track_changes) [πŸ”„ Sync with a Remote](https://docs.oxen.ai/getting-started/command-line/sync_remote) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # βš™οΈ Setup & Authentication - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/getting-started/command-line/setup#content-area) [​](https://docs.oxen.ai/getting-started/command-line/setup#setup-user) Setup User ------------------------------------------------------------------------------------- To use Oxen, you’ll need to set up a local Oxen username and email. This is what will show up in `oxen log` or in the OxenHub dashboard for who changed what. oxen config --name "YOUR_NAME" --email "YOUR_EMAIL" This will save the user to `~/.config/oxen/user_config.toml` for future use. [​](https://docs.oxen.ai/getting-started/command-line/setup#auth-tokens) Auth Tokens --------------------------------------------------------------------------------------- Pushing data or cloning private repositories requires a valid API Key. You can obtain one by creating an account on and going to your profile. ![Oxen.ai authentication key](https://mintcdn.com/oxenai/iXdgSU_j00SuyDvU/images/auth_key.png?w=2500&fit=max&auto=format&n=iXdgSU_j00SuyDvU&q=85&s=fa0b3fb3dec23a1dd60f7505f9b49f5c) The token can then be set with `oxen config --auth`. oxen config --auth 'hub.oxen.ai' YOUR_AUTH_TOKEN This will write the auth token to `~/.config/oxen/auth_config.toml`. To push or access repositories on [Oxen.ai](https://oxen.ai/) , set the host as `hub.oxen.ai`. If you set up your own [oxen-server](https://docs.oxen.ai/getting-started/oxen-server) , you can generate custom auth tokens there. [βš’οΈ Installation](https://docs.oxen.ai/getting-started/install) [πŸš€ Start a Repository](https://docs.oxen.ai/getting-started/command-line/start_repository) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # 🧹 Maintenance - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/getting-started/command-line/maintenance#content-area) The `oxen prune` command removes orphaned nodes and version files that are not referenced by any commit in your repository. This helps reclaim disk space by cleaning up unreferenced data that accumulates over time. [​](https://docs.oxen.ai/getting-started/command-line/maintenance#basic-usage) Basic Usage --------------------------------------------------------------------------------------------- To prune your repository and remove orphaned files: oxen prune This will scan your repository, identify unreferenced nodes and version files, and remove them to free up disk space. In large repositories, the prune operation can take a while to run as it needs to scan all nodes and version files. Consider using `--dry-run` first to estimate the scope of the operation. [​](https://docs.oxen.ai/getting-started/command-line/maintenance#dry-run-mode) Dry Run Mode ----------------------------------------------------------------------------------------------- Before actually removing files, you can preview what would be deleted using the `--dry-run` flag: oxen prune --dry-run Or using the short form: oxen prune -n This is useful to see how much space would be freed without making any changes to your repository. [​](https://docs.oxen.ai/getting-started/command-line/maintenance#understanding-prune-statistics) Understanding Prune Statistics ----------------------------------------------------------------------------------------------------------------------------------- After running `oxen prune`, you’ll see detailed statistics about the operation: Output: Prune Statistics: Nodes: Scanned: 1250 Kept: 1100 Removed: 150 Version Files: Scanned: 3400 Kept: 3200 Removed: 200 Disk Space Freed: 1.2 GB * **Nodes**: Internal data structures that track file metadata * **Scanned**: Total number of nodes examined * **Kept**: Nodes still referenced by commits * **Removed**: Orphaned nodes that were deleted * **Version Files**: Actual file content stored in the repository * **Scanned**: Total number of version files examined * **Kept**: Files still referenced by commits * **Removed**: Orphaned files that were deleted * **Disk Space Freed**: Total amount of storage reclaimed [​](https://docs.oxen.ai/getting-started/command-line/maintenance#when-to-use-prune) When to Use Prune --------------------------------------------------------------------------------------------------------- You should consider running `oxen prune` when: * You’ve deleted or modified many files across multiple commits * You’ve rebased or reset your commit history * You’ve removed large files from your repository * Your `.oxen` directory is taking up more space than expected * You want to optimize repository storage before sharing or archiving [​](https://docs.oxen.ai/getting-started/command-line/maintenance#safety) Safety ----------------------------------------------------------------------------------- The prune operation only removes files that are not referenced by any commit in your repository. It will never delete: * Files referenced by any commit * Files in your working directory * Staged files * The `.oxen` directory structure itself This makes it safe to run without worrying about losing committed data. [​](https://docs.oxen.ai/getting-started/command-line/maintenance#example-workflow) Example Workflow ------------------------------------------------------------------------------------------------------- A typical workflow for pruning your repository: # First, check what would be removed oxen prune --dry-run # Review the statistics # If everything looks good, run the actual prune oxen prune # Verify your repository is still intact oxen status oxen log [πŸ—‚οΈ Workspaces](https://docs.oxen.ai/getting-started/command-line/workspaces) [πŸ”§ Debugging & Performance](https://docs.oxen.ai/getting-started/command-line/debugging) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Repositories on Oxen.ai - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/getting-started/data#content-area) When using models on Oxen.ai, by default we store the model inputs, outputs, and metadata in a repository. Every piece of data is versioned so you can trace the provenance of your data and models. In order to version data at scale, we built an [open source version control system](https://github.com/Oxen-AI/Oxen) that can scale to monorepos with millions of files and terabytes of data. [​](https://docs.oxen.ai/getting-started/data#key-concepts) Key Concepts --------------------------------------------------------------------------- * **Repository**: A collection of files and folders that is versioned together. * **Commit**: A snapshot of a repository at a given time. * **Branch**: A named pointer to a commit. * **Dataset**: A tabular file within an oxen repository that can be indexed and searched. ie csv, jsonl, parquet, etc. * **Workspace**: The equivalent of a working directory on the remote server where files can be added in an uncommitted state. Follow along with the [Version Control](https://docs.oxen.ai/examples/data/versioning) guide to learn how to version your data. [πŸŽ₯ Video Generation](https://docs.oxen.ai/examples/inference/video_generation) [πŸ’Ύ Version Control](https://docs.oxen.ai/examples/data/versioning) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # πŸ“Š Datasets - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/examples/data/datasets#content-area) In Oxen.ai, datasets are used to structure your unstructured data. Any tabular data file will automatically be turned into a collaborative database that can be versioned and used to organize data, can be queried, or fed in as training data for models. Oxen.ai datasets are accessible with an easy to use web interface as well as a command line tools, python, and HTTP library. [​](https://docs.oxen.ai/examples/data/datasets#repositories-vs-datasets) Repositories vs Datasets ----------------------------------------------------------------------------------------------------- Repositories are the top level container for your datasets. They are a collection of versioned files and directories. ![Oxen.ai Repo](https://mintcdn.com/oxenai/GvHCMKbbr_BpHEwk/images/datasets/image_net_files.png?w=2500&fit=max&auto=format&n=GvHCMKbbr_BpHEwk&q=85&s=069cc60084725ee6859020b7a0a23913) Certain files within Oxen with the extensions `csv`, `tsv`, `jsonl` and `parquet` gain super powers. These dataset files can be multi-modal containing links to images, audio, and PDFs. You can query them in natural language, and edit them like a spreadsheet. ![Image Net](https://mintcdn.com/oxenai/GvHCMKbbr_BpHEwk/images/datasets/image_net_train.png?w=2500&fit=max&auto=format&n=GvHCMKbbr_BpHEwk&q=85&s=18f7340cc87dee54b9a4369cd7b79a28) Under the hood we turn these raw files into a lightweight database that can be queried, edited, versioned, and downloaded. [​](https://docs.oxen.ai/examples/data/datasets#view-your-dataset) View Your Dataset --------------------------------------------------------------------------------------- Click the file your repository to open the dataset you want to work with. If you want to follow along with this example, download the [Thinking LLMs](https://www.oxen.ai/ox/Thinking-LLMs) dataset. ![Oxen.ai Thinking LLMs Repo](https://mintcdn.com/oxenai/VndlMSXTb9YuU-Wl/images/thinking_llms.png?w=2500&fit=max&auto=format&n=VndlMSXTb9YuU-Wl&q=85&s=7f5d2b0250ba7cd3d928a7f91a23dc3e) [​](https://docs.oxen.ai/examples/data/datasets#download-your-dataset) Download Your Dataset ----------------------------------------------------------------------------------------------- Datasets can be downloaded directly from the UI or using the CLI and Python library. You can grab any revision of the dataset by specifying the revision as a branch name or commit id. Python CLI from oxen import RemoteRepo # Connect to the remote repository (does not download any data) repo = RemoteRepo("YOUR_USERNAME/YOUR_REPO") # Download the dataset repo.download("path/to/dataset.jsonl", revision="main") [​](https://docs.oxen.ai/examples/data/datasets#upload-your-dataset) Upload Your Dataset ------------------------------------------------------------------------------------------- Once you have created a repository, you can use the β€œAdd Files” button on your repository to upload dataset files through the UI. The dataset will automatically be versioned so you can iterate on it and track changes. ![Oxen.ai Thinking LLMs Repo](https://mintcdn.com/oxenai/GvHCMKbbr_BpHEwk/images/datasets/dataset_upload.png?w=2500&fit=max&auto=format&n=GvHCMKbbr_BpHEwk&q=85&s=a536358a13a63a2ea5f8a6e5391c44d9) Datasets can also be uploaded from the command line or python library. This allows you to integrate Oxen into your existing codebases or CI/CD pipelines. The workflow is similar to git where you `add` and `commit` your changes. Python CLI from oxen import RemoteRepo # Connect to the remote repository repo = RemoteRepo("YOUR_USERNAME/YOUR_REPO") # Upload the file to the remote repository repo.add("path/to/dataset.jsonl", dst="datasets/") # Commit the changes repo.commit("Add dataset.jsonl to the datasets/ directory") To perform **write operations** on datasets, you need to be an editor on the repository and have your username and API key set. You can set your username and API key using the [CLI](https://docs.oxen.ai/getting-started/command-line/setup) or [Python library](https://docs.oxen.ai/python-api/index) .Read more about [Authentication & Authorization](https://docs.oxen.ai/getting-started/auth) . [​](https://docs.oxen.ai/examples/data/datasets#using-fsspec) Using `fsspec` ------------------------------------------------------------------------------- Since datasets are just stored as files and directories, you can interact with them directly using [fsspec](https://filesystem-spec.readthedocs.io/en/latest/) . This allows you to read and write to them similar to how you would with a local file system. For example if you want to read the contents of a file on the server, you can simply use the `open` method. Python import oxen fs = oxen.OxenFS("YOUR_USERNAME", "YOUR_REPO") with fs.open("path/to/dataset.jsonl") as f: content = f.read() # Print the first 100 characters of the file print(content[:100]) If you want to write to a file, you can use the `write` method. Python fs = oxen.OxenFS("YOUR_USERNAME", "YOUR_REPO") with fs.open("path/to/dataset.jsonl", "w") as f: f.write("Hello, world!") If you want to specify a commit message, simply add the commit message in the scope of the `with` block. Python fs = oxen.OxenFS("YOUR_USERNAME", "YOUR_REPO") with fs.open("path/to/dataset.jsonl", "w") as f: f.write("{\"question\": \"What is the capital of France?\", \"answer\": \"Paris\"}") f.commit_message = "Add a new row" To learn more about how to use fsspec with Oxen, check out the [OxenFS](https://docs.oxen.ai/python-api/oxen_fs) documentation. [​](https://docs.oxen.ai/examples/data/datasets#using-pandas) Using Pandas ----------------------------------------------------------------------------- Since `OxenFS` implements the `fsspec` interface, you can use it with any library that supports `fsspec`. For example, you can use it with [pandas](https://pandas.pydata.org/) to read and write to datasets. Python import pandas as pd # Format: oxen:///@/ df = pd.read_parquet("oxen://openai:gsm8k@main/gsm8k_test.parquet") # Print the first 5 rows print(df.head()) # Apply a transformation to the dataframe df["answer"] = df["answer"].apply(lambda x: x.upper()) # Write the dataframe to a new file df.to_parquet("oxen://openai:gsm8k@main/gsm8k_test_new.parquet") [​](https://docs.oxen.ai/examples/data/datasets#your-dataset-is-a-database) Your Dataset is a Database --------------------------------------------------------------------------------------------------------- Datasets look like raw files on the surface, but some of their superpowers come from the fact that Oxen.ai can index them into a [DuckDB](https://duckdb.org/) database on the remote server. This allows you to query your dataset directly with SQL. You can use the [DataFrame](https://docs.oxen.ai/python-api/data_frame) class in the python library to interact with your dataset as a database. Python from oxen import DataFrame # Connect to and index the data frame df = DataFrame("YOUR_USERNAME/YOUR_REPO", "path/to/file.jsonl") # Print the first 5 rows that are spam results = df.query("SELECT * FROM df where category = 'spam' LIMIT 5") print(results) Not only can you query your dataset, but you can also add rows, add columns, and perform other database operations before committing your changes. This is useful if you want to build labeling workflows or other data pipelines. Python from oxen import DataFrame # Connect to and index the data frame # Note: This must be an existing file committed to the repo # indexing may take a while for large files df = DataFrame("YOUR_USERNAME/YOUR_REPO", "path/to/file.jsonl") # Add a row row_id = data_frame.insert_row({"category": "spam", "message": "Hello, do I have an offer for you!"}) # Get a row by id row = data_frame.get_row_by_id(row_id) print(row) # Update a row row = data_frame.update_row(row_id, {"category": "ham"}) print(row) # Delete a row data_frame.delete_row(row_id) # Get the current changes to the data frame status = data_frame.diff() print(status) # Commit the changes data_frame.commit("Updating data.csv")​ Note: There are currently some limitations to the DataFrame API. 1. You must have **write access** to the repository to use the DataFrame API. This is because it creates a [workspace](https://docs.oxen.ai/python-api/workspace) on the remote server to index the dataset. 2. Indexing may take a while for large files, and is performed on instantiation of the DataFrame object. 3. The DataFrame API is currently only supported for single files, you cannot yet use it to JOIN datasets across files. [​](https://docs.oxen.ai/examples/data/datasets#datasets-as-a-vector-database) Datasets as a Vector Database --------------------------------------------------------------------------------------------------------------- If you have a column in your dataset that contains a vector of floats representing a piece of text or image, you can use Oxen.ai as a vector database to sort by similarity. ![Embedding a dataset](https://mintcdn.com/oxenai/GvHCMKbbr_BpHEwk/images/datasets/embeddings.png?w=2500&fit=max&auto=format&n=GvHCMKbbr_BpHEwk&q=85&s=2cd647ffca323ddc5050d4c02a85ab08) Python from oxen import DataFrame # Connect to and index the data frame df = DataFrame("YOUR_USERNAME/YOUR_REPO", "path/to/file.parquet") # Check if the dataset is indexed for embeddings search if not df.is_nearest_neighbors_enabled(): # Enable nearest neighbors search df.enable_nearest_neighbors() # Get an embedding for a specific row (may return multiple embeddings there are multiple results for the query) embed_column = "embedding" embeddings = df.get_embeddings({"prompt": "What is the capital of France?"}, column=embed_column) # Query the data frame embedding = embeddings[0] results = df.query( embedding=embedding, sort_by_similarity_to=embed_column ) for row in results: print(row["prompt"]) If you don’t have an embedding column, you can compute one using an Evaluation on the Oxen.ai platform. [​](https://docs.oxen.ai/examples/data/datasets#rendering-images-and-links) Rendering Images and Links --------------------------------------------------------------------------------------------------------- In the dataset viewer, you can render images and links to other files in the dataset. The assumption is that the value in the rows is a relative path to a file in the same repository. For example if we have a directory of images in the `images` directory, we can render the image by using the relative path to the image `images/my_image_0.png`. ![Rendering images and links](https://mintcdn.com/oxenai/GvHCMKbbr_BpHEwk/images/datasets/ox_with_wings.png?w=2500&fit=max&auto=format&n=GvHCMKbbr_BpHEwk&q=85&s=cf0be1f4ac6f272526d6ae150fbf27bb) In order to enable the rendering, you need to edit the `render` function in the dataset viewer. Go into the edit mode of the dataset, then edit the column you want to render. You can select from a few different rendering options including: `image`, `link`, `markdown`, and `code`. ![Edit render function](https://mintcdn.com/oxenai/GvHCMKbbr_BpHEwk/images/datasets/image_metadata.png?w=2500&fit=max&auto=format&n=GvHCMKbbr_BpHEwk&q=85&s=4650a60991ef69aa2b2188e73787de2b) This will save metadata to the repository that will be used to render the images and links. To programmatically set the render function, checkout the [file metadata documentation](https://docs.oxen.ai/concepts/file_metadata) . [​](https://docs.oxen.ai/examples/data/datasets#using-the-ui) Using the UI ----------------------------------------------------------------------------- ### [​](https://docs.oxen.ai/examples/data/datasets#editing-your-dataset) Editing Your Dataset You can edit your dataset directly from the UI by clicking the pencil icon in the upper right of the dataset viewer. This will open the file in an editor that will allow to add, edit, and delete rows and columns. ![Editing a dataset](https://mintcdn.com/oxenai/GvHCMKbbr_BpHEwk/images/datasets/remove_row.png?w=2500&fit=max&auto=format&n=GvHCMKbbr_BpHEwk&q=85&s=2f2df4f2945306d78eb26a1ea8dadf76) The editor will not commit any changes to the repository until you use the β€œCommit” button to write a message and save your changes. ![Editing a dataset](https://mintcdn.com/oxenai/GvHCMKbbr_BpHEwk/images/datasets/commit_data_frame.png?w=2500&fit=max&auto=format&n=GvHCMKbbr_BpHEwk&q=85&s=45510c2307e5650e722002e735088522) ### [​](https://docs.oxen.ai/examples/data/datasets#use-llms-to-augment-your-dataset) Use LLMs to Augment Your Dataset In Oxen.ai, you can generate new columns and rows using LLMs. This is a great way to automatically label your dataset or generate training data for small LLMs from larger models. Click the β€œActions” button and select β€œRun Inference”. ![Oxen.ai Evaluation](https://mintcdn.com/oxenai/GvHCMKbbr_BpHEwk/images/evaluations/run_inference_dataset.png?w=2500&fit=max&auto=format&n=GvHCMKbbr_BpHEwk&q=85&s=e83658e8646db188a0adb63584769a26) Simply select a model, write a prompt, and run the model row by row on the dataset. ![Oxen.ai Evaluation](https://mintcdn.com/oxenai/GvHCMKbbr_BpHEwk/images/datasets/categorieze_columns.png?w=2500&fit=max&auto=format&n=GvHCMKbbr_BpHEwk&q=85&s=e3409c2cf5c52d6aa1d66853dfe6ebc0) ### [​](https://docs.oxen.ai/examples/data/datasets#query-your-dataset) Query Your Dataset To query your dataset, write a question in plain English in the search bar. This will automatically translate the question into a SQL query and apply it to the view of your data. For example, you can look at the distribution of question types by asking: What are all the categories sorted by count? ![Where to find Text2SQL](https://mintcdn.com/oxenai/GvHCMKbbr_BpHEwk/images/datasets/text2sql.png?w=2500&fit=max&auto=format&n=GvHCMKbbr_BpHEwk&q=85&s=18d8939b0737c681a41fd43f82c1b027) If the query engine makes a mistake, no worries! You can edit the SQL query to get the results you want. [πŸ’Ύ Version Control](https://docs.oxen.ai/examples/data/versioning) [πŸ“¦ Workspaces](https://docs.oxen.ai/examples/data/workspaces) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # πŸ”„ Sync with a Remote - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/getting-started/command-line/sync_remote#content-area) Once your repository has a remote configured (see [Start a Repository](https://docs.oxen.ai/getting-started/command-line/start_repository#configure-a-remote) ), you can push your work and pull collaborators’ changes. [​](https://docs.oxen.ai/getting-started/command-line/sync_remote#push-changes) Push Changes ----------------------------------------------------------------------------------------------- Once you’ve committed changes locally, push them to a remote with `oxen push`. oxen push origin main If you don’t supply a remote name or branch, they default to `origin` and the current branch. oxen push ### [​](https://docs.oxen.ai/getting-started/command-line/sync_remote#resume-a-push) Resume a Push If a push is cancelled partway through, use `--missing-files` to resume and upload only the remaining files. oxen push --missing-files [​](https://docs.oxen.ai/getting-started/command-line/sync_remote#pull-changes) Pull Changes ----------------------------------------------------------------------------------------------- To pull the latest commits for a branch β€” downloading their files and Merkle trees, then checking out the latest commit β€” use `oxen pull`. oxen pull origin main If no arguments are provided, the remote defaults to `origin` and the branch defaults to the current branch. oxen pull As with `clone`, you can pull all branches with `--all`. oxen pull --all [​](https://docs.oxen.ai/getting-started/command-line/sync_remote#fetch-changes) Fetch Changes ------------------------------------------------------------------------------------------------- To fetch the latest changes without checking them out in the working directory, use `oxen fetch`. oxen fetch This is useful when you want to inspect what’s new on the remote before deciding whether to merge or check it out. [​](https://docs.oxen.ai/getting-started/command-line/sync_remote#view-configured-remotes) View Configured Remotes --------------------------------------------------------------------------------------------------------------------- `oxen remote` lists the remotes configured for your repository. oxen remote Output: origin Use `--verbose` to also see each remote’s URL. oxen remote --verbose Output: origin https://hub.oxen.ai/ox/CatDogBBox local_dev http://localhost:3000/ox/CatDogBBox To add or change a remote’s URL, see [Configure a Remote](https://docs.oxen.ai/getting-started/command-line/start_repository#configure-a-remote) on the Start a Repository page. [🌿 Branches & Merging](https://docs.oxen.ai/getting-started/command-line/branches) [πŸ—‚οΈ Workspaces](https://docs.oxen.ai/getting-started/command-line/workspaces) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # βš’οΈ Installation - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/getting-started/install#content-area) [​](https://docs.oxen.ai/getting-started/install#command-line-tools) Command Line Tools ------------------------------------------------------------------------------------------ The Oxen client can be installed on MacOS via [homebrew](https://brew.sh/) or by downloading the relevant binaries for Linux or Windows. You can find the source code for the client [here](https://github.com/Oxen-AI/Oxen) and can also build from source for your platform. All binaries for MacOS, Linux, Windows and Docker are available on [GitHub Releases](https://github.com/Oxen-AI/Oxen/releases) . ### [​](https://docs.oxen.ai/getting-started/install#mac) Mac brew install oxen ### [​](https://docs.oxen.ai/getting-started/install#linux) Linux #### [​](https://docs.oxen.ai/getting-started/install#ubuntu) Ubuntu We provide .deb packages that can be installed directly on Debian-based systems such as Ubuntu. First, download the release for your system’s architecture. For x86-64 wget https://github.com/Oxen-AI/Oxen/releases/latest/download/oxen-linux-x86_64.deb For ARM64 wget https://github.com/Oxen-AI/Oxen/releases/latest/download/oxen-linux-arm64.deb Then run sudo dpkg -i oxen-linux-*.deb #### [​](https://docs.oxen.ai/getting-started/install#other-distributions) Other distributions We also provide distributions-agnostic binaries that can be installed on any Linux system. First, download the release for your system’s architecture. For x86-64 wget https://github.com/Oxen-AI/Oxen/releases/latest/download/oxen-linux-x86_64.tar.gz For ARM64 wget https://github.com/Oxen-AI/Oxen/releases/latest/download/oxen-linux-arm64.tar.gz tar -xzvf oxen-linux-*.tar.gz chmod +x oxen mv oxen /usr/local/bin ### [​](https://docs.oxen.ai/getting-started/install#windows) Windows We provide Windows binaries as a .exe. wget https://github.com/Oxen-AI/Oxen/releases/latest/download/oxen-windows-x86_64.exe.zip [​](https://docs.oxen.ai/getting-started/install#python-package) Python Package ---------------------------------------------------------------------------------- The easiest way to get started with the Oxen Python library is to use `uv`. [Install uv](https://docs.astral.sh/uv/getting-started/installation/) . Install a supported Python version uv python install 3.13 Then, create and init a new uv project. mkdir my-python-script/ && cd my-python-script/ uv init This will create a virtual environment with the latest installed Python version. Next, add the oxen library to the project uv add oxenai Then, to test that everything is working, update `main.py` with the following code. import oxen oxen.clone("ox/SpanishToEnglish") Then run the script with `uv run` so it executes in the virtual environment. uv run main.py Note that this will only install the Python library and not the command line tool. ### [​](https://docs.oxen.ai/getting-started/install#installing-oxen-through-jupyter-notebooks-or-google-colab) Installing Oxen through Jupyter Notebooks or Google Colab Create and run this cell: !pip install oxenai ### [​](https://docs.oxen.ai/getting-started/install#docker) Docker We build many binary wheels for the Python library (and we’re working on adding more), but if your container image doesn’t work with one of our binary wheels, pip will have to build it from source. Here is a minimal Dockerfile for a Debian-based image that installs the prerequisites for building the Oxen library from source: FROM python:3.12-slim-bookworm RUN apt update RUN apt install -y clang pkg-config libssl-dev curl RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y ENV PATH="/root/.cargo/bin:${PATH}" RUN pip install oxenai [​](https://docs.oxen.ai/getting-started/install#server-install) Server Install ---------------------------------------------------------------------------------- The Oxen server binary can be deployed where ever you want to store and backup your data. It is an HTTP server that the client communicates with to enable collaboration. ### [​](https://docs.oxen.ai/getting-started/install#mac-2) Mac brew tap Oxen-AI/oxen-server brew install oxen-server ### [​](https://docs.oxen.ai/getting-started/install#docker-2) Docker First, download the Docker image based on the host architecture. For x86-64 wget https://github.com/Oxen-AI/Oxen/releases/latest/download/oxen-server-docker-x86_64.tar For ARM64 wget https://github.com/Oxen-AI/Oxen/releases/latest/download/oxen-server-docker-arm64.tar Then, load the image into Docker. docker load < oxen-server-docker-*.tar Finally, run a new container. docker run -d -v /var/oxen/data:/var/oxen/data -p 80:3001 oxen/oxen-server:latest ### [​](https://docs.oxen.ai/getting-started/install#linux-2) Linux #### [​](https://docs.oxen.ai/getting-started/install#ubuntu-2) Ubuntu We provide .deb packages that can be installed directly on Debian-based systems such as Ubuntu. First, download the release for your system’s architecture. For x86-64 wget https://github.com/Oxen-AI/Oxen/releases/latest/download/oxen-server-linux-x86_64.deb For ARM64 wget https://github.com/Oxen-AI/Oxen/releases/latest/download/oxen-server-linux-arm64.deb Then run sudo dpkg -i oxen-server-linux-*.deb #### [​](https://docs.oxen.ai/getting-started/install#other-distributions-2) Other distributions First, download the release for your system’s architecture. For x86-64 wget https://github.com/Oxen-AI/Oxen/releases/latest/download/oxen-server-linux-x86_64.tar.gz For ARM64 wget https://github.com/Oxen-AI/Oxen/releases/latest/download/oxen-server-linux-arm64.tar.gz tar -xzvf oxen-server-linux-*.tar.gz chmod +x oxen-server mv oxen-server /usr/local/bin ### [​](https://docs.oxen.ai/getting-started/install#windows-2) Windows We provide Windows binaries as a .exe. wget https://github.com/Oxen-AI/Oxen/releases/latest/download/oxen-server-windows-x86_64.exe.zip To get up and running using the client and server, you can follow the [getting started docs](https://github.com/Oxen-AI/oxen) . [​](https://docs.oxen.ai/getting-started/install#building-from-source) Building from Source ---------------------------------------------------------------------------------------------- To build the command line tool from source, you can follow these steps. 1. Install rustup via the instructions at [https://rustup.rs/](https://rustup.rs/) 2. Clone the repository [https://github.com/Oxen-AI/Oxen](https://github.com/Oxen-AI/Oxen) git clone git@github.com:Oxen-AI/Oxen.git 3. `cd` into the cloned repository cd Oxen/oxen-rust 4. Run this command (the release flag is recommended but not necessary): cargo build --release 5. After the build has finished, the `oxen` binary will be in `Oxen/oxen-rust/target/release` (or, if you did not use the β€”release flag, `Oxen/oxen-rust/target/debug`). Now, to make it usable from a terminal window, you have the option to add it to create a symlink or to add it to your `PATH`. 6. To add oxen to your `PATH`: Add this line to your `.bashrc` (or equivalent, e.g. `.zshrc`) export PATH="$PATH:/path/to/Oxen/oxen-rust/target/release" 7. Alternatively, to create a symlink, run the following command: sudo ln -s /path/to/Oxen/oxen-rust/target/release/oxen /usr/local/bin/oxen Note that if you did not use the `--release` flag when building Oxen, you will have to change the path. [πŸŽ₯ Video Generation](https://docs.oxen.ai/examples/fine-tuning/video_generation) [βš™οΈ Setup & Authentication](https://docs.oxen.ai/getting-started/command-line/setup) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # πŸš€ Start a Repository - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/getting-started/command-line/start_repository#content-area) Most Oxen workflows begin in one of three ways: initializing a fresh local repository, cloning an existing one from a remote, or pulling down specific files without setting up a full repo. [​](https://docs.oxen.ai/getting-started/command-line/start_repository#initialize-a-local-repository) Initialize a Local Repository -------------------------------------------------------------------------------------------------------------------------------------- Create a new Oxen repository in the current directory with `oxen init`. oxen init This creates a `.oxen/` directory in your working directory containing the repository metadata. As you add and commit files, each commit’s [Merkle Tree](https://ghost.oxen.ai/merkle-tree-101/) is stored under `.oxen/`. [​](https://docs.oxen.ai/getting-started/command-line/start_repository#clone-a-remote-repository) Clone a Remote Repository ------------------------------------------------------------------------------------------------------------------------------ There are a few ways to clone an Oxen repository, depending on how much data you want to transfer. The default `oxen clone` with no flags downloads the _latest commit_ from the `main` branch. oxen clone https://hub.oxen.ai/ox/CatDogBBox This creates a new directory `CatDogBBox` containing the files from the latest commit, plus a `.oxen/` folder with the [Merkle Tree](https://ghost.oxen.ai/merkle-tree-101/) for the branch’s history. ### [​](https://docs.oxen.ai/getting-started/command-line/start_repository#clone-a-specific-branch) Clone a Specific Branch Use the `-b` flag to clone from a branch other than `main`. oxen clone https://hub.oxen.ai/ox/CatDogBBox -b my-pets ### [​](https://docs.oxen.ai/getting-started/command-line/start_repository#clone-all-branches) Clone All Branches To clone the commit history for every branch (useful when migrating a repo to a new remote), use `--all`. oxen clone https://hub.oxen.ai/ox/CatDogBBox --all ### [​](https://docs.oxen.ai/getting-started/command-line/start_repository#clone-a-subtree) Clone a Subtree If you only need a subset of the repository, use `--filter` and `--depth` to limit the clone. `--filter` selects which directories to clone, while `--depth` limits how many levels of subdirectories are recursed into. oxen clone https://hub.oxen.ai/ox/CatDogBBox --filter annotations --depth 1 This clones only the subtree starting at the `annotations` directory, without recursing into any new subdirectories. ### [​](https://docs.oxen.ai/getting-started/command-line/start_repository#remote-mode) Remote Mode If the repository is larger than you can store locally, you can clone it in remote mode to download the commit Merkle trees without the file contents. oxen clone --remote https://hub.oxen.ai/ox/CatDogBBox In a remote-mode repository, you can download individual files or directories on demand with `oxen restore`. oxen restore path/to/file This is useful for inspecting the state of a repository without waiting for all its files to download. [​](https://docs.oxen.ai/getting-started/command-line/start_repository#configure-a-remote) Configure a Remote ---------------------------------------------------------------------------------------------------------------- If you initialized a repository locally, you can point it at a remote with `oxen config --set-remote`. This is what enables `oxen push`, `oxen pull`, and `oxen fetch`. oxen config --set-remote origin https://hub.oxen.ai/ox/CatDogBBox Specify a remote name (commonly `origin`) and the URL of the remote repository. Cloned repositories already have `origin` set automatically. A repo can have multiple remotes β€” most commands default to `origin` if no remote is specified. ### [​](https://docs.oxen.ai/getting-started/command-line/start_repository#create-a-remote-from-the-cli) Create a Remote from the CLI If the remote repository doesn’t exist yet, you can create it from the CLI with `oxen create-remote`. oxen create-remote --host hub.oxen.ai --scheme https --name ox/SampleRepo You can also create remotes through the [Oxen.ai web UI](https://oxen.ai/) . [​](https://docs.oxen.ai/getting-started/command-line/start_repository#download-specific-files) Download Specific Files -------------------------------------------------------------------------------------------------------------------------- If you only need specific files or directories β€” without cloning the whole repository β€” use `oxen download`. oxen download ox/CatDogBBox test.csv To download from a specific branch or commit, pass `--revision`. oxen download ox/CatDogBBox path/to/folder --revision commit_or_branch_name [βš™οΈ Setup & Authentication](https://docs.oxen.ai/getting-started/command-line/setup) [πŸ“ Track Changes](https://docs.oxen.ai/getting-started/command-line/track_changes) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # πŸ”§ Debugging & Performance - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/getting-started/command-line/debugging#content-area) [​](https://docs.oxen.ai/getting-started/command-line/debugging#oxen-tree) Oxen Tree --------------------------------------------------------------------------------------- You can use `oxen tree` to view the current state of the merkle tree for a commit. This gives you a view of the metadata contained in the tree for each file and directory, as well as how many [VNodes](https://ghost.oxen.ai/merkle-tree-vnodes/) are present. oxen tree Output: [Commit] 74bb3ece2ccfa3f23420ef5c0be84865 (0.36.0) "Add Data" -> Daisy daisy@oxen.ai parent_ids "" [Dir] 65d46b6d56 "" (3.5 MB) (4 files) (commit 74bb3ece2c) (3 entries) [VNode] 4f677b731c (3 entries) [File] d29aed6e8d "README.md" (text/markdown) 28 B [d29aed6e8d] (commit 74bb3ece2c) MetadataText(2 lines, 28 chars) [Dir] 5be82041ff "dir" (95.1 KB) (2 files) (commit 74bb3ece2c) (2 entries) [VNode] dca3063656 (2 entries) [File] 17caf6d759 "binary" (application/octet-stream) 8 B [17caf6d759] (commit 74bb3ece2c) [File] b04c7235e3 "image.png" (image/png) 95.1 KB [b04c7235e3] (commit 74bb3ece2c) MetadataImage(1798x839) [Dir] b8fc85925c "other" (3.4 MB) (1 files) (commit 74bb3ece2c) (1 entries) [VNode] c36eb4516e (1 entries) [File] 1fc24f94e0 "audio.mp3" (audio/mpeg) 3.4 MB [1fc24f94e0] (commit 74bb3ece2c) MetadataVideo(2x44100 143.491s) Time to load tree: 4.8259ms [​](https://docs.oxen.ai/getting-started/command-line/debugging#oxen-node) Oxen Node --------------------------------------------------------------------------------------- `oxen node` can be used to inspect file and dir nodes in the merkle tree. This can be used to check whether nodes exist and have been created properly in the merkle tree. You can search for a node by hash or by path. oxen node -n 65d46b6d5616364ba975320b5768c63c Output: [Dir] 65d46b6d56 "" (3.5 MB) (4 files) (commit 74bb3ece2c) (3 entries) ============= hash: 65d46b6d5616364ba975320b5768c63c node: Directory(DirNode(0.36.0) hash: 65d46b6d5616364ba975320b5768c63c name: num_bytes: 3.5 MB num_entries: 3 num_files: 4 data_type_counts: {"audio": 1, "text": 1, "binary": 1, "image": 1} data_type_sizes: {"audio": 3443832, "binary": 8, "text": 28, "image": 95080} ) parent_id: 74bb3ece2ccfa3f23420ef5c0be84865 children.len(): 1 ============= [VNode] 4f677b731c (3 entries) oxen node -p dir/image.png Output: [File] b04c7235e3 "image.png" (image/png) 95.1 KB [b04c7235e3] (commit 74bb3ece2c) MetadataImage(1798x839) ============= hash: b04c7235e38d8e9b4eb1f802d0fe7e60 node: File(FileNode(0.36.0) hash: b04c7235e38d8e9b4eb1f802d0fe7e60 name: image.png num_bytes: 95.1 KB data_type: Image metadata: Some(MetadataImage(MetadataImage { image: MetadataImageImpl { width: 1798, height: 839, color_space: None } })) mime_type: image/png extension: png chunk_hashes: [234341058283605499288244061100413189728] chunk_type: SingleFile storage_backend: Disk last_commit_id: 74bb3ece2ccfa3f23420ef5c0be84865 last_modified_seconds: 1766177016 last_modified_nanoseconds: 995509200 metadata: Some(MetadataImage(MetadataImage { image: MetadataImageImpl { width: 1798, height: 839, color_space: None } })) ) parent_id: dca3063656d08a4ecdd1644fb64f8de children.len(): 0 [​](https://docs.oxen.ai/getting-started/command-line/debugging#concurrency) Concurrency ------------------------------------------------------------------------------------------- By default, oxen will use up to 8 threads for its parallelized operations (`oxen add`, `oxen push`, etc.). This can be configured via the `OXEN_NUM_THREADS` environment variable. If `OXEN_NUM_THREADS` is set, oxen will instead use that many threads, so long as they are available on the local machine. export OXEN_NUM_THREADS="16" [​](https://docs.oxen.ai/getting-started/command-line/debugging#http-requests) HTTP Requests ----------------------------------------------------------------------------------------------- When uploading or downloading data, if any files fail to transfer, oxen will wait and retry the request. By default, oxen will allow up to 5 retries before cancelling the operation. This can be configured via the enviornment variable `OXEN_NUM_RETRIES` export OXEN_NUM_RETRIES="10" All HTTP requests oxen makes timeout after 120 seconds by default. You can configure this the OXEN\_TIMEOUT\_SECS variable. export OXEN_TIMEOUT_SECS="100" [​](https://docs.oxen.ai/getting-started/command-line/debugging#chunk-size) Chunk Size ----------------------------------------------------------------------------------------- Under the hood, oxen groups files into small files and large files for more efficient transfer in `oxen push`, `oxen workspace add`, etc. Files are considered large if they’re larger than `AVG_CHUNK_SIZE`, which is set to 10 MB by default. This can be configured via the `AVG_CHUNK_SIZE` environment variable export AVG_CHUNK_SIZE="20_000_000" [​](https://docs.oxen.ai/getting-started/command-line/debugging#debug-logs) Debug Logs ----------------------------------------------------------------------------------------- The oxen codebase contains plenty of debug logs, which you can turn on with the RUST\_LOG variable. export RUST_LOG="debug" You can also set RUST\_LOG to `info` or `warn` for more restrictive debug logs [🧹 Maintenance](https://docs.oxen.ai/getting-started/command-line/maintenance) [Introduction](https://docs.oxen.ai/python-api) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Inference API Overview - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/inference-api/overview#content-area) [​](https://docs.oxen.ai/inference-api/overview#what-is-the-inference-api) What is the Inference API? -------------------------------------------------------------------------------------------------------- The Inference API gives you access to hundreds of AI models through a single, consistent interface. Generate text, images, and videos without managing infrastructure or juggling multiple provider SDKs. **Capabilities:** * **Text Generation**: Chat completions, tool calling, vision, structured output * **Image Generation**: Text-to-image, image-to-image editing * **Video Generation**: Text-to-video, image-to-video, reference-to-video, video-to-video editing [​](https://docs.oxen.ai/inference-api/overview#where-to-find-things) Where to find things --------------------------------------------------------------------------------------------- | Looking for… | Go to | | --- | --- | | General API info | [Keep reading below](https://docs.oxen.ai/inference-api/overview#authentication) | | Getting started fast | [Quick Starts](https://docs.oxen.ai/inference-api/overview#quick-starts) | | Endpoint specs and parameters | [API Reference](https://docs.oxen.ai/inference-api/overview#api-reference) | | Running inference with a specific model | [Model API References](https://docs.oxen.ai/inference-api/reference/model-references) | | Model discovery | [Models page](https://www.oxen.ai/ai/models) | [​](https://docs.oxen.ai/inference-api/overview#quick-starts) Quick Starts ----------------------------------------------------------------------------- Chat ---- Text generation in minutes Images ------ Text-to-image in minutes Videos ------ Text-to-video in minutes Async Queue ----------- Generate in background [​](https://docs.oxen.ai/inference-api/overview#api-reference) API Reference ------------------------------------------------------------------------------- Chat Completions ---------------- Text generation, vision, tool calling Image Generation ---------------- Text-to-image generation Image Editing ------------- Edit images with text prompts Video Generation ---------------- Text-to-video, image-to-video, multi-shot Async Queue ----------- Background image/video generation Models ------ List, search, and manage models [​](https://docs.oxen.ai/inference-api/overview#individual-model-api-references) Individual Model API References ------------------------------------------------------------------------------------------------------------------- Browse per-model API references ------------------------------- Sample requests, parameter tables, and workbench links for every model. [​](https://docs.oxen.ai/inference-api/overview#individual-model-walkthroughs) Individual Model Walkthroughs --------------------------------------------------------------------------------------------------------------- Kling O3 Pro: Reference to Video -------------------------------- Multi-shot with references Kling O3 Pro: Video to Video Edit --------------------------------- Text-guided video edits Seedance 2.0: Reference to Video -------------------------------- Mixed-reference video Topaz Starlight Precise 2.5 --------------------------- Upscale and restore to 4K * * * [​](https://docs.oxen.ai/inference-api/overview#authentication) Authentication --------------------------------------------------------------------------------- All requests require a bearer token: curl -H "Authorization: Bearer YOUR_API_KEY" \ https://hub.oxen.ai/api/ai/... Get your API key from your [account settings](https://oxen.ai/settings/profile) . [​](https://docs.oxen.ai/inference-api/overview#base-url) Base URL --------------------------------------------------------------------- All inference endpoints live under: https://hub.oxen.ai/api/ai If you’re using the OpenAI SDK, set the base URL to `https://hub.oxen.ai/api/ai`. The SDK appends `/chat/completions` automatically. [​](https://docs.oxen.ai/inference-api/overview#endpoints) Endpoints ----------------------------------------------------------------------- | Endpoint | Method | Description | | --- | --- | --- | | `/ai/chat/completions` | POST | Text generation (chat, vision, tool use) | | `/ai/images/generate` | POST | Image generation | | `/ai/images/edit` | POST | Image editing | | `/ai/videos/generate` | POST | Video generation | | `/ai/queue` | POST | Async image/video generation | | `/ai/queue` | GET | List generations (active by default, filterable by status) | | `/ai/queue/:generation_id` | GET | Get generation status and result | | `/ai/queue/:generation_id` | DELETE | Cancel a queued generation | | `/ai/models` | GET | List available models | | `/ai/models/:id` | GET | Get model details and parameter schema | | `/ai/models/search` | GET | Search models by name | | `/ai/models/:id/activate` | POST | Activate a custom model deployment | | `/ai/models/:id/deactivate` | POST | Deactivate a custom model deployment | [​](https://docs.oxen.ai/inference-api/overview#common-parameters) Common Parameters --------------------------------------------------------------------------------------- These parameters are accepted across multiple endpoints: | Parameter | Type | Description | | --- | --- | --- | | `model` | string | Required. The model to use (e.g. `claude-sonnet-4-6`, `flux-2-dev`, `kling-video-o3-pro-reference-to-video`). | | `response_format` | string | `"url"` (default) returns a hosted URL. `"b64_json"` returns base64-encoded bytes inline. Supported on image and video endpoints. | | `target_namespace` | string | Namespace to save results and bill to. Defaults to your user. Can be an organization name. | [​](https://docs.oxen.ai/inference-api/overview#discovering-models) Discovering Models ----------------------------------------------------------------------------------------- List all models, optionally filtered by developer: # All models curl -H "Authorization: Bearer $OXEN_API_KEY" \ "https://hub.oxen.ai/api/ai/models" # Search by name curl -H "Authorization: Bearer $OXEN_API_KEY" \ "https://hub.oxen.ai/api/ai/models/search?search=kling" Get full details for a specific model (including its parameter schema): curl -H "Authorization: Bearer $OXEN_API_KEY" \ "https://hub.oxen.ai/api/ai/models/kling-video-o3-pro-reference-to-video" The response includes a `request_schema` field with the complete parameter definitions, types, defaults, and constraints for that model. [​](https://docs.oxen.ai/inference-api/overview#pricing) Pricing ------------------------------------------------------------------- Pricing varies by model: | Method | How it works | Examples | | --- | --- | --- | | `token` | Per input/output token | GPT, Claude, Gemini | | `time` | Per second of compute time | Custom models, Llama, Qwen | | `per_image` | Fixed cost per image | FLUX, DALL-E | | `per_video_output_second` | Cost per second of output video | Kling, Sora | Check the [model detail endpoint](https://docs.oxen.ai/inference-api/reference/models/overview#retrieve-model) for exact pricing. Relevant fields: `input_cost_per_token`, `output_cost_per_token`, `cost_per_image`, `cost_per_second`, `cost_per_second_with_audio`, `cost_per_second_high_res`. [​](https://docs.oxen.ai/inference-api/overview#error-format) Error Format ----------------------------------------------------------------------------- Errors use one of two formats: { "error": { "type": "invalid_params", "title": "Invalid parameters supplied, please check your request and try again.", "detail": "Specific error details" }, "status": "error", "status_message": "invalid_params" } { "error": { "message": "Model not found: bad-model-name" } } Common error types: `unauthenticated`, `invalid_params`, `resource_not_found`, `unknown_error`. Need help? Join our [Discord community](https://discord.com/invite/s3tBEn7Ptg) . [Chat Completions](https://docs.oxen.ai/inference-api/quickstart/chat) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Model Walkthroughs - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/overview#content-area) Walkthroughs go further than the per-model reference pages: they wire together a complete example end-to-end, explain when to use the model, and call out parameters that are easy to miss. Looking for the full request schema? ------------------------------------ Every model has a dedicated API reference with a request builder, sample cURL and Python snippets, and the full parameter table. That’s usually what you want if you just need to make a call. [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/overview#available-walkthroughs) Available walkthroughs ------------------------------------------------------------------------------------------------------------------------------- Kling O3 Pro: Reference to Video -------------------------------- Multi-shot video generation with reference images, per-shot prompts and durations, and optional native audio. Kling O3 Edit: Video to Video ----------------------------- Text-guided video editing with reference images and character/element consistency. Seedance 2.0: Reference to Video -------------------------------- Video from prompt plus reference images, videos, or audio, up to 720p and 15 seconds with synchronized sound. Topaz Starlight Precise 2.5 --------------------------- Restore and upscale video to 1080p, 2K, or 4K with detail-preserving temporal consistency. [Model API References](https://docs.oxen.ai/inference-api/reference/model-references) [Kling O3 Pro: Reference to Video](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/kling_o3_pro_reference_to_video) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # πŸ“ Track Changes - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/getting-started/command-line/track_changes#content-area) The day-to-day Oxen workflow follows the same shape as git: stage what’s changed, commit it, and inspect the history when you need to. [​](https://docs.oxen.ai/getting-started/command-line/track_changes#stage-files) Stage Files ----------------------------------------------------------------------------------------------- Add files to a repository with `oxen add`. This copies the files’ contents to the repository’s version store and stages the changes for commit. You can use absolute paths or paths relative to the repo root. oxen add path/to/file.txt oxen add images/ You can also stage matching files with glob patterns and wildcards. This stages everything that matches the pattern and isn’t excluded by `.oxenignore`. # Adds all paths starting with an 'f' in the images dir oxen add images/f* # Adds everything in the current directory oxen add . `oxen add` handles new, modified, and removed files and directories. Oxen lets you version any data type β€” text, images, audio, video, parquet, etc. β€” in the same repository, and you interact with all of them through the same commands. Under the hood, Oxen stores type-specific [file metadata](https://docs.oxen.ai/concepts/file_metadata) to power richer features. [​](https://docs.oxen.ai/getting-started/command-line/track_changes#view-status) View Status ----------------------------------------------------------------------------------------------- To see what is tracked, staged, modified, removed, or not yet added, use `oxen status`. oxen status Output: On branch main -> e76dd52a4fc13a6f Directories to be committed added: images with added 8108 files Files to be committed: new file: images/000000000042.jpg new file: images/000000000074.jpg new file: images/000000000109.jpg new file: images/000000000307.jpg new file: images/000000000309.jpg new file: images/000000000394.jpg new file: images/000000000400.jpg new file: images/000000000443.jpg new file: images/000000000490.jpg new file: images/000000000575.jpg ... and 8098 others Untracked Directories (use "oxen add ..." to update what will be committed) annotations/ (3 items) Because Oxen is built for large datasets with many files, `status` rolls up directory-level changes and summarizes them. You can paginate through staged files with the `-s` (skip) and `-l` (limit) flags. Run `oxen status --help` for the full list. [​](https://docs.oxen.ai/getting-started/command-line/track_changes#commit-changes) Commit Changes ----------------------------------------------------------------------------------------------------- Once changes are staged, commit them with a message. oxen commit -m "Some informative commit message" This creates a new commit on the current branch. If the repository was previously empty, this also creates the `main` branch. After a commit, a copy of each file’s contents lives in the repository’s version store (by default `.oxen/versions/files`). File and directory metadata are stored in the [Merkle Tree](https://ghost.oxen.ai/merkle-tree-101/) , which mirrors the working directory structure. [​](https://docs.oxen.ai/getting-started/command-line/track_changes#view-history) View History ------------------------------------------------------------------------------------------------- Show the commit history of your current branch with `oxen log`. oxen log Output: commit 6b958e268656b0c5 Author: Ox Date: Fri, 21 Oct 2022 16:08:39 -0700 adding 10,000 training images commit e76dd52a4fc13a6f Author: Ox Date: Fri, 21 Oct 2022 16:05:22 -0700 Initialized Repo πŸ‚ [​](https://docs.oxen.ai/getting-started/command-line/track_changes#view-diffs) View Diffs --------------------------------------------------------------------------------------------- Oxen can compute and display diffs between files using the [oxen diff](https://docs.oxen.ai/concepts/diffs) command. oxen diff dataset.csv This compares `dataset.csv` in the working directory with its version in the HEAD commit. You can also diff different files against each other, files across revisions, or whole revisions against each other. See the [diff concepts page](https://docs.oxen.ai/concepts/diffs) for the full set of options. [​](https://docs.oxen.ai/getting-started/command-line/track_changes#restore-files) Restore Files --------------------------------------------------------------------------------------------------- To revert changes you’ve made to a file in the working directory, use `oxen restore`. This restores the file to its version in the HEAD commit, and works on both modified and deleted files. oxen restore path/to/file.txt You can also restore directories β€” `oxen restore` will recursively restore the files inside. To restore from a specific commit or branch, pass `--source`. oxen restore path/to/file.txt --source COMMIT_ID Like git, you can also unstage files (without changing the working directory) using `--staged`. oxen restore --staged path/to/dir [​](https://docs.oxen.ai/getting-started/command-line/track_changes#remove-files) Remove Files ------------------------------------------------------------------------------------------------- To stage a file to be removed from the next commit, use `oxen rm`. oxen rm path/to/file.txt The file must already be committed for this to work. If you want to remove a file that has not been committed yet, just use your shell’s `rm` command. To recursively remove a directory, use the `-r` flag. oxen rm -r path/to/dir You can also remove entries from the staging area only β€” without deleting the file from the working directory β€” using `--staged`. oxen rm --staged -r path/to/dir [πŸš€ Start a Repository](https://docs.oxen.ai/getting-started/command-line/start_repository) [🌿 Branches & Merging](https://docs.oxen.ai/getting-started/command-line/branches) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Chat Completions - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/inference-api/quickstart/chat#content-area) [​](https://docs.oxen.ai/inference-api/quickstart/chat#overview) Overview ---------------------------------------------------------------------------- Generate text responses from language models using the OpenAI-compatible chat completions API. Supports streaming, vision, tool calling, and structured output. [​](https://docs.oxen.ai/inference-api/quickstart/chat#minimal-example) Minimal Example ------------------------------------------------------------------------------------------ Python cURL from openai import OpenAI client = OpenAI( base_url="https://hub.oxen.ai/api/ai", api_key="YOUR_API_KEY", ) response = client.chat.completions.create( model="claude-sonnet-4-6", messages=[{"role": "user", "content": "What is Oxen.ai?"}], max_tokens=200, ) print(response.choices[0].message.content) [​](https://docs.oxen.ai/inference-api/quickstart/chat#with-streaming) With Streaming ---------------------------------------------------------------------------------------- Python cURL from openai import OpenAI client = OpenAI( base_url="https://hub.oxen.ai/api/ai", api_key="YOUR_API_KEY", ) stream = client.chat.completions.create( model="gemini-3-1-flash-lite-preview", messages=[{"role": "user", "content": "Write a haiku about data"}], stream=True, ) for chunk in stream: content = chunk.choices[0].delta.content if content: print(content, end="", flush=True) print() [​](https://docs.oxen.ai/inference-api/quickstart/chat#what%E2%80%99s-next) What’s Next ------------------------------------------------------------------------------------------ * [Chat Completions Reference](https://docs.oxen.ai/inference-api/reference/chat_completions) for the full parameter list * [Image Generation Quick Start](https://docs.oxen.ai/inference-api/quickstart/image-generation) to generate images * [Video Generation Quick Start](https://docs.oxen.ai/inference-api/quickstart/video-generation) to generate videos [Inference API Overview](https://docs.oxen.ai/inference-api/overview) [Image Generation](https://docs.oxen.ai/inference-api/quickstart/image-generation) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # πŸ—‚οΈ Workspaces - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/getting-started/command-line/workspaces#content-area) A workspace lets you stage changes against a remote branch without first copying its files to a local repository. This makes it ideal for bulk imports, automation, and any case where you don’t need a local working copy. For the conceptual overview, see [Workspaces](https://docs.oxen.ai/getting-started/workspaces) . For the Python interface, see [`python-api/workspace`](https://docs.oxen.ai/python-api/workspace) . [​](https://docs.oxen.ai/getting-started/command-line/workspaces#create-a-workspace) Create a Workspace ---------------------------------------------------------------------------------------------------------- Create a workspace on the current branch with `oxen workspace create`. oxen workspace create This returns a workspace ID you’ll use for subsequent commands. [​](https://docs.oxen.ai/getting-started/command-line/workspaces#stage-files-in-a-workspace) Stage Files in a Workspace -------------------------------------------------------------------------------------------------------------------------- Add files to the workspace with `oxen workspace add`. The file contents are uploaded directly to the remote and staged for commit. oxen workspace add images --workspace-id 117abd2d-3363-497d-ac93-a5cb3c280234 [​](https://docs.oxen.ai/getting-started/command-line/workspaces#commit-a-workspace) Commit a Workspace ---------------------------------------------------------------------------------------------------------- Once your changes are staged, commit them with `oxen workspace commit`. oxen workspace commit -m "Uploading Images" --workspace-id 117abd2d-3363-497d-ac93-a5cb3c280234 The commit lands on the remote branch directly β€” no local push step required. [πŸ”„ Sync with a Remote](https://docs.oxen.ai/getting-started/command-line/sync_remote) [🧹 Maintenance](https://docs.oxen.ai/getting-started/command-line/maintenance) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # πŸ’Ύ Version Control - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/examples/data/versioning#content-area) Oxen’s [open source data version control system](https://github.com/Oxen-AI/Oxen) shines at workflows and data sizes where git or git-lfs fall short. The interface is inspired by git, so that it is easy to learn for engineers, but has a few core differences. Oxen is built from the ground up to handle large datasets with many files or large csvs, parquet files, or other large binary blobs like model weights, videos or 3D assets. The developer tools come with a [CLI](https://docs.oxen.ai/examples/data/versioning#versioning-101) , [HTTP APIs](https://docs.oxen.ai/http-api) , and [Python library](https://docs.oxen.ai/python-api) to make it easy to integrate into your workflow. [​](https://docs.oxen.ai/examples/data/versioning#versioning-101) Versioning 101 ----------------------------------------------------------------------------------- On the surface, `oxen` looks a lot like `git`. Users can add, commit, data locally then push to a remote server. Similar to git, by default oxen will create a local copy of the data on your machine in your `.oxen` directory before pushing to the remote server. CLI Python oxen init oxen add lotsa_data/ oxen commit -m "adding too much data for git" # Create the remote on hub.oxen.ai (or `oxen create-remote --name /`) # and wire it up before pushing: oxen config --set-remote origin https://hub.oxen.ai// oxen push origin main The first main difference is that `oxen` comes with a remote `oxen-server` that user’s can sync data to. This server also allows you to upload data directly without making local copies. CLI SYNC_DIR=/path/to/data oxen-server start -p 3000 -i 0.0.0.0 Say we had already pushed a large dataset to the remote server, and simply wanted to to add a file to a large dataset like ImageNet with [1 Million Files](https://docs.oxen.ai/examples/data/performance) . You do not want to wait to clone all the files locally just to add yours to the server. Python CLI from oxen import RemoteRepo # Connect to the remote client repo = RemoteRepo("my-username/my-repo") # Add the images to the workspace without committing. # Pass `dst=` so the files land under `images/` on the remote. repo.add("images/image_1_000_001.png", dst="images/") repo.add("images/image_1_000_002.png", dst="images/") # Commit the remote changes repo.commit("Adding the 1,000,001st image to the dataset") This is just one example of how Oxen.ai enables a more developer friendly workflow for large datasets. There are also optimizations under the hood such as parallel file transfer, scalable merkle trees, and data deduplication to make Oxen go brrr (or mooo?). [​](https://docs.oxen.ai/examples/data/versioning#interfaces) Interfaces --------------------------------------------------------------------------- The server exposes a REST API that can be used to interact with data. Oxen.ai’s clients include a [command line interface](https://docs.oxen.ai/getting-started/command-line/start_repository) , as well as bindings for [Rust](https://github.com/Oxen-AI/Oxen) πŸ¦€, [Python](https://docs.oxen.ai/python-api) 🐍, and [HTTP interfaces](https://docs.oxen.ai/http-api) 🌎 to make it easy to integrate into your workflow. [​](https://docs.oxen.ai/examples/data/versioning#installation) Installation ------------------------------------------------------------------------------- Oxen makes versioning your datasets as easy as versioning your code. You can install through homebrew or pip or from our [releases page](https://github.com/Oxen-AI/Oxen/releases) . CLI Python brew install oxen [​](https://docs.oxen.ai/examples/data/versioning#remote-workflow) Remote Workflow ------------------------------------------------------------------------------------- Centralized version control systems like Oxen.ai allow you to have remote first workflows where you do not need to have a fully copy of the data on your local machine. Decentralized version control systems like git by default duplicate all the data to every node in your network. ![Oxen Remote and Local Workflow](https://mintcdn.com/oxenai/VndlMSXTb9YuU-Wl/images/versioning/Centralized-vs-Decentralized-VCS.png?w=2500&fit=max&auto=format&n=VndlMSXTb9YuU-Wl&q=85&s=17e6424856164e2e86b47171781fe377) While the decentralized nature of git makes it easy to maintain full copies of the history across many machines, this is not practical for large datasets. Oxen was designed from the ground up to be able to seamlessly switch between local and remote (centralized) workflows. Only clone what you need, and contribute back to the remote repository when you are done. ### [​](https://docs.oxen.ai/examples/data/versioning#create-a-remote-repository) Create a Remote Repository If you do not already have a remote repository, you can create one with a single `README.md` and initial commit so it is immediately cloneable. Python CLI cURL from oxen import RemoteRepo # RemoteRepo.create is an instance method β€” construct first, then call create. # The Python client adds a README.md and initial commit by default. repo = RemoteRepo("my-user/my-repo-name") repo.create() If you want to create an empty repository β€” with no `README.md` and no initial commit β€” pass `empty=True` from Python, or simply omit `--add_readme` from the CLI. Python CLI cURL from oxen import RemoteRepo repo = RemoteRepo("my-user/my-repo-name") repo.create(empty=True) The reason you may want to start with an empty repository is if you already started a local repository and want to push it to the remote repository. This local repository already has a commit history. When pushing to a remote, commit histories must match. Hence we need to start with an empty remote repository without any commits if we want to push a local repository with a commit history. ### [​](https://docs.oxen.ai/examples/data/versioning#add-files) Add Files You can add files to the remote repository by passing the path to the file and the destination directory. This will upload the file to the remote repository and stage it for commit. Python CLI cURL from oxen import RemoteRepo repo = RemoteRepo("ox/CatDogBBox") repo.add("images/000000002754.jpg", dst="images/") ### [​](https://docs.oxen.ai/examples/data/versioning#commit-changes) Commit Changes You can commit changes to the remote repository by passing a message. Python CLI cURL repo.commit("Adding the 1,000,001st image to the dataset") ### [​](https://docs.oxen.ai/examples/data/versioning#file-exploration) File Exploration To see the files in the remote repository you can use `ls`. Python cURL from oxen import RemoteRepo repo = RemoteRepo("ox/CatDogBBox") print(repo.ls()) To view a specific directory you can pass the directory name to the `ls` method. Note: the directories are paginated so you will need to use the `page_num` parameter to view the next page of results. There are also `total_pages`, `page_number`, and `total_entries` attributes that give you information about the pagination. Python cURL from oxen import RemoteRepo repo = RemoteRepo("ox/CatDogBBox") images_results = repo.ls("images", page_num=1, page_size=10) print(images_results) print(images_results.total_pages) print(images_results.page_number) print(images_results.total_entries) ### [​](https://docs.oxen.ai/examples/data/versioning#downloading-data) Downloading Data You can download individual files and folders if you do not need the entire data repository for your job. CLI Python cURL oxen download ox/CatDogBBox annotations/test.csv ### [​](https://docs.oxen.ai/examples/data/versioning#checkout-a-branch) Checkout a Branch If you have a data on a separate branch that you want to view you can checkout a branch by passing the branch name to the `checkout` method. Python CLI cURL from oxen import RemoteRepo repo = RemoteRepo("ox/CatDogBBox") repo.checkout("my-branch-name") print(repo.ls()) ### [​](https://docs.oxen.ai/examples/data/versioning#create-a-new-branch) Create a New Branch The `checkout` method also allows you to create a new branch if the branch does not exist. Python CLI cURL from oxen import RemoteRepo repo = RemoteRepo("ox/CatDogBBox") repo.checkout("my-new-branch-name", create=True) print(repo.ls()) ### [​](https://docs.oxen.ai/examples/data/versioning#view-branches) View Branches To see all the branches in the remote repository you can use the `branches` method. Python CLI cURL from oxen import RemoteRepo repo = RemoteRepo("ox/CatDogBBox") print(repo.branches()) ### [​](https://docs.oxen.ai/examples/data/versioning#workspaces) Workspaces Under the hood, the way that we enable remote collaboration is through a concept called a [workspace](https://docs.oxen.ai/getting-started/workspaces) . A workspace can be thought of as an uncommitted working directory that is stored on the server. Just like you can `add` files before committing locally, you can `add` files to a workspace on the remote server before committing. This allows you to build up a set of changes remotely before committing them in bulk. Python CLI cURL from oxen import RemoteRepo from oxen import Workspace repo = RemoteRepo("ox/CatDogBBox") # The second positional arg to Workspace is the BRANCH the workspace is tied # to. The optional `workspace_name` gives the workspace a stable identifier # so you can reattach to it later by name. workspace = Workspace(repo, "main", workspace_name="add-images") workspace.add("/path/to/image.png") status = workspace.status() print(status.added_files()) # Commits land on the workspace's branch β€” "main" in this example. workspace.commit("Adding the 1,000,001st image to the dataset") The `RemoteRepo.add` method is a shortcut for creating a workspace and adding files to it. It creates a ephemeral workspace and adds the files to it, and deletes the workspace after committing. To learn more about workspaces, check out the [workspaces documentation](https://docs.oxen.ai/getting-started/workspaces) . ### [​](https://docs.oxen.ai/examples/data/versioning#clone-a-remote-repository) Clone a Remote Repository Remote repositories are identified by a remote URL. This is the URL that you can use to clone the repository. Python CLI cURL from oxen import RemoteRepo remote_repo = RemoteRepo("my-user/my-repo-name") remote_repo.create(empty=True) # `url` is a property, not a method β€” no parentheses. print(remote_repo.url) You can use this URL to clone the repository. Python # Local Repository from oxen import Repo from oxen import RemoteRepo remote_repo = RemoteRepo("my-user/my-repo-name") remote_repo.create(empty=True) repo_url = remote_repo.url local_repo = Repo("/path/to/local/repo") local_repo.clone(repo_url) Or you can set the remote of an existing local repository to point at the remote repository. Python from oxen import Repo from oxen import RemoteRepo remote_repo = RemoteRepo("my-user/my-repo-name") remote_repo.create(empty=True) local_repo = Repo("/path/to/local/repo") local_repo.set_remote("origin", remote_repo.url) [​](https://docs.oxen.ai/examples/data/versioning#local-workflow) Local Workflow ----------------------------------------------------------------------------------- Local workflow looks a lot like git. The downside is that you have to duplicate all the data locally. The good news is that oxen is much faster than git for large files and repositories. ### [​](https://docs.oxen.ai/examples/data/versioning#initialize-user) Initialize User Each change you make will be associated with a name and email. Set them before you get started so you know who changed what. The user data is saved by default in `~/.config/oxen/user_config.toml`. CLI Python oxen config --name "Bessie Oxington" --email "bessie@yourcomany.com" ### [​](https://docs.oxen.ai/examples/data/versioning#create-repository) Create Repository Initialize your first Oxen repository, and commit the first version of your data. CLI Python # Initialize the repository oxen init # Write data to a file printf '%s\n' 'name,age' 'bob,12' 'jane,13' > people.csv # Stage the data for commit oxen add people.csv # Commit the changes with a message oxen commit -m "Adding my data" ### [​](https://docs.oxen.ai/examples/data/versioning#create-branch) Create Branch It is good practice to create a new branch for changes you make to your data. This will allow you to easily compare the parallel versions of your data over time. CLI Python # Checkout a branch named `modify-data` oxen checkout -b modify-data # Overwrite data in existing file printf '%s\n' 'name,age' 'bob,12' 'jane,13' 'joe,14' > people.csv ### [​](https://docs.oxen.ai/examples/data/versioning#delete-branch) Delete Branch Once finished with a branch, you can delete it. CLI Python cURL # Checkout main branch locally oxen checkout main # Delete 'other_branch' locally oxen branch -d new_branch # may need -D if branch is not merged into main # Delete branch in remote repo oxen push origin --delete new_branch ### [​](https://docs.oxen.ai/examples/data/versioning#status) Status Check the current state of your local repository by using `oxen status`. Instead of printing out every file that was added/modified/removed (which is unsustainable for large repositories), `oxen` summarizes the changes and lets you page through them. CLI Python oxen status ### [​](https://docs.oxen.ai/examples/data/versioning#restore-changes) Restore Changes If you are not happy with the changes you made to your data, you can restore them to the previous commit with the `oxen restore` command. CLI oxen restore --source people.csv ### [​](https://docs.oxen.ai/examples/data/versioning#commit-changes-2) Commit Changes Once you are happy with the changes you have made to your data, you can commit them to the repository with a new message. CLI Python oxen add people.csv oxen commit -m "Adding Joe to the dataset" ### [​](https://docs.oxen.ai/examples/data/versioning#view-commit-history) View Commit History To see the commit history of your repository, you can use the `oxen log` command. CLI Python cURL oxen log ### [​](https://docs.oxen.ai/examples/data/versioning#checkout-main-branch) Checkout Main Branch Once you are done making changes to your data, you can return to the main branch with the `oxen checkout` command. Never fear, the file now has now been reverted to the inital commit again, but your changes will be saved in the branch you created. CLI Python oxen checkout main ### [​](https://docs.oxen.ai/examples/data/versioning#list-branches) List Branches To see the branches in your repository, you can use the `oxen branch` command. CLI Python cURL oxen branch ### [​](https://docs.oxen.ai/examples/data/versioning#push-data) Push Data Once your data has been committed locally, you can sync it to the `oxen-server`. Oxen.ai has a web hub that allows you to collaborate on your data in the cloud. You can create a free account at [https://oxen.ai](https://oxen.ai/) . CLI Python # Go create repo at https://oxen.ai # ... oxen config --set-remote origin https://hub.oxen.ai// oxen config --auth hub.oxen.ai oxen push origin main # to push your other branch simply change the branch name from `main` to `modify-data` To learn more about setting up authentication and authorization, read our [security documentation here](https://docs.oxen.ai/getting-started/auth) . ### [​](https://docs.oxen.ai/examples/data/versioning#clone-data) Clone Data Clone your data faster than ever before. Oxen has been optimized to the core to make pulling large datasets as fast as possible. CLI Python oxen clone https://hub.oxen.ai/ox/CatDogBBox ### [​](https://docs.oxen.ai/examples/data/versioning#pull-changes) Pull Changes Only pull the changes you need. Oxen will only pull the files that have changed since the last time you pulled. CLI Python oxen pull origin main [πŸ“– Overview](https://docs.oxen.ai/getting-started/data) [πŸ“Š Datasets](https://docs.oxen.ai/examples/data/datasets) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Image Generation - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/inference-api/reference/image_generation#content-area) [​](https://docs.oxen.ai/inference-api/reference/image_generation#endpoint) Endpoint --------------------------------------------------------------------------------------- POST /api/ai/images/generate Generates images synchronously. The request blocks until the image is ready (typically 5-30 seconds depending on the model). [​](https://docs.oxen.ai/inference-api/reference/image_generation#request-parameters) Request Parameters ----------------------------------------------------------------------------------------------------------- | Parameter | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `model` | string | **yes** | β€” | Image model name (e.g. `black-forest-labs-flux-2-klein-4b`, `flux-2-dev`) | | `prompt` | string | **yes** | β€” | Text description of the image to generate. | | `response_format` | string | no | `"url"` | `"url"` returns a hosted URL. `"b64_json"` returns base64-encoded image bytes inline. | | `target_namespace` | string | no | current user | Namespace to save results and bill to. Can be an organization name. | | `aspect_ratio` | string | no | β€” | Aspect ratio (e.g. `"1:1"`, `"16:9"`, `"9:16"`, `"4:3"`, `"3:4"`). | | `num_inference_steps` | integer | no | β€” | Number of denoising steps. | | `seed` | integer | no | β€” | Reproducibility seed. | Available parameters vary by model. Use the [model detail endpoint](https://docs.oxen.ai/inference-api/reference/models/overview#retrieve-model) (`GET /api/ai/models/:id`) to see the `request_schema` for model-specific parameters. [​](https://docs.oxen.ai/inference-api/reference/image_generation#examples) Examples --------------------------------------------------------------------------------------- ### [​](https://docs.oxen.ai/inference-api/reference/image_generation#basic-generation) Basic generation Python cURL import requests response = requests.post( "https://hub.oxen.ai/api/ai/images/generate", headers={ "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, json={ "model": "black-forest-labs-flux-2-klein-4b", "prompt": "A red cube on a white background", "aspect_ratio": "1:1", "seed": 42, }, ) data = response.json() print("Image URL:", data["images"][0]["url"]) ### [​](https://docs.oxen.ai/inference-api/reference/image_generation#response-response_format-url) Response (`response_format: "url"`) { "model": "black-forest-labs-flux-2-klein-4b", "created": 1775090372, "images": [\ {\ "url": "https://hub.oxen.ai/api/repos/.../files/.../image.png?..."\ }\ ] } The URL is a temporary link that expires after a period of time. ### [​](https://docs.oxen.ai/inference-api/reference/image_generation#response-response_format-b64_json) Response (`response_format: "b64_json"`) { "model": "black-forest-labs-flux-2-klein-4b", "created": 1775090372, "images": [\ {\ "b64_json": ""\ }\ ] } [​](https://docs.oxen.ai/inference-api/reference/image_generation#errors) Errors ----------------------------------------------------------------------------------- | Condition | Error | | --- | --- | | No prompt | `"Prompt cannot be empty"` | | Model not found | `"Model not found: "` | [Chat Completions](https://docs.oxen.ai/inference-api/reference/chat_completions) [Image Editing](https://docs.oxen.ai/inference-api/reference/image_editing) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Async Queue - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/inference-api/quickstart/async-queue#content-area) [​](https://docs.oxen.ai/inference-api/quickstart/async-queue#overview) Overview ----------------------------------------------------------------------------------- Video generation can take minutes. The async queue returns immediately with a generation ID so you can avoid long-lived HTTP connections, run generations in parallel, and build progress-tracking UIs. You can either poll the queue or use SSE to receive events when generations complete. [​](https://docs.oxen.ai/inference-api/quickstart/async-queue#enqueue-a-job) Enqueue a Job --------------------------------------------------------------------------------------------- Python cURL import requests API_KEY = "YOUR_API_KEY" HEADERS = { "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json", } response = requests.post( "https://hub.oxen.ai/api/ai/queue", headers=HEADERS, json={ "model": "kling-video-v2-6-pro-text-to-video", "prompt": "A sunset timelapse over the ocean", "duration": 5, }, ) generations = response.json()["generations"] print(f"Enqueued {len(generations)} generation(s)") for g in generations: print(g["generation_id"], g["status"]) [​](https://docs.oxen.ai/inference-api/quickstart/async-queue#poll-until-done) Poll Until Done ------------------------------------------------------------------------------------------------- Poll a generation by ID until its `status` reaches a terminal value (`succeeded`, `failed`, or `cancelled`). The response includes `result_url` on success and `error_message` on failure. Python cURL import time generation_id = generations[0]["generation_id"] while True: data = requests.get( f"https://hub.oxen.ai/api/ai/queue/{generation_id}", headers=HEADERS, ).json() print(f"Status: {data['status']}") if data["status"] in {"succeeded", "failed", "cancelled"}: break time.sleep(10) if data["status"] == "succeeded": print(f"Done! Result: {data['result_url']}") else: print(f"Generation {data['status']}: {data.get('error_message')}") You can also list all active generations with `GET /ai/queue` to see how many are still in progress: curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://hub.oxen.ai/api/ai/queue?model=kling-video-v2-6-pro-text-to-video" [​](https://docs.oxen.ai/inference-api/quickstart/async-queue#fetch-a-single-job) Fetch a Single Job ------------------------------------------------------------------------------------------------------- Use the generation ID to get a specific job’s full status, including `result_url` on success: curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://hub.oxen.ai/api/ai/queue/GENERATION_ID" [​](https://docs.oxen.ai/inference-api/quickstart/async-queue#what%E2%80%99s-next) What’s Next ------------------------------------------------------------------------------------------------- * [Async Queue Reference](https://docs.oxen.ai/inference-api/reference/async_queue) for the full parameter list, polling details, and cancellation * [Video Generation Quick Start](https://docs.oxen.ai/inference-api/quickstart/video-generation) for the synchronous counterpart * [Model API References](https://docs.oxen.ai/inference-api/reference/model-references) for per-model parameters you can pass through the queue [Video Generation](https://docs.oxen.ai/inference-api/quickstart/video-generation) [Chat Completions](https://docs.oxen.ai/inference-api/reference/chat_completions) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Image Editing - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/inference-api/reference/image_editing#content-area) [​](https://docs.oxen.ai/inference-api/reference/image_editing#endpoint) Endpoint ------------------------------------------------------------------------------------ POST /api/ai/images/edit Edit an existing image using a text prompt. The request blocks until the edited image is ready. [​](https://docs.oxen.ai/inference-api/reference/image_editing#request-parameters) Request Parameters -------------------------------------------------------------------------------------------------------- | Parameter | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `model` | string | **yes** | β€” | Image editing model (e.g. `qwen-image-edit`, `nano-banana-2-edit`, `xai-grok-imagine-image-edit`) | | `prompt` | string | **yes** | β€” | Description of the edit to apply. | | `input_image` | string/array | **yes** | β€” | URL(s) of the image to edit. Some models accept an array; see [per-model reference](https://docs.oxen.ai/inference-api/reference/model-references)
. | | `response_format` | string | no | `"url"` | `"url"` returns a hosted URL. `"b64_json"` returns base64-encoded image bytes inline. | | `target_namespace` | string | no | current user | Namespace to save results and bill to. Can be an organization name. | [​](https://docs.oxen.ai/inference-api/reference/image_editing#examples) Examples ------------------------------------------------------------------------------------ ### [​](https://docs.oxen.ai/inference-api/reference/image_editing#basic-edit) Basic edit Python cURL import requests response = requests.post( "https://hub.oxen.ai/api/ai/images/edit", headers={ "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, json={ "model": "qwen-image-edit", "prompt": "Make the background blue", "input_image": "https://example.com/my-photo.jpg", }, ) data = response.json() print("Image URL:", data["images"][0]["url"]) ### [​](https://docs.oxen.ai/inference-api/reference/image_editing#multi-image-input) Multi-image input Some models accept an array of URLs in `input_image`. Consult the per-model reference for how each model uses them: Python cURL import requests response = requests.post( "https://hub.oxen.ai/api/ai/images/edit", headers={ "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, json={ "model": "gpt-image-2-edit", "prompt": "Combine these references into a single scene", "input_image": [\ "https://example.com/reference-a.png",\ "https://example.com/reference-b.png",\ ], }, ) Whether a model accepts a single image or an array of images is part of its schema. See each model’s [API reference](https://docs.oxen.ai/inference-api/reference/model-references) for the exact type. ### [​](https://docs.oxen.ai/inference-api/reference/image_editing#response) Response Same format as `/ai/images/generate`: { "model": "qwen-image-edit", "created": 1775090400, "images": [\ {\ "url": "https://hub.oxen.ai/api/repos/.../files/.../image.png?..."\ }\ ] } [​](https://docs.oxen.ai/inference-api/reference/image_editing#errors) Errors -------------------------------------------------------------------------------- | Condition | Error | | --- | --- | | Image URL not accessible | `"... 403 Client Error: Forbidden for url: ..."` | | Model not found | `"Model not found: "` | The `input_image` URL must be publicly downloadable. URLs that require authentication or block automated access will fail. Data URIs (`data:image/...;base64,...`) work as an alternative but aren’t recommended for production. [Image Generation](https://docs.oxen.ai/inference-api/reference/image_generation) [Video Generation](https://docs.oxen.ai/inference-api/reference/video_generation) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Fine-Tuning Models on Oxen.ai - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/getting-started/fine-tuning#content-area) Simply [upload your data](https://docs.oxen.ai/examples/data/datasets) , and we will provision GPU infrastructure and run the fine-tune. When it’s done, Oxen.ai will save the fine-tuned model weights directly to your repository, and we spin down the GPU for you. No worrying about run away costs or having to manage your own infrastructure. Once the fine-tuning process is complete, you can deploy your model to a dedicated endpoint and use the [inference endpoints](https://docs.oxen.ai/getting-started/inference) to integrate it into your application. ![Fine-Tuning Ox](https://mintcdn.com/oxenai/Zz1r0EaHSepwL757/images/fine_tuning/bloxy-fine-tuning.png?w=2500&fit=max&auto=format&n=Zz1r0EaHSepwL757&q=85&s=0e960f33a08d7df0a3c719884902d5b8) Oxen.ai automatically [versions](https://docs.oxen.ai/examples/data/versioning) and manages the raw model weights and datasets, so that you can always track the data that was used to train the model, or download the model to run locally. [​](https://docs.oxen.ai/getting-started/fine-tuning#why-fine-tune) Why Fine-Tune? ------------------------------------------------------------------------------------- Fine-tuning is a great tool to reach for when basic prompting and context engineering fall short. You may need to fine-tune when: * **Quality** is critical and the model isn’t consistently producing correct outputs. * **Proprietary Data** gives you a unique advantage that generic models can’t capture. * **Latency** is a deal breaker and you need real-time responses. * **Throughput** limitations are bottlenecking your application’s scalability. * **Ownership** of the model is important and you want to control your own destiny. * **Cost** if a foundation model is too expensive for your use case or you want to deploy a smaller model to the edge. With Oxen.ai, we make it easy to automate the fine-tuning process of LLMs on your own data. [​](https://docs.oxen.ai/getting-started/fine-tuning#modalities) Modalities ------------------------------------------------------------------------------ Oxen.ai supports many data types and tasks for fine-tuning. Text Generation --------------- Fine-tune a model to take a user input as text and generate a single response as text. Chat Completions ---------------- Fine-tune a model on chat messages to have a conversation with a user. Image Generation ---------------- Fine-tune a model to go from text descriptions to images. Image Editing ------------- Fine-tune a model to take a prompt and a reference image and generate a new image. Video Generation ---------------- Fine-tune a model to take in a prompt and generate a video. [​](https://docs.oxen.ai/getting-started/fine-tuning#start-by-uploading-a-dataset) Start by Uploading a Dataset ------------------------------------------------------------------------------------------------------------------ To get started, you’ll need to create a new repository on Oxen.ai. Once you’ve created a repository, you can upload your data. The dataset can be in any tabular format including `csv`, `jsonl`, or `parquet`. ![Fine-Tuning Dataset Upload](https://mintcdn.com/oxenai/T4_0EQB1ENVXiGMM/images/fine_tuning/fine-tune-upload-file.png?w=2500&fit=max&auto=format&n=T4_0EQB1ENVXiGMM&q=85&s=87e8ae35fec43c13d7a3d9d949c9dcf9) Once you have your dataset uploaded, you can query, explore, and make sure that the data is high quality before kicking off the fine-tuning process. Your model will only be as good as the data you train it on. ![Fine-Tuning Dataset](https://mintcdn.com/oxenai/GvHCMKbbr_BpHEwk/images/fine_tuning/fine-tune-dataset.png?w=2500&fit=max&auto=format&n=GvHCMKbbr_BpHEwk&q=85&s=cac4c818aa76bc0623d0e8518b6bf854) When you feel confident that your dataset is ready, use the β€œActions” button to select the model you want to fine-tune. ![Fine-Tuning Dataset](https://mintcdn.com/oxenai/GvHCMKbbr_BpHEwk/images/fine_tuning/fine-tune-actions.png?w=2500&fit=max&auto=format&n=GvHCMKbbr_BpHEwk&q=85&s=847da8291ea396398b8aead8cf5f2942) [​](https://docs.oxen.ai/getting-started/fine-tuning#selecting-a-model) Selecting a Model -------------------------------------------------------------------------------------------- This will take you to a form where you can select the model you want to fine-tune and the columns you want to use for the fine-tuning process. We support fine-tuning for [text generation](https://docs.oxen.ai/examples/fine-tuning/text_generation) , [image generation](https://docs.oxen.ai/examples/fine-tuning/image_generation) , [image editing](https://docs.oxen.ai/examples/fine-tuning/image_editing) , and [video generation](https://docs.oxen.ai/examples/fine-tuning/video_generation) with a variety of models. ![Fine-Tuning Model Selection](https://mintcdn.com/oxenai/T4_0EQB1ENVXiGMM/images/fine_tuning/fine-tune-model-selection.png?w=2500&fit=max&auto=format&n=T4_0EQB1ENVXiGMM&q=85&s=ebb2aeb42dae86cd980d00605d79a78b) If you want support for any specific models, data formats, training methods contact us at [hello@oxen.ai](mailto:hello@oxen.ai) and we are happy to help you get started. We are actively working on support for new models and distributed training. [​](https://docs.oxen.ai/getting-started/fine-tuning#monitoring-the-fine-tune) Monitoring the Fine-Tune ---------------------------------------------------------------------------------------------------------- Once you have started the fine-tuning process, you can monitor its progress. The dashboard will show you loss over time and token accuracy processed. ![Fine-Tuning Monitoring](https://mintcdn.com/oxenai/GvHCMKbbr_BpHEwk/images/fine_tuning/fine-tune-loss.png?w=2500&fit=max&auto=format&n=GvHCMKbbr_BpHEwk&q=85&s=0eccd01e926eaa0294c0f3603d634302) If you are fine-tuning an [image](https://docs.oxen.ai/examples/fine-tuning/image_generation) or [video](https://docs.oxen.ai/examples/fine-tuning/video_generation) generation model, you can view the generated images or videos in the β€œSamples” tab to get a feel for the model’s performance. ![Fine-Tuning Samples](https://mintcdn.com/oxenai/T4_0EQB1ENVXiGMM/images/fine_tuning/fine-tune-samples.png?w=2500&fit=max&auto=format&n=T4_0EQB1ENVXiGMM&q=85&s=e22bf3b328e4d9f47391acc9efffd3dd) Click on the β€œInfo” tab to see the fine-tuning configuration and all the hyper-parameters used. This will include a link to the [dataset version](https://docs.oxen.ai/examples/data/versioning) you used and the raw model weights for downloading and running locally. ![Fine-Tuning Samples](https://mintcdn.com/oxenai/GvHCMKbbr_BpHEwk/images/fine_tuning/fine-tune-info-tab.png?w=2500&fit=max&auto=format&n=GvHCMKbbr_BpHEwk&q=85&s=0a25a1dd95104994d3f9ee2a2b33dabd) [​](https://docs.oxen.ai/getting-started/fine-tuning#deploying-the-model) Deploying the Model ------------------------------------------------------------------------------------------------ Once the model is fine-tuned, you can deploy it to a dedicated endpoint or in the playground. This will give you a `/ai/chat/completions` api and a playground that you can use to test out the model. Start by using the β€œplaygroud” button. ![Fine-Tuning Configuration](https://mintcdn.com/oxenai/D1rpfmXbqvsK8ph0/images/fine_tuning/fine-tune-deploy-model.png?w=2500&fit=max&auto=format&n=D1rpfmXbqvsK8ph0&q=85&s=bf9a1b3fbf5e93c05714413ee9fbdb2c) if the model is not loaded you’ll see an β€œinactive” button on the top right of the playgroud. ![Fine-Tuning Configuration](https://mintcdn.com/oxenai/D1rpfmXbqvsK8ph0/images/fine_tuning/fine-tune-deploy-model-inactive.png?w=2500&fit=max&auto=format&n=D1rpfmXbqvsK8ph0&q=85&s=e5e97edb8b53e69f8b90fae573e64c47) use the activate button to load the model. ![Fine-Tuning Configuration](https://mintcdn.com/oxenai/D1rpfmXbqvsK8ph0/images/fine_tuning/fine-tune-deploy-model-active.png?w=2500&fit=max&auto=format&n=D1rpfmXbqvsK8ph0&q=85&s=036964ec363e194d5e6ce8419f4b9821) To use the API Swap out the model name with the name of the model you want to use. curl https://hub.oxen.ai/api/ai/chat/completions -H "Content-Type: application/json" -d '{ "model":"oxen:my-model-name", "messages": [{"role": "user", "content": "What is the best name for a friendly ox?"}], }' [​](https://docs.oxen.ai/getting-started/fine-tuning#using-the-model) Using the Model ---------------------------------------------------------------------------------------- Once the model is deployed, you can also chat with it using the Oxen.ai chat interface at the playgroud. Learn more about the [chat interface here](https://docs.oxen.ai/getting-started/inference) . ![Chatting with the Model](https://mintcdn.com/oxenai/s_o9ZlhOEkYJf27_/images/chat/chat_window_powerful_coffee_chimpanzee.png?w=2500&fit=max&auto=format&n=s_o9ZlhOEkYJf27_&q=85&s=b49d24239ebfe529515e682acefdc2a7) For image and video generation, you can use the [playground](https://oxen.ai/ai/models) to generate images and videos. ![Chatting with the Model](https://mintcdn.com/oxenai/T4_0EQB1ENVXiGMM/images/fine_tuning/model-playground.png?w=2500&fit=max&auto=format&n=T4_0EQB1ENVXiGMM&q=85&s=31b875aa360a0b801cc94ed589fbba9b) [​](https://docs.oxen.ai/getting-started/fine-tuning#downloading-the-model) Downloading the Model ---------------------------------------------------------------------------------------------------- If you want access to the raw model weights, you can download them from the repository using the Oxen.ai [Python Library](https://docs.oxen.ai/python-api) or the [CLI](https://docs.oxen.ai/getting-started/command-line/start_repository) . Follow the instructions for [installing oxen](https://docs.oxen.ai/getting-started/install) if you haven’t already. CLI Python oxen download my-username/my-repo models/ox-artistic-cyan-elephant/model.safetensors --revision models/ox-artistic-cyan-elephant ![Fine-Tuning Configuration](https://mintcdn.com/oxenai/T4_0EQB1ENVXiGMM/images/fine_tuning/fine-tune-model-weights.png?w=2500&fit=max&auto=format&n=T4_0EQB1ENVXiGMM&q=85&s=43f4f16c2f7e8f387ba999e3313dca25) [​](https://docs.oxen.ai/getting-started/fine-tuning#need-custom-infrastructure) Need Custom Infrastructure? --------------------------------------------------------------------------------------------------------------- If you need custom or private deployments in your own VPC or want to train a larger model on distributed infrastructure, contact us at [hello@oxen.ai](mailto:hello@oxen.ai) and we can give you a custom deployment. [🏷️ File Metadata](https://docs.oxen.ai/concepts/file_metadata) [πŸ’¬ Text Generation](https://docs.oxen.ai/examples/fine-tuning/text_generation) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Image Generation - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/inference-api/quickstart/image-generation#content-area) [​](https://docs.oxen.ai/inference-api/quickstart/image-generation#overview) Overview ---------------------------------------------------------------------------------------- Generate images from text descriptions using models like FLUX and DALL-E. [​](https://docs.oxen.ai/inference-api/quickstart/image-generation#minimal-example-synchronous) Minimal Example (Synchronous) -------------------------------------------------------------------------------------------------------------------------------- Python cURL import requests response = requests.post( "https://hub.oxen.ai/api/ai/images/generate", headers={ "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, json={ "model": "black-forest-labs-flux-2-klein-4b", "prompt": "A red cube on a white background, minimal", }, ) data = response.json() print("Image URL:", data["images"][0]["url"]) [​](https://docs.oxen.ai/inference-api/quickstart/image-generation#with-base64-response) With Base64 Response ---------------------------------------------------------------------------------------------------------------- Set `response_format` to `"b64_json"` to get the image bytes directly instead of a URL: Python cURL import requests import base64 response = requests.post( "https://hub.oxen.ai/api/ai/images/generate", headers={ "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, json={ "model": "black-forest-labs-flux-2-klein-4b", "prompt": "A blue sphere on grey background", "response_format": "b64_json", }, ) data = response.json() image_bytes = base64.b64decode(data["images"][0]["b64_json"]) with open("output.png", "wb") as f: f.write(image_bytes) print("Saved to output.png") [​](https://docs.oxen.ai/inference-api/quickstart/image-generation#async-generation-recommended) Async Generation (Recommended) ---------------------------------------------------------------------------------------------------------------------------------- For longer-running image generation jobs, using the async queue avoids long-lived HTTP connections: Python cURL import requests import time API_KEY = "YOUR_API_KEY" MODEL = "black-forest-labs-flux-2-klein-4b" HEADERS = { "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json", } # 1. Enqueue response = requests.post( "https://hub.oxen.ai/api/ai/queue", headers=HEADERS, json={ "model": MODEL, "prompt": "A watercolor painting of a mountain landscape", }, ) generation_id = response.json()["generations"][0]["generation_id"] print(f"Enqueued generation: {generation_id}") # 2. Poll until done while True: data = requests.get( f"https://hub.oxen.ai/api/ai/queue/{generation_id}", headers=HEADERS, ).json() print(f"Status: {data['status']}") if data["status"] in {"succeeded", "failed", "cancelled"}: break time.sleep(10) if data["status"] == "succeeded": print(f"Done! Result: {data['result_url']}") else: print(f"Generation {data['status']}: {data.get('error_message')}") [​](https://docs.oxen.ai/inference-api/quickstart/image-generation#what%E2%80%99s-next) What’s Next ------------------------------------------------------------------------------------------------------ * [Image Generation Reference](https://docs.oxen.ai/inference-api/reference/image_generation) for the full parameter list * [Image Editing Reference](https://docs.oxen.ai/inference-api/reference/image_editing) to edit existing images * [Async Queue](https://docs.oxen.ai/inference-api/reference/async_queue) to generate multiple images in parallel [Chat Completions](https://docs.oxen.ai/inference-api/quickstart/chat) [Video Generation](https://docs.oxen.ai/inference-api/quickstart/video-generation) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Video Generation - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/inference-api/reference/video_generation#content-area) [​](https://docs.oxen.ai/inference-api/reference/video_generation#endpoint) Endpoint --------------------------------------------------------------------------------------- POST /api/ai/videos/generate Generates videos synchronously. The request blocks until the video is ready, which can take 1-10+ minutes depending on the model and duration. For long-running or batch generation, consider using the [async queue](https://docs.oxen.ai/inference-api/reference/async_queue) instead. [​](https://docs.oxen.ai/inference-api/reference/video_generation#request-parameters) Request Parameters ----------------------------------------------------------------------------------------------------------- | Parameter | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `model` | string | **yes** | β€” | Video model name (e.g. `kling-video-v2-6-pro-text-to-video`, `kling-video-o3-pro-reference-to-video`) | | `prompt` | string | **one of** | β€” | Text prompt. Use this or `multi_prompt`, not both. | | `multi_prompt` | array | **one of** | β€” | Multi-shot prompts with per-shot duration. See [Kling O3 Pro reference](https://docs.oxen.ai/inference-api/reference/models/kling-video-o3-pro-reference-to-video)
for details. | | `duration` | integer | no | 5 | Video duration in seconds (when using `prompt`). | | `aspect_ratio` | string | no | `"16:9"` | Aspect ratio (e.g. `"16:9"`, `"9:16"`, `"1:1"`). | | `input_image` | string/array | no | β€” | Reference image(s) for image-to-video or reference-to-video models. | | `input_video` | string (URL) | no | β€” | Reference video for video-to-video models. | | `generate_audio` | boolean | no | `false` | Generate audio track (model-dependent). | | `response_format` | string | no | `"url"` | `"url"` returns a hosted URL. `"b64_json"` returns base64-encoded video bytes inline. | | `target_namespace` | string | no | current user | Namespace to save results and bill to. Can be an organization name. | Additional parameters vary by model. Use the [model detail endpoint](https://docs.oxen.ai/inference-api/reference/models/overview#retrieve-model) (`GET /api/ai/models/:id`) to see the `request_schema` for model-specific parameters. Either `prompt` or `multi_prompt` is required. Sending both returns an error: "Getting model response error: 422 - Value error, Cannot provide both 'prompt' and 'multi_prompt'." Sending neither returns: "Getting model response error: 422 - Value error, Either 'prompt' or 'multi_prompt' must be provided." [​](https://docs.oxen.ai/inference-api/reference/video_generation#examples) Examples --------------------------------------------------------------------------------------- ### [​](https://docs.oxen.ai/inference-api/reference/video_generation#basic-text-to-video) Basic text-to-video Python cURL import requests response = requests.post( "https://hub.oxen.ai/api/ai/videos/generate", headers={ "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, json={ "model": "kling-video-v2-6-pro-text-to-video", "prompt": "A red balloon floating upward through blue sky", "duration": 5, }, ) data = response.json() print("Video URL:", data["videos"][0]["url"]) ### [​](https://docs.oxen.ai/inference-api/reference/video_generation#response-response_format-url) Response (`response_format: "url"`) { "model": "kling-video-v2-6-pro-text-to-video", "created": 1775090508, "videos": [\ {\ "url": "https://hub.oxen.ai/api/repos/.../files/.../video.mp4?..."\ }\ ] } The URL is a temporary link that expires after a period of time. ### [​](https://docs.oxen.ai/inference-api/reference/video_generation#response-response_format-b64_json) Response (`response_format: "b64_json"`) { "model": "kling-video-v2-6-pro-text-to-video", "created": 1775090508, "videos": [\ {\ "b64_json": ""\ }\ ] } ### [​](https://docs.oxen.ai/inference-api/reference/video_generation#multi-shot-video) Multi-shot video Python cURL import requests response = requests.post( "https://hub.oxen.ai/api/ai/videos/generate", headers={ "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, json={ "model": "kling-video-o3-pro-reference-to-video", "multi_prompt": [\ {"prompt": "Wide shot: a bird takes off from a branch", "duration": 5},\ {"prompt": "Tracking shot: the bird soars through clouds", "duration": 5},\ ], "aspect_ratio": "16:9", }, ) data = response.json() print("Video URL:", data["videos"][0]["url"]) [​](https://docs.oxen.ai/inference-api/reference/video_generation#important-notes) Important Notes ----------------------------------------------------------------------------------------------------- * Video generation can take several minutes. Very long generations may time out on your client side. * For long-running or batch generation, use [`/ai/queue`](https://docs.oxen.ai/inference-api/reference/async_queue) which returns immediately and processes in the background. [​](https://docs.oxen.ai/inference-api/reference/video_generation#errors) Errors ----------------------------------------------------------------------------------- | Condition | Error | | --- | --- | | Both `prompt` and `multi_prompt` | `"Getting model response error: 422 - Value error, Cannot provide both 'prompt' and 'multi_prompt'."` | | Neither `prompt` nor `multi_prompt` | `"Getting model response error: 422 - Value error, Either 'prompt' or 'multi_prompt' must be provided."` | | Model not found | `"Model not found: "` | [Image Editing](https://docs.oxen.ai/inference-api/reference/image_editing) [Async Queue](https://docs.oxen.ai/inference-api/reference/async_queue) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Topaz Starlight Precise 2.5 - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/topaz_starlight_precise_2_5#content-area) Video restoration and upscaling model focused on preserving fine detail and temporal consistency while improving clarity. Upscales input video to 1080p, 2K, or 4K and lets you control the output frame rate (up to 60 fps). **Model name:** `topazlabs-upscale-starlight-2-5-video` [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/topaz_starlight_precise_2_5#endpoint) Endpoint ---------------------------------------------------------------------------------------------------------------------- POST /api/ai/videos/generate Video upscaling is synchronous β€” the request blocks until the video is ready. Processing time depends on the input video length and target resolution. It is recommended to use [`/ai/queue`](https://docs.oxen.ai/inference-api/reference/async_queue) instead for long-running jobs, so that you don’t have long running http requests. [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/topaz_starlight_precise_2_5#request-parameters) Request Parameters ------------------------------------------------------------------------------------------------------------------------------------------ | Parameter | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `model` | string | **yes** | β€” | `"topazlabs-upscale-starlight-2-5-video"` | | `input_video` | string (URI) | **yes** | β€” | URL of the video to upscale. | | `resolution` | string | no | `"4k"` | Target output resolution: `"1080p"`, `"2k"`, or `"4k"`. | | `target_fps` | integer | no | `24` | Target frame rate (1–60 fps). | | `response_format` | string | no | `"url"` | `"url"` returns a hosted URL. `"b64_json"` returns base64-encoded video bytes inline. | | `target_namespace` | string | no | current user | Namespace to save results and bill to. Can be an organization name. | ### [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/topaz_starlight_precise_2_5#resolution-and-pricing) Resolution and Pricing | Resolution | Cost per Second | | --- | --- | | 1080p | $0.0374 | | 2K | $0.1494 | | 4K | $0.1494 | Higher resolutions (2K and 4K) are billed at the high-res rate. [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/topaz_starlight_precise_2_5#examples) Examples ---------------------------------------------------------------------------------------------------------------------- ### [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/topaz_starlight_precise_2_5#upscale-to-4k-default) Upscale to 4K (default) Python cURL import requests response = requests.post( "https://hub.oxen.ai/api/ai/videos/generate", headers={ "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, json={ "model": "topazlabs-upscale-starlight-2-5-video", "input_video": "https://example.com/my-video.mp4", }, ) data = response.json() print("Video URL:", data["videos"][0]["url"]) ### [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/topaz_starlight_precise_2_5#upscale-to-1080p-at-60-fps) Upscale to 1080p at 60 fps Python cURL import requests response = requests.post( "https://hub.oxen.ai/api/ai/videos/generate", headers={ "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, json={ "model": "topazlabs-upscale-starlight-2-5-video", "input_video": "https://example.com/my-video.mp4", "resolution": "1080p", "target_fps": 60, }, ) data = response.json() print("Video URL:", data["videos"][0]["url"]) ### [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/topaz_starlight_precise_2_5#response-response_format-url) Response (`response_format: "url"`) { "created": 1775090723, "model": "topazlabs-upscale-starlight-2-5-video", "videos": [\ {\ "url": "https://hub.oxen.ai/api/repos/.../files/.../video.mp4?..."\ }\ ] } The URL is a temporary link that expires after a period of time. ### [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/topaz_starlight_precise_2_5#response-response_format-b64_json) Response (`response_format: "b64_json"`) { "created": 1775090723, "model": "topazlabs-upscale-starlight-2-5-video", "videos": [\ {\ "b64_json": ""\ }\ ] } [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/topaz_starlight_precise_2_5#using-with-/ai/queue) Using with /ai/queue ---------------------------------------------------------------------------------------------------------------------------------------------- Recommended for longer videos. Returns immediately, processes in the background. ### [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/topaz_starlight_precise_2_5#enqueue) Enqueue Python cURL import requests response = requests.post( "https://hub.oxen.ai/api/ai/queue", headers={ "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, json={ "model": "topazlabs-upscale-starlight-2-5-video", "input_video": "https://example.com/my-video.mp4", "resolution": "4k", "target_fps": 30, "num_generations": 1, }, ) generations = response.json()["generations"] for g in generations: print(f"ID: {g['generation_id']}, Status: {g['status']}") ### [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/topaz_starlight_precise_2_5#poll) Poll Python cURL import requests import time generation_id = "4ef840a4-..." while True: data = requests.get( f"https://hub.oxen.ai/api/ai/queue/{generation_id}", headers={"Authorization": "Bearer YOUR_API_KEY"}, ).json() if data["status"] in {"succeeded", "failed", "cancelled"}: break time.sleep(10) if data["status"] == "succeeded": print(f"Result: {data['result_url']}") else: print(f"Generation {data['status']}: {data.get('error_message')}") A generation is done when its `status` is `succeeded`, `failed`, or `cancelled`. On success, `result_url` points to the output file. ### [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/topaz_starlight_precise_2_5#cancel) Cancel Python cURL import requests generation_id = "4ef840a4-..." response = requests.delete( f"https://hub.oxen.ai/api/ai/queue/{generation_id}", headers={"Authorization": "Bearer YOUR_API_KEY"}, ) print(response.json()) [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/topaz_starlight_precise_2_5#errors) Errors ------------------------------------------------------------------------------------------------------------------ | Error | Cause | Fix | | --- | --- | --- | | `Field required` | Missing `input_video` | Provide a video URL | | `Invalid resolution` | Unsupported resolution value | Use `"1080p"`, `"2k"`, or `"4k"` | | `target_fps must be between 1 and 60` | FPS out of range | Use a value between 1 and 60 | | `num_generations must be an integer between 1 and 4` | Invalid count (via `/ai/queue`) | Use 1–4 | [Seedance 2.0: Reference to Video](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/seedance_2_reference_to_video) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Kling O3 Edit: Video to Video - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/kling_o3_pro_video_to_video_edit#content-area) Edit existing videos using text instructions. Describe what to change β€” add objects, swap characters, alter scenery β€” and the model re-renders the video accordingly. Supports reference images (`@Image1`, `@Image2`, …) and structured element references (`@Element1`, `@Element2`, …) for character/object consistency across the edit. **Model name:** `kling-video-o3-pro-video-to-video-edit` [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/kling_o3_pro_video_to_video_edit#endpoint) Endpoint --------------------------------------------------------------------------------------------------------------------------- POST /api/ai/videos/generate Video editing is synchronous β€” the request blocks until the edited video is ready (typically 1–5 minutes). It is recommended to use [`/ai/queue`](https://docs.oxen.ai/inference-api/reference/async_queue) instead for long-running jobs, so that you don’t have long running http requests. [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/kling_o3_pro_video_to_video_edit#request-parameters) Request Parameters ----------------------------------------------------------------------------------------------------------------------------------------------- | Parameter | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `model` | string | **yes** | β€” | `"kling-video-o3-pro-video-to-video-edit"` | | `prompt` | string | **yes** | β€” | Text description of what to generate or how to edit the video. | | `input_video` | string (URI) | **yes** | β€” | URL of the source video to edit. | | `input_image` | array of URIs | no | β€” | Reference images for style/appearance. Use `@Image1`, `@Image2`, etc. in the prompt to refer to them. | | `elements` | array of objects | no | β€” | Structured element references for characters/objects. See [elements](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/kling_o3_pro_video_to_video_edit#elements)
below. | | `keep_audio` | boolean | no | `false` | Whether to keep the original audio from the source video. | | `response_format` | string | no | `"url"` | `"url"` returns a hosted URL. `"b64_json"` returns base64-encoded video bytes inline. | | `target_namespace` | string | no | current user | Namespace to save results and bill to. Can be an organization name. | ### [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/kling_o3_pro_video_to_video_edit#elements) elements Array of element objects for character/object reference. Use `@Element1`, `@Element2`, etc. in prompts. | Field | Type | Required | Description | | --- | --- | --- | --- | | `frontal_image_url` | string (URI) | **yes** | Front view of the reference object or character. | | `reference_image_urls` | array of URIs | no | Additional angles. Max 3 images per element. | [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/kling_o3_pro_video_to_video_edit#examples) Examples --------------------------------------------------------------------------------------------------------------------------- ### [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/kling_o3_pro_video_to_video_edit#basic-video-edit) Basic video edit Python cURL import requests response = requests.post( "https://hub.oxen.ai/api/ai/videos/generate", headers={ "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, json={ "model": "kling-video-o3-pro-video-to-video-edit", "prompt": "A red bird flies in and lands in-between the two birds on the wire", "input_video": "https://example.com/birds-on-wire.mp4", }, ) data = response.json() print("Video URL:", data["videos"][0]["url"]) ### [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/kling_o3_pro_video_to_video_edit#edit-with-reference-images) Edit with reference images Python cURL import requests response = requests.post( "https://hub.oxen.ai/api/ai/videos/generate", headers={ "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, json={ "model": "kling-video-o3-pro-video-to-video-edit", "prompt": "Replace the person with @Image1 walking in the same direction", "input_video": "https://example.com/street-scene.mp4", "input_image": ["https://example.com/character-reference.jpg"], }, ) data = response.json() print("Video URL:", data["videos"][0]["url"]) ### [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/kling_o3_pro_video_to_video_edit#edit-with-elements-and-keep-audio) Edit with elements and keep audio Python cURL import requests response = requests.post( "https://hub.oxen.ai/api/ai/videos/generate", headers={ "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, json={ "model": "kling-video-o3-pro-video-to-video-edit", "prompt": "@Element1 replaces the main character in the scene", "input_video": "https://example.com/original-scene.mp4", "elements": [\ {\ "frontal_image_url": "https://example.com/character-front.jpg",\ "reference_image_urls": [\ "https://example.com/character-side.jpg",\ "https://example.com/character-back.jpg",\ ],\ }\ ], "keep_audio": True, }, ) data = response.json() print("Video URL:", data["videos"][0]["url"]) ### [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/kling_o3_pro_video_to_video_edit#response-response_format-url) Response (`response_format: "url"`) { "created": 1775090723, "model": "kling-video-o3-pro-video-to-video-edit", "videos": [\ {\ "url": "https://hub.oxen.ai/api/repos/.../files/.../video.mp4?..."\ }\ ] } The URL is a temporary link that expires after a period of time. ### [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/kling_o3_pro_video_to_video_edit#response-response_format-b64_json) Response (`response_format: "b64_json"`) { "created": 1775090723, "model": "kling-video-o3-pro-video-to-video-edit", "videos": [\ {\ "b64_json": ""\ }\ ] } [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/kling_o3_pro_video_to_video_edit#using-with-/ai/queue) Using with /ai/queue --------------------------------------------------------------------------------------------------------------------------------------------------- Recommended for video editing. Returns immediately, processes in the background. ### [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/kling_o3_pro_video_to_video_edit#enqueue) Enqueue Python cURL import requests response = requests.post( "https://hub.oxen.ai/api/ai/queue", headers={ "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, json={ "model": "kling-video-o3-pro-video-to-video-edit", "prompt": "Change the background to a sunset beach", "input_video": "https://example.com/my-video.mp4", "num_generations": 2, }, ) generations = response.json()["generations"] for g in generations: print(f"ID: {g['generation_id']}, Status: {g['status']}") ### [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/kling_o3_pro_video_to_video_edit#poll) Poll Python cURL import requests import time generation_id = "4ef840a4-..." while True: data = requests.get( f"https://hub.oxen.ai/api/ai/queue/{generation_id}", headers={"Authorization": "Bearer YOUR_API_KEY"}, ).json() if data["status"] in {"succeeded", "failed", "cancelled"}: break time.sleep(10) if data["status"] == "succeeded": print(f"Result: {data['result_url']}") else: print(f"Generation {data['status']}: {data.get('error_message')}") A generation is done when its `status` is `succeeded`, `failed`, or `cancelled`. On success, `result_url` points to the output file. ### [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/kling_o3_pro_video_to_video_edit#cancel) Cancel Python cURL import requests generation_id = "4ef840a4-..." response = requests.delete( f"https://hub.oxen.ai/api/ai/queue/{generation_id}", headers={"Authorization": "Bearer YOUR_API_KEY"}, ) print(response.json()) [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/kling_o3_pro_video_to_video_edit#errors) Errors ----------------------------------------------------------------------------------------------------------------------- | Error | Cause | Fix | | --- | --- | --- | | `Field required` | Missing `prompt` or `input_video` | Both are required | | `Invalid URL` | Malformed `input_video` URL | Provide a valid video URL | | `num_generations must be an integer between 1 and 4` | Invalid count (via `/ai/queue`) | Use 1–4 | [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/kling_o3_pro_video_to_video_edit#other-kling-models) Other Kling Models ----------------------------------------------------------------------------------------------------------------------------------------------- | Model | Input | Use Case | Cost/sec | | --- | --- | --- | --- | | `kling-video-v2-6-pro-text-to-video` | Text only | Simple text-to-video | $0.070 | | `kling-video-v2-6-pro-image-to-video` | Image | Animate a single image | $0.070 | | `kling-video-o3-pro-image-to-video` | Image + text | Higher quality image animation | $0.224 | | `kling-video-o3-pro-reference-to-video` | Images + text | Reference-conditioned, multi-shot | $0.224 | | `kling-video-o3-pro-video-to-video-edit` | Video + text | Edit existing video | $0.336 | | `kling-video-v3-pro-motion-control` | Text + image + video | Camera/motion control | $0.168 | The O3 Pro models produce higher quality output than v2.x but cost roughly 3x more per second. [Kling O3 Pro: Reference to Video](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/kling_o3_pro_reference_to_video) [Seedance 2.0: Reference to Video](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/seedance_2_reference_to_video) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Video Generation - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/inference-api/quickstart/video-generation#content-area) [​](https://docs.oxen.ai/inference-api/quickstart/video-generation#overview) Overview ---------------------------------------------------------------------------------------- Generate videos from text descriptions, reference images, or existing videos. [​](https://docs.oxen.ai/inference-api/quickstart/video-generation#minimal-example-synchronous) Minimal Example (Synchronous) -------------------------------------------------------------------------------------------------------------------------------- Note: Synchronous generation can take 5-15 minutes to complete for certain models, we recommend using the async queue and polling for long-running jobs (See Below). Python cURL import requests response = requests.post( "https://hub.oxen.ai/api/ai/videos/generate", headers={ "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, json={ "model": "kling-video-v2-6-pro-text-to-video", "prompt": "A red balloon floating upward through blue sky", "duration": 5, }, ) data = response.json() print("Video URL:", data["videos"][0]["url"]) [​](https://docs.oxen.ai/inference-api/quickstart/video-generation#async-generation-recommended) Async Generation (Recommended) ---------------------------------------------------------------------------------------------------------------------------------- For video generation, using the async queue avoids long-lived HTTP connections: Python cURL import requests import time API_KEY = "YOUR_API_KEY" MODEL = "kling-video-v2-6-pro-text-to-video" HEADERS = { "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json", } # 1. Enqueue response = requests.post( "https://hub.oxen.ai/api/ai/queue", headers=HEADERS, json={ "model": MODEL, "prompt": "A sunset timelapse over the ocean", "duration": 5, }, ) generation_id = response.json()["generations"][0]["generation_id"] print(f"Enqueued generation: {generation_id}") # 2. Poll until done while True: data = requests.get( f"https://hub.oxen.ai/api/ai/queue/{generation_id}", headers=HEADERS, ).json() print(f"Status: {data['status']}") if data["status"] in {"succeeded", "failed", "cancelled"}: break time.sleep(10) if data["status"] == "succeeded": print(f"Done! Result: {data['result_url']}") else: print(f"Generation {data['status']}: {data.get('error_message')}") [​](https://docs.oxen.ai/inference-api/quickstart/video-generation#what%E2%80%99s-next) What’s Next ------------------------------------------------------------------------------------------------------ * [Video Generation Reference](https://docs.oxen.ai/inference-api/reference/video_generation) for the full parameter list * [Kling O3 Pro: Reference to Video](https://docs.oxen.ai/inference-api/reference/models/kling-video-o3-pro-reference-to-video) for multi-shot video with reference images * [Async Queue Reference](https://docs.oxen.ai/inference-api/reference/async_queue) for batch generation [Image Generation](https://docs.oxen.ai/inference-api/quickstart/image-generation) [Async Queue](https://docs.oxen.ai/inference-api/quickstart/async-queue) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Models - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/inference-api/reference/models/overview#content-area) Browse per-model API references ------------------------------- Sample requests, parameter tables, and workbench links for every model. Discover models on our Models page ---------------------------------- Filter by modality, search by name, and preview every model side-by-side. [​](https://docs.oxen.ai/inference-api/reference/models/overview#list-models) List Models -------------------------------------------------------------------------------------------- GET /api/ai/models Lists all available models. OpenAI-compatible. ### [​](https://docs.oxen.ai/inference-api/reference/models/overview#query-parameters) Query Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `developer_name` | string | no | Filter by developer (e.g. `openai`, `anthropic`, `google`) | | `action` | string | no | Filter by fine-tuning action type | ### [​](https://docs.oxen.ai/inference-api/reference/models/overview#response) Response { "object": "list", "data": [\ {\ "id": "claude-sonnet-4-6",\ "object": "model",\ "created": 1750000000,\ "owned_by": "oxen",\ "display_name": "Claude Sonnet 4.6",\ "description": "Anthropic's balanced model for a wide range of tasks",\ "summary": "Balanced performance and speed",\ "model_type": "base",\ "endpoint": "/chat/completions",\ "capabilities": {\ "input": ["text", "image"],\ "output": ["text"]\ },\ "pricing": {\ "method": "token",\ "input_cost_per_token": 3e-6,\ "output_cost_per_token": 1.5e-5\ },\ "fine_tuning": null,\ "deployments": [],\ "developer": {\ "name": "Anthropic",\ "logo": "https://..."\ },\ "source_model": null,\ "image_url": null,\ "released_at": "2025-06-19T00:00:00Z",\ "request_schema": null\ }\ ] } ### [​](https://docs.oxen.ai/inference-api/reference/models/overview#examples) Examples Python cURL import requests response = requests.get( "https://hub.oxen.ai/api/ai/models", headers={"Authorization": "Bearer YOUR_API_KEY"}, ) for model in response.json()["data"]: print(f"{model['id']} ({model['endpoint']})") * * * [​](https://docs.oxen.ai/inference-api/reference/models/overview#search-models) Search Models ------------------------------------------------------------------------------------------------ GET /api/ai/models/search Search models by name. ### [​](https://docs.oxen.ai/inference-api/reference/models/overview#query-parameters-2) Query Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `search` | string | **yes** | Search query | ### [​](https://docs.oxen.ai/inference-api/reference/models/overview#examples-2) Examples Python cURL import requests response = requests.get( "https://hub.oxen.ai/api/ai/models/search", headers={"Authorization": "Bearer YOUR_API_KEY"}, params={"search": "kling"}, ) for model in response.json()["data"]: print(f"{model['id']} - {model['display_name']}") * * * [​](https://docs.oxen.ai/inference-api/reference/models/overview#retrieve-model) Retrieve Model -------------------------------------------------------------------------------------------------- GET /api/ai/models/:id Retrieves a model by name. Returns the full model object including the `request_schema` describing model-specific parameters. ### [​](https://docs.oxen.ai/inference-api/reference/models/overview#path-parameters) Path Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `id` | string | **yes** | Model name (e.g. `claude-sonnet-4-6`, `flux-2-dev`) | ### [​](https://docs.oxen.ai/inference-api/reference/models/overview#query-parameters-3) Query Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `deployment_status` | string | no | Pass `"live"` to refresh deployment status from provider before responding | ### [​](https://docs.oxen.ai/inference-api/reference/models/overview#examples-3) Examples Python cURL import requests response = requests.get( "https://hub.oxen.ai/api/ai/models/kling-video-o3-pro-reference-to-video", headers={"Authorization": "Bearer YOUR_API_KEY"}, ) model = response.json() print(f"Endpoint: {model['endpoint']}") print(f"Pricing: {model['pricing']}") # Get the model's parameter schema if model.get("request_schema"): print(f"Parameters: {model['request_schema']}") * * * [​](https://docs.oxen.ai/inference-api/reference/models/overview#activate-model) Activate Model -------------------------------------------------------------------------------------------------- POST /api/ai/models/:id/activate Activates an inactive custom model deployment. Base models are always active and do not need activation. ### [​](https://docs.oxen.ai/inference-api/reference/models/overview#path-parameters-2) Path Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `id` | string | **yes** | Model name | ### [​](https://docs.oxen.ai/inference-api/reference/models/overview#examples-4) Examples Python cURL import requests response = requests.post( "https://hub.oxen.ai/api/ai/models/my-custom-model/activate", headers={"Authorization": "Bearer YOUR_API_KEY"}, ) model = response.json() print(f"Status: {model['deployments'][0]['status']}") * * * [​](https://docs.oxen.ai/inference-api/reference/models/overview#deactivate-model) Deactivate Model ------------------------------------------------------------------------------------------------------ POST /api/ai/models/:id/deactivate Deactivates an active custom model deployment to stop billing. ### [​](https://docs.oxen.ai/inference-api/reference/models/overview#path-parameters-3) Path Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `id` | string | **yes** | Model name | ### [​](https://docs.oxen.ai/inference-api/reference/models/overview#examples-5) Examples Python cURL import requests response = requests.post( "https://hub.oxen.ai/api/ai/models/my-custom-model/deactivate", headers={"Authorization": "Bearer YOUR_API_KEY"}, ) model = response.json() print(f"Status: {model['deployments'][0]['status']}") * * * [​](https://docs.oxen.ai/inference-api/reference/models/overview#model-object) Model Object ---------------------------------------------------------------------------------------------- Every endpoint above returns one or more model objects with this schema: | Field | Type | Description | | --- | --- | --- | | `id` | string | Model identifier used in API calls (e.g. `claude-sonnet-4-6`) | | `object` | string | Always `"model"` | | `created` | integer | Unix timestamp when the model was registered | | `owned_by` | string | `"oxen"` for base models, owner namespace for custom models | | `display_name` | string | Human-readable name | | `description` | string/null | Full description | | `summary` | string/null | Brief summary | | `model_type` | string | `"base"` or `"custom"` | | `endpoint` | string | API endpoint to call: `"/chat/completions"`, `"/images/generate"`, or `"/videos/generate"` | | `capabilities` | object | Input/output modalities, e.g. `input: ["text", "image"]`, `output: ["text"]` | | `pricing` | object | See [Pricing](https://docs.oxen.ai/inference-api/reference/models/overview#pricing)
below | | `fine_tuning` | object/null | Fine-tuning config with `actions` and `cost_per_second`, or `null` if not fine-tuneable | | `deployments` | array | Deployment status objects. Possible statuses: `active`, `inactive`, `deploying`, `deactivating`, `error`, `unknown`. Empty for base models. | | `developer` | object/null | Developer info with `name` and `logo` fields | | `source_model` | string/null | Base model this was fine-tuned from | | `image_url` | string/null | Image asset URL | | `released_at` | string/null | Release timestamp | | `request_schema` | object/null | JSON Schema describing model-specific request parameters | ### [​](https://docs.oxen.ai/inference-api/reference/models/overview#pricing) Pricing The `pricing` object describes how the model is billed: | Field | Type | Description | | --- | --- | --- | | `method` | string | `"token"`, `"time"`, `"per_image"`, or `"per_video_output_second"` | | `input_cost_per_token` | number/null | Cost per input token (token-based models) | | `output_cost_per_token` | number/null | Cost per output token (token-based models) | | `cost_per_second` | number/null | Cost per second (time-based models) | | `cost_per_image` | number/null | Fixed cost per image (image generation models) | | `cost_per_second_high_res` | number/null | High-resolution video cost per second | | `cost_per_second_with_audio` | number/null | Video with audio cost per second | [​](https://docs.oxen.ai/inference-api/reference/models/overview#errors) Errors ---------------------------------------------------------------------------------- | Condition | Status | Error | | --- | --- | --- | | Model not found | 404 | `"Model not found: "` | | Not authenticated | 401 | `"unauthenticated"` | [Async Queue](https://docs.oxen.ai/inference-api/reference/async_queue) [Model API References](https://docs.oxen.ai/inference-api/reference/model-references) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Chat Completions - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/inference-api/reference/chat_completions#content-area) [​](https://docs.oxen.ai/inference-api/reference/chat_completions#endpoint) Endpoint --------------------------------------------------------------------------------------- POST /api/ai/chat/completions Compatible with the OpenAI chat completions format. Supports streaming, multimodal input (images and video), tool calling, and structured output. [​](https://docs.oxen.ai/inference-api/reference/chat_completions#request-parameters) Request Parameters ----------------------------------------------------------------------------------------------------------- | Parameter | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `model` | string | **yes** | β€” | Model name (e.g. `claude-sonnet-4-6`, `gpt-5-4-2026-03-05`, `gemini-3-1-flash-lite-preview`) | | `messages` | array | **yes** | β€” | Array of message objects. Must not be empty. | | `stream` | boolean | no | `false` | Stream the response as server-sent events. | | `max_tokens` | integer | no | varies | Maximum tokens in the response. | | `temperature` | number | no | varies | Sampling temperature (0-2). | | `top_p` | number | no | β€” | Nucleus sampling parameter. | | `frequency_penalty` | number | no | β€” | Penalize repeated tokens. | | `presence_penalty` | number | no | β€” | Penalize tokens already present. | | `tools` | array | no | β€” | Tool/function definitions for tool calling. | | `tool_choice` | string/object | no | β€” | Control tool selection behavior. | | `parallel_tool_calls` | boolean | no | β€” | Allow parallel tool calls. | | `response_format` | object | no | β€” | Constrain response format (e.g. `{"type": "json_object"}`). Support varies by provider. | [​](https://docs.oxen.ai/inference-api/reference/chat_completions#message-format) Message Format --------------------------------------------------------------------------------------------------- Each message has a `role` and `content`: [\ {"role": "system", "content": "You are a helpful assistant."},\ {"role": "user", "content": "Hello!"},\ {"role": "assistant", "content": "Hi there!"}\ ] ### [​](https://docs.oxen.ai/inference-api/reference/chat_completions#vision-multimodal) Vision (multimodal) Use a content array to include images or video: { "role": "user", "content": [\ {"type": "text", "text": "What's in this image?"},\ {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}}\ ] } Video input: { "role": "user", "content": [\ {"type": "text", "text": "Describe this video"},\ {"type": "video_url", "video_url": {"url": "https://example.com/clip.mp4"}}\ ] } Image and video URLs must be publicly accessible. [​](https://docs.oxen.ai/inference-api/reference/chat_completions#examples) Examples --------------------------------------------------------------------------------------- ### [​](https://docs.oxen.ai/inference-api/reference/chat_completions#basic-text-generation) Basic text generation Python cURL from openai import OpenAI client = OpenAI( base_url="https://hub.oxen.ai/api/ai", api_key="YOUR_API_KEY", ) response = client.chat.completions.create( model="claude-sonnet-4-6", messages=[{"role": "user", "content": "Say hello in exactly 3 words."}], max_tokens=50, temperature=0.1, ) print(response.choices[0].message.content) ### [​](https://docs.oxen.ai/inference-api/reference/chat_completions#response) Response { "id": "chatcmpl-97eab7db-fe67-4b29-900c-ed5260c654d4", "object": "chat.completion", "created": 1775090332, "model": "claude-sonnet-4-6", "choices": [\ {\ "index": 0,\ "message": {\ "role": "assistant",\ "content": "Hello, how are you?"\ },\ "finish_reason": "stop"\ }\ ], "usage": { "prompt_tokens": 15, "completion_tokens": 5, "total_tokens": 20 } } ### [​](https://docs.oxen.ai/inference-api/reference/chat_completions#streaming) Streaming Python cURL from openai import OpenAI client = OpenAI( base_url="https://hub.oxen.ai/api/ai", api_key="YOUR_API_KEY", ) stream = client.chat.completions.create( model="gemini-3-1-flash-lite-preview", messages=[{"role": "user", "content": "Say hello"}], stream=True, ) for chunk in stream: content = chunk.choices[0].delta.content if content: print(content, end="", flush=True) print() Returns server-sent events. Each chunk has a `delta` instead of a full `message`: data: {"choices":[{"delta":{"content":"Hello"},"finish_reason":null,"index":0}],"created":1775090334,"id":"chatcmpl-...","model":"gemini-3-1-flash-lite-preview","object":"chat.completion.chunk"} data: {"choices":[{"delta":{"content":" there"},"finish_reason":null,"index":0}],...} data: [DONE] ### [​](https://docs.oxen.ai/inference-api/reference/chat_completions#tool-calling) Tool calling Python cURL from openai import OpenAI client = OpenAI( base_url="https://hub.oxen.ai/api/ai", api_key="YOUR_API_KEY", ) response = client.chat.completions.create( model="gpt-5-4-2026-03-05", messages=[\ {"role": "system", "content": "Use tools when appropriate."},\ {"role": "user", "content": "What is the weather in San Francisco?"},\ ], tools=[{\ "type": "function",\ "function": {\ "name": "get_weather",\ "description": "Get current weather",\ "parameters": {\ "type": "object",\ "properties": {"location": {"type": "string"}},\ "required": ["location"],\ },\ },\ }], ) tool_call = response.choices[0].message.tool_calls[0] print(f"{tool_call.function.name}({tool_call.function.arguments})") When the model uses a tool, `finish_reason` is `"tool_calls"`: { "choices": [{\ "finish_reason": "tool_calls",\ "message": {\ "content": null,\ "role": "assistant",\ "tool_calls": [{\ "id": "call_GRNwPXnbuQW4Sa3QNB3FYkYw",\ "index": 0,\ "type": "function",\ "function": {\ "name": "get_weather",\ "arguments": "{\"location\":\"San Francisco\"}"\ }\ }]\ }\ }] } ### [​](https://docs.oxen.ai/inference-api/reference/chat_completions#structured-output-json-mode) Structured output (JSON mode) Python cURL from openai import OpenAI client = OpenAI( base_url="https://hub.oxen.ai/api/ai", api_key="YOUR_API_KEY", ) response = client.chat.completions.create( model="gpt-5-4-2026-03-05", messages=[{"role": "user", "content": "List 3 colors as a JSON array"}], response_format={"type": "json_object"}, max_tokens=100, ) print(response.choices[0].message.content) [​](https://docs.oxen.ai/inference-api/reference/chat_completions#errors) Errors ----------------------------------------------------------------------------------- | Condition | Error | | --- | --- | | No model specified | `"You must specify a model to call"` | | Model not found | `"Model not found: "` | | Empty messages | `"Messages array cannot be empty"` | | Insufficient credits | Credit-related error message | [Async Queue](https://docs.oxen.ai/inference-api/quickstart/async-queue) [Image Generation](https://docs.oxen.ai/inference-api/reference/image_generation) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Init - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/python-api/init#content-area) [​](https://docs.oxen.ai/python-api/init#oxen-init) oxen.init ================================================================ [​](https://docs.oxen.ai/python-api/init#init) init ------------------------------------------------------ def init(path: str = "./") Initialize a [Repo](https://docs.oxen.ai/python-api/repo) at the given path. **Arguments**: * `path` - `str` The path to initialize the repo at. **Returns**: [Repo](https://docs.oxen.ai/python-api/repo) A Repo object that can be used to interact with the repo. [Text diff](https://docs.oxen.ai/python-api/diff/text_diff) [Oxen fs](https://docs.oxen.ai/python-api/oxen_fs) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Clone - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/python-api/clone#content-area) [​](https://docs.oxen.ai/python-api/clone#oxen-clone) oxen.clone =================================================================== [​](https://docs.oxen.ai/python-api/clone#clone) clone --------------------------------------------------------- def clone(repo_id: str, path: Optional[str] = None, host: str = "hub.oxen.ai", branch: str = "main", scheme: str = "https", all=False) Clone a repository **Arguments**: * `repo_id` - `str` Name of the repository in the format β€˜namespace/repo\_name’. For example β€˜ox/chatbot’ * `path` - `Optional[str]` The path to clone the repo to. Defaults to the name of the repository. * `host` - `str` The host to connect to. Defaults to β€˜hub.oxen.ai’ * `branch` - `str` The branch name id to clone. Defaults to β€˜main’ * `scheme` - `str` The scheme to use. Defaults to β€˜https’ * `all` - `bool` Whether to clone the full commit history or not. Default: False **Returns**: [Repo](https://docs.oxen.ai/python-api/repo) A Repo object that can be used to interact with the cloned repo. [Introduction](https://docs.oxen.ai/python-api) [Data frame](https://docs.oxen.ai/python-api/data_frame) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Seedance 2.0: Reference to Video - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/seedance_2_reference_to_video#content-area) ByteDance Seedance 2.0 reference-to-video generates video from a text prompt guided by reference images, videos, and/or audio. Reference media are addressed in the prompt as `@Image1`, `@Image2`, `@Video1`, `@Video2`, `@Audio1`, etc. Supports resolutions up to 720p, durations from 4–15 seconds, and synchronized audio generation including sound effects, ambient sounds, and lip-synced speech. **Model name:** `bytedance-seedance-2-0-reference-to-video` [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/seedance_2_reference_to_video#endpoint) Endpoint ------------------------------------------------------------------------------------------------------------------------ POST /api/ai/videos/generate Video generation is synchronous β€” the request blocks until the video is ready (typically 1–5 minutes). It is recommended to use [`/ai/queue`](https://docs.oxen.ai/inference-api/reference/async_queue) instead for long-running jobs, so that you don’t have long running http requests. [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/seedance_2_reference_to_video#request-parameters) Request Parameters -------------------------------------------------------------------------------------------------------------------------------------------- | Parameter | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `model` | string | **yes** | β€” | `"bytedance-seedance-2-0-reference-to-video"` | | `prompt` | string | **yes** | β€” | Text prompt. Use `@Image1`, `@Video1`, `@Audio1`, etc. to reference input media. | | `input_images` | array of URIs | no | β€” | Reference images (JPEG, PNG, WebP). Max 30 MB each. Up to 9. Use `@Image1`, `@Image2`, … in the prompt. | | `input_videos` | array of URIs | no | β€” | Reference videos (MP4, MOV). Up to 3. Combined duration must be 2–15 s, total size < 50 MB. Resolution between ~480p and ~720p. Use `@Video1`, `@Video2`, … in the prompt. | | `input_audios` | array of URIs | no | β€” | Reference audio (MP3, WAV). Up to 3 files. Combined duration ≀ 15 s. Max 15 MB each. Requires at least one reference image or video. Use `@Audio1`, `@Audio2`, … in the prompt. | | `resolution` | string | no | `"720p"` | `"480p"` for faster generation, `"720p"` for higher quality. | | `duration` | string | no | `"auto"` | Duration in seconds: `"auto"`, or `"4"` through `"15"`. | | `generate_audio` | boolean | no | `true` | Generate synchronized audio (sound effects, ambient sounds, lip-synced speech). Cost is the same either way. | | `aspect_ratio` | string | no | `"auto"` | `"auto"`, `"21:9"`, `"16:9"`, `"4:3"`, `"1:1"`, `"3:4"`, or `"9:16"`. | | `seed` | integer | no | β€” | Random seed for reproducibility. Results may still vary slightly. | | `response_format` | string | no | `"url"` | `"url"` returns a hosted URL. `"b64_json"` returns base64-encoded video bytes inline. | | `target_namespace` | string | no | current user | Namespace to save results and bill to. Can be an organization name. | ### [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/seedance_2_reference_to_video#reference-media-limits) Reference Media Limits | Modality | Max Count | Size Limit | Other Constraints | | --- | --- | --- | --- | | Images | 9 | 30 MB each | JPEG, PNG, WebP | | Videos | 3 | 50 MB total | MP4, MOV. Combined duration 2–15 s. Resolution ~480p to ~720p. | | Audio | 3 | 15 MB each | MP3, WAV. Combined duration ≀ 15 s. Requires β‰₯ 1 image or video. | Total files across all modalities must not exceed 12. ### [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/seedance_2_reference_to_video#duration) Duration | Value | Behavior | | --- | --- | | `"auto"` | Model decides based on prompt and references | | `"4"` – `"15"` | Fixed duration in seconds | [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/seedance_2_reference_to_video#examples) Examples ------------------------------------------------------------------------------------------------------------------------ ### [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/seedance_2_reference_to_video#text-only-prompt) Text-only prompt Python cURL import requests response = requests.post( "https://hub.oxen.ai/api/ai/videos/generate", headers={ "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, json={ "model": "bytedance-seedance-2-0-reference-to-video", "prompt": "A serene mountain lake at sunrise with mist rolling across the water", }, ) data = response.json() print("Video URL:", data["videos"][0]["url"]) ### [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/seedance_2_reference_to_video#with-reference-images) With reference images Python cURL import requests response = requests.post( "https://hub.oxen.ai/api/ai/videos/generate", headers={ "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, json={ "model": "bytedance-seedance-2-0-reference-to-video", "prompt": "@Image1 walks through a crowded market, browsing the stalls", "input_images": ["https://example.com/character.jpg"], "duration": "8", "aspect_ratio": "16:9", }, ) data = response.json() print("Video URL:", data["videos"][0]["url"]) ### [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/seedance_2_reference_to_video#with-reference-video-and-audio) With reference video and audio Python cURL import requests response = requests.post( "https://hub.oxen.ai/api/ai/videos/generate", headers={ "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, json={ "model": "bytedance-seedance-2-0-reference-to-video", "prompt": "@Image1 dances to the rhythm of @Audio1 in the style of @Video1", "input_images": ["https://example.com/dancer.jpg"], "input_videos": ["https://example.com/dance-reference.mp4"], "input_audios": ["https://example.com/music.mp3"], "resolution": "720p", "duration": "10", "generate_audio": True, }, ) data = response.json() print("Video URL:", data["videos"][0]["url"]) ### [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/seedance_2_reference_to_video#portrait-video-at-480p) Portrait video at 480p Python cURL import requests response = requests.post( "https://hub.oxen.ai/api/ai/videos/generate", headers={ "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, json={ "model": "bytedance-seedance-2-0-reference-to-video", "prompt": "@Image1 speaks directly to camera, warm studio lighting", "input_images": ["https://example.com/speaker.jpg"], "resolution": "480p", "aspect_ratio": "9:16", "duration": "6", "generate_audio": True, }, ) data = response.json() print("Video URL:", data["videos"][0]["url"]) ### [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/seedance_2_reference_to_video#response-response_format-url) Response (`response_format: "url"`) { "created": 1775090723, "model": "bytedance-seedance-2-0-reference-to-video", "videos": [\ {\ "url": "https://hub.oxen.ai/api/repos/.../files/.../video.mp4?..."\ }\ ] } The URL is a temporary link that expires after a period of time. ### [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/seedance_2_reference_to_video#response-response_format-b64_json) Response (`response_format: "b64_json"`) { "created": 1775090723, "model": "bytedance-seedance-2-0-reference-to-video", "videos": [\ {\ "b64_json": ""\ }\ ] } [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/seedance_2_reference_to_video#using-with-/ai/queue) Using with /ai/queue ------------------------------------------------------------------------------------------------------------------------------------------------ Recommended for video generation. Returns immediately, processes in the background. ### [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/seedance_2_reference_to_video#enqueue) Enqueue Python cURL import requests response = requests.post( "https://hub.oxen.ai/api/ai/queue", headers={ "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, json={ "model": "bytedance-seedance-2-0-reference-to-video", "prompt": "@Image1 waves at the camera and smiles", "input_images": ["https://example.com/person.jpg"], "duration": "5", "num_generations": 2, }, ) generations = response.json()["generations"] for g in generations: print(f"ID: {g['generation_id']}, Status: {g['status']}") ### [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/seedance_2_reference_to_video#poll) Poll Python cURL import requests import time generation_id = "4ef840a4-..." while True: data = requests.get( f"https://hub.oxen.ai/api/ai/queue/{generation_id}", headers={"Authorization": "Bearer YOUR_API_KEY"}, ).json() if data["status"] in {"succeeded", "failed", "cancelled"}: break time.sleep(10) if data["status"] == "succeeded": print(f"Result: {data['result_url']}") else: print(f"Generation {data['status']}: {data.get('error_message')}") A generation is done when its `status` is `succeeded`, `failed`, or `cancelled`. On success, `result_url` points to the output file. ### [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/seedance_2_reference_to_video#cancel) Cancel Python cURL import requests generation_id = "4ef840a4-..." response = requests.delete( f"https://hub.oxen.ai/api/ai/queue/{generation_id}", headers={"Authorization": "Bearer YOUR_API_KEY"}, ) print(response.json()) [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/seedance_2_reference_to_video#errors) Errors -------------------------------------------------------------------------------------------------------------------- | Error | Cause | Fix | | --- | --- | --- | | `Field required` | Missing `prompt` | Provide a text prompt | | `Too many input files` | Total files across images, videos, audio > 12 | Reduce the number of reference files | | `Audio requires at least one image or video` | `input_audios` provided without `input_images` or `input_videos` | Add at least one reference image or video | | `Invalid duration` | Duration not `"auto"` or `"4"`–`"15"` | Use a supported duration value | | `Invalid resolution` | Resolution not `"480p"` or `"720p"` | Use `"480p"` or `"720p"` | | `num_generations must be an integer between 1 and 4` | Invalid count (via `/ai/queue`) | Use 1–4 | [Kling O3 Edit: Video to Video](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/kling_o3_pro_video_to_video_edit) [Topaz Starlight Precise 2.5](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/topaz_starlight_precise_2_5) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Tabular diff - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/python-api/diff/tabular_diff#content-area) [​](https://docs.oxen.ai/python-api/diff/tabular_diff#oxen-diff/tabular-diff) oxen.diff/tabular\_diff ======================================================================================================== [​](https://docs.oxen.ai/python-api/diff/tabular_diff#tabulardiff-objects) TabularDiff Objects ------------------------------------------------------------------------------------------------- class TabularDiff() This class returns a polars data frame that represents a tabular diff. [​](https://docs.oxen.ai/python-api/diff/tabular_diff#data) data ------------------------------------------------------------------- @property def data() -> DataFrame Returns the data of the diff as a polars data frame. [Line diff](https://docs.oxen.ai/python-api/diff/line_diff) [Text diff](https://docs.oxen.ai/python-api/diff/text_diff) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Line diff - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/python-api/diff/line_diff#content-area) [​](https://docs.oxen.ai/python-api/diff/line_diff#oxen-diff/line-diff) oxen.diff/line\_diff =============================================================================================== [​](https://docs.oxen.ai/python-api/diff/line_diff#linediff-objects) LineDiff Objects ---------------------------------------------------------------------------------------- class LineDiff() A class representing a change in a line of text. [​](https://docs.oxen.ai/python-api/diff/line_diff#modification) modification -------------------------------------------------------------------------------- @property def modification() -> ChangeType Returns the modification of the line diff. [​](https://docs.oxen.ai/python-api/diff/line_diff#text) text ---------------------------------------------------------------- @property def text() -> str Returns the text of the line diff. [Diff](https://docs.oxen.ai/python-api/diff/diff) [Tabular diff](https://docs.oxen.ai/python-api/diff/tabular_diff) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Text diff - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/python-api/diff/text_diff#content-area) [​](https://docs.oxen.ai/python-api/diff/text_diff#oxen-diff/text-diff) oxen.diff/text\_diff =============================================================================================== [​](https://docs.oxen.ai/python-api/diff/text_diff#textdiff-objects) TextDiff Objects ---------------------------------------------------------------------------------------- class TextDiff() A class representing a text diff. [​](https://docs.oxen.ai/python-api/diff/text_diff#num-added) num\_added --------------------------------------------------------------------------- @property def num_added() -> int Returns the number of added lines in the diff. [​](https://docs.oxen.ai/python-api/diff/text_diff#num-removed) num\_removed ------------------------------------------------------------------------------- @property def num_removed() -> int Returns the number of removed lines in the diff. [​](https://docs.oxen.ai/python-api/diff/text_diff#lines) lines ------------------------------------------------------------------ @property def lines() -> list[LineDiff] Returns the contents of the diff as a polars data frame. [Tabular diff](https://docs.oxen.ai/python-api/diff/tabular_diff) [Init](https://docs.oxen.ai/python-api/init) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Datasets - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/python-api/datasets#content-area) [​](https://docs.oxen.ai/python-api/datasets#oxen-datasets) oxen.datasets ============================================================================ [​](https://docs.oxen.ai/python-api/datasets#load-dataset) load\_dataset --------------------------------------------------------------------------- def load_dataset(repo_id: str, path: str, fmt: str = "hugging_face", revision=None) Load a dataset from an Oxen repository into memory using the HuggingFace datasets library. **Arguments**: * `repo_id` - `str` The namespace/repo\_name of the oxen repository to load the dataset from * `path` - `str` | Sequence\[str\] The path to the dataset we want to load * `fmt` - `str` The format of the data files. Currently only β€œhugging\_face” is supported. * `revision` - `str` | None The commit id or branch name of the version of the data to download **Example**: from oxen.datasets import load_dataset dataset = load_dataset("datasets/gsm8k", "train.jsonl") # use datasets functions as you normally would dataset.shuffle()[:10] [​](https://docs.oxen.ai/python-api/datasets#download) download ------------------------------------------------------------------ def download(repo_id: str, path: str, revision=None, dst=None, host="hub.oxen.ai", scheme="https") Download files or directories from a remote Oxen repository. **Arguments**: * `repo_id` - `str` The namespace/repo\_name of the oxen repository to load the dataset from * `path` - `str` The path to the data files * `revision` - `str | None` The commit id or branch name of the version of the data to download * `dst` - `str | None` The path to download the data to. * `host` - `str` The host to download the data from. * `scheme` - `str` The scheme to download the data with. (default: β€œhttps”) [​](https://docs.oxen.ai/python-api/datasets#upload) upload -------------------------------------------------------------- def upload(repo_id: str, path: str, message: str, branch: Optional[str] = None, dst: str = "") Upload files or directories to a remote Oxen repository. **Arguments**: * `repo_id` - `str` The namespace/repo\_name of the oxen repository to upload the dataset to * `path` - `str` The path to the data files * `message` - `str` The commit message to use when uploading the data * `branch` - `str | None` The branch to upload the data to. If None, the `main` branch is used. * `dst` - `str | None` The directory to upload the data to. [Data frame](https://docs.oxen.ai/python-api/data_frame) [Df utils](https://docs.oxen.ai/python-api/df_utils) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Df utils - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/python-api/df_utils#content-area) [​](https://docs.oxen.ai/python-api/df_utils#oxen-df-utils) oxen.df\_utils ============================================================================= The `df_utils` module provides a consistent interface for loading data frames and saving them to disk. Supported types: csv, parquet, json, jsonl, arrow Example usage: import os from oxen import df_utils # load a data frame df = df_utils.load("path/to/data.csv") # save a data frame df_utils.save(df, "path/to/save.csv") [​](https://docs.oxen.ai/python-api/df_utils#load) load ---------------------------------------------------------- def load(path: os.PathLike) Reads a file into a data frame. The file format is inferred from the file extension. Supported types: csv, parquet, json, jsonl, arrow **Arguments**: * `path` - `os.PathLike` The path to the file to read. [​](https://docs.oxen.ai/python-api/df_utils#save) save ---------------------------------------------------------- def save(data_frame: DataFrame, path: os.PathLike) Saves a data frame to a file. The file format is inferred from the file extension. **Arguments**: * `data_frame` - `DataFrame` The polars data frame to save. * `path` - `os.PathLike` The path to save the data frame to. [Datasets](https://docs.oxen.ai/python-api/datasets) [Diff](https://docs.oxen.ai/python-api/diff/diff) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Activate model deployment - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/fine-tuning-api/activate-model-deployment#content-area) Activate model deployment cURL curl --request POST \ --url https://hub.oxen.ai/api/ai/models/{id}/activate 200 { "created": 123, "id": "", "owned_by": "", "capabilities": { "input": [\ ""\ ], "output": [\ ""\ ] }, "deployments": [\ {}\ ], "description": "", "developer": { "logo": "", "name": "" }, "display_name": "", "fine_tuning": { "actions": [\ ""\ ], "cost_per_second": 123 }, "image_url": "", "pricing": { "cost_per_image": 123, "cost_per_second": 123, "cost_per_second_high_res": 123, "cost_per_second_with_audio": 123, "input_cost_per_token": 123, "output_cost_per_token": 123 }, "released_at": "", "request_schema": {}, "showcase": { "gallery": [\ {\ "alt": "",\ "src": "",\ "category": "",\ "details": "",\ "prompt": "",\ "title": ""\ }\ ], "hero_image": "", "tagline": "" }, "source_model": "", "summary": "" } POST / api / ai / models / {id} / activate Try it Activate model deployment cURL curl --request POST \ --url https://hub.oxen.ai/api/ai/models/{id}/activate 200 { "created": 123, "id": "", "owned_by": "", "capabilities": { "input": [\ ""\ ], "output": [\ ""\ ] }, "deployments": [\ {}\ ], "description": "", "developer": { "logo": "", "name": "" }, "display_name": "", "fine_tuning": { "actions": [\ ""\ ], "cost_per_second": 123 }, "image_url": "", "pricing": { "cost_per_image": 123, "cost_per_second": 123, "cost_per_second_high_res": 123, "cost_per_second_with_audio": 123, "input_cost_per_token": 123, "output_cost_per_token": 123 }, "released_at": "", "request_schema": {}, "showcase": { "gallery": [\ {\ "alt": "",\ "src": "",\ "category": "",\ "details": "",\ "prompt": "",\ "title": ""\ }\ ], "hero_image": "", "tagline": "" }, "source_model": "", "summary": "" } #### Path Parameters [​](https://docs.oxen.ai/fine-tuning-api/activate-model-deployment#parameter-id) id string required #### Response 200 - application/json Model activated Represents a model available for inference or fine-tuning. Compatible with the OpenAI model object. [​](https://docs.oxen.ai/fine-tuning-api/activate-model-deployment#response-created) created integer required Unix timestamp when the model was registered [​](https://docs.oxen.ai/fine-tuning-api/activate-model-deployment#response-id) id string required Model identifier used in API calls [​](https://docs.oxen.ai/fine-tuning-api/activate-model-deployment#response-object) object enum required Available options: `model` [​](https://docs.oxen.ai/fine-tuning-api/activate-model-deployment#response-owned-by) owned\_by string required "oxen" for base models, owner namespace for custom models [​](https://docs.oxen.ai/fine-tuning-api/activate-model-deployment#response-capabilities) capabilities object Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/activate-model-deployment#response-deployments) deployments object\[\] Active deployments. Empty for base models. Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/activate-model-deployment#response-description-one-of-0) description string | null [​](https://docs.oxen.ai/fine-tuning-api/activate-model-deployment#response-developer-one-of-0) developer object Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/activate-model-deployment#response-display-name) display\_name string [​](https://docs.oxen.ai/fine-tuning-api/activate-model-deployment#response-endpoint) endpoint enum API endpoint to call this model Available options: `/chat/completions`, `/images/generate`, `/videos/generate` [​](https://docs.oxen.ai/fine-tuning-api/activate-model-deployment#response-fine-tuning-one-of-0) fine\_tuning object Fine-tuning info, or null if model is not fine-tuneable Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/activate-model-deployment#response-image-url-one-of-0) image\_url string | null [​](https://docs.oxen.ai/fine-tuning-api/activate-model-deployment#response-model-type) model\_type enum Available options: `base`, `custom` [​](https://docs.oxen.ai/fine-tuning-api/activate-model-deployment#response-pricing) pricing object Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/activate-model-deployment#response-released-at-one-of-0) released\_at string | null [​](https://docs.oxen.ai/fine-tuning-api/activate-model-deployment#response-request-schema-one-of-0) request\_schema object JSON Schema describing model-specific parameters [​](https://docs.oxen.ai/fine-tuning-api/activate-model-deployment#response-showcase-one-of-0) showcase object Optional marketing content rendered on the public model showcase page Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/activate-model-deployment#response-source-model-one-of-0) source\_model string | null Base model this was fine-tuned from [​](https://docs.oxen.ai/fine-tuning-api/activate-model-deployment#response-summary-one-of-0) summary string | null [Delete custom model](https://docs.oxen.ai/fine-tuning-api/delete-custom-model) [Deactivate model deployment](https://docs.oxen.ai/fine-tuning-api/deactivate-model-deployment) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Kling O3 Pro: Reference to Video - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/kling_o3_pro_reference_to_video#content-area) Transforms reference images into dynamic video sequences. Preserves identity, layout, and text from reference images while adding realistic motion, camera movements, and scene progression. Supports multi-shot generation with per-shot prompts and durations, and optional native audio (Chinese/English). **Model name:** `kling-video-o3-pro-reference-to-video` [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/kling_o3_pro_reference_to_video#endpoint) Endpoint -------------------------------------------------------------------------------------------------------------------------- POST /api/ai/videos/generate Video generation is synchronous, the request blocks until the video is ready (typically 1-5 minutes). It is recommended to use [`/ai/queue`](https://docs.oxen.ai/inference-api/reference/async_queue) instead for long-running jobs, so that you don’t have long running http requests. [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/kling_o3_pro_reference_to_video#request-parameters) Request Parameters ---------------------------------------------------------------------------------------------------------------------------------------------- | Parameter | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `model` | string | **yes** | β€” | `"kling-video-o3-pro-reference-to-video"` | | `prompt` | string | **one of** | β€” | Single prompt for the video. Use this or `multi_prompt`, not both. Max 512 characters. | | `multi_prompt` | array | **one of** | β€” | Multi-shot prompts. See [multi\_prompt](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/kling_o3_pro_reference_to_video#multi_prompt)
below. | | `duration` | integer | no | 5 | Duration in seconds when using `prompt`. | | `input_image` | array of URIs | no | β€” | Reference images for style/appearance (max 4 combined with elements). Reference in prompts as `@Image1`, `@Image2`, etc. | | `start_image_url` | string (URI) | no | β€” | First frame of the video. The model extends from this image. | | `tail_image_url` | string (URI) | no | β€” | Last frame of the video. Requires `start_image_url`. The model fills in between the frames. | | `elements` | array of objects | no | β€” | Structured element references for characters/objects. See [elements](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/kling_o3_pro_reference_to_video#elements)
below. | | `negative_prompt` | string | no | `"blur, distort, and low quality"` | Text describing what to avoid in the generated video. | | `aspect_ratio` | string | no | `"16:9"` | `"9:16"`, `"1:1"`, or `"16:9"`. | | `generate_audio` | boolean | no | `false` | Generate native audio. Supports Chinese and English voice output. | | `response_format` | string | no | `"url"` | `"url"` returns a hosted URL. `"b64_json"` returns base64-encoded video bytes inline. | | `target_namespace` | string | no | current user | Namespace to save results and bill to. Can be an organization name. | ### [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/kling_o3_pro_reference_to_video#prompt-vs-multi_prompt) prompt vs multi\_prompt Use **either** `prompt` or `multi_prompt`, not both. Sending both returns: "Cannot provide both 'prompt' and 'multi_prompt'." Sending neither (or an empty `multi_prompt: []`) returns: "Either 'prompt' or 'multi_prompt' must be provided." When using `prompt`, the duration defaults to 5 seconds. Override with `duration`: {"model": "kling-video-o3-pro-reference-to-video", "prompt": "A flower blooming in timelapse", "duration": 10} ### [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/kling_o3_pro_reference_to_video#multi_prompt) multi\_prompt Array of shot objects. Each shot generates a segment of the video. | Field | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `prompt` | string | **yes** | β€” | Prompt for this shot. Max 512 characters. | | `duration` | integer | no | 5 | Duration of this shot in seconds (1-15). | ### [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/kling_o3_pro_reference_to_video#duration-constraints) Duration Constraints | Constraint | Value | | --- | --- | | Minimum total duration | **3 seconds** | | Maximum total duration | **15 seconds** | | Maximum per shot | 15 seconds | | Default per shot | 5 seconds | Individual shots can be as short as 1 second, as long as the total across all shots is between 3 and 15 seconds. | Configuration | Total | Result | | --- | --- | --- | | Single shot, `duration: 1` | 1s | **Fails** | | Single shot, `duration: 2` | 2s | **Fails** | | Single shot, `duration: 3` | 3s | Works | | Two shots: `duration: 2` + `duration: 1` | 3s | Works | | Two shots: `duration: 1` + `duration: 1` | 2s | **Fails** | | Single shot, `duration: 15` | 15s | Works | | Three shots: `duration: 5` + `duration: 5` + `duration: 5` | 15s | Works | | Three shots: `duration: 5` + `duration: 5` + `duration: 6` | 16s | **Fails** | When total duration is too short: "duration value '2' is invalid. Try using duration='5' instead, as duration support may vary by model and mode." When total duration exceeds 15 seconds: "Total shot duration (16s) exceeds maximum allowed (15s)." When a single shot exceeds 15 seconds: "Input should be '1', '2', '3', '4', '5', '6', '7', '8', '9', '10', '11', '12', '13', '14' or '15'" ### [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/kling_o3_pro_reference_to_video#elements) elements Array of element objects for character/object reference. Use `@Element1`, `@Element2`, etc. in prompts. | Field | Type | Required | Description | | --- | --- | --- | --- | | `frontal_image_url` | string (URI) | **yes** | Front view of the reference object or character. | | `reference_image_urls` | array of URIs | no | Additional angles. Max 3 images per element. | Maximum 4 total images across all elements and `input_image` references. [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/kling_o3_pro_reference_to_video#examples) Examples -------------------------------------------------------------------------------------------------------------------------- ### [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/kling_o3_pro_reference_to_video#minimal-text-only) Minimal: text only `input_image` is optional. Without it the model generates purely from the prompt. Python cURL import requests response = requests.post( "https://hub.oxen.ai/api/ai/videos/generate", headers={ "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, json={ "model": "kling-video-o3-pro-reference-to-video", "prompt": "A puppy runs through a park", }, ) data = response.json() print("Video URL:", data["videos"][0]["url"]) ### [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/kling_o3_pro_reference_to_video#single-prompt-with-reference-image) Single prompt with reference image Python cURL import requests response = requests.post( "https://hub.oxen.ai/api/ai/videos/generate", headers={ "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, json={ "model": "kling-video-o3-pro-reference-to-video", "prompt": "A dog runs across a sunny field", "input_image": ["https://example.com/dog.jpg"], }, ) data = response.json() print("Video URL:", data["videos"][0]["url"]) ### [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/kling_o3_pro_reference_to_video#multi-shot-with-reference-image) Multi-shot with reference image Python cURL import requests response = requests.post( "https://hub.oxen.ai/api/ai/videos/generate", headers={ "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, json={ "model": "kling-video-o3-pro-reference-to-video", "multi_prompt": [\ {"prompt": "A woman walks toward the camera smiling, cinematic lighting", "duration": 5},\ {"prompt": "She turns and looks out a window, soft focus background", "duration": 5},\ ], "input_image": ["https://example.com/reference-face.jpg"], }, ) data = response.json() print("Video URL:", data["videos"][0]["url"]) ### [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/kling_o3_pro_reference_to_video#with-start/end-frames-and-elements) With start/end frames and elements Python cURL import requests response = requests.post( "https://hub.oxen.ai/api/ai/videos/generate", headers={ "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, json={ "model": "kling-video-o3-pro-reference-to-video", "multi_prompt": [\ {"prompt": "@Element1 picks up a coffee cup from the table", "duration": 5},\ ], "start_image_url": "https://example.com/first-frame.jpg", "tail_image_url": "https://example.com/last-frame.jpg", "elements": [\ {\ "frontal_image_url": "https://example.com/character-front.jpg",\ "reference_image_urls": ["https://example.com/character-side.jpg"],\ }\ ], "aspect_ratio": "16:9", "generate_audio": True, }, ) data = response.json() print("Video URL:", data["videos"][0]["url"]) ### [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/kling_o3_pro_reference_to_video#response-response_format-url) Response (`response_format: "url"`) { "created": 1775090723, "model": "kling-video-o3-pro-reference-to-video", "videos": [\ {\ "url": "https://hub.oxen.ai/api/repos/.../files/.../video.mp4?..."\ }\ ] } The URL is a temporary link that expires after a period of time. ### [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/kling_o3_pro_reference_to_video#response-response_format-b64_json) Response (`response_format: "b64_json"`) { "created": 1775090723, "model": "kling-video-o3-pro-reference-to-video", "videos": [\ {\ "b64_json": ""\ }\ ] } [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/kling_o3_pro_reference_to_video#using-with-/ai/queue) Using with /ai/queue -------------------------------------------------------------------------------------------------------------------------------------------------- Recommended for video generation. Returns immediately, processes in the background. ### [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/kling_o3_pro_reference_to_video#enqueue) Enqueue Python cURL import requests response = requests.post( "https://hub.oxen.ai/api/ai/queue", headers={ "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, json={ "model": "kling-video-o3-pro-reference-to-video", "multi_prompt": [{"prompt": "A person speaking into a microphone", "duration": 5}], "generate_audio": True, "num_generations": 2, }, ) generations = response.json()["generations"] for g in generations: print(f"ID: {g['generation_id']}, Status: {g['status']}") ### [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/kling_o3_pro_reference_to_video#poll) Poll Python cURL import requests import time generation_id = "4ef840a4-..." while True: data = requests.get( f"https://hub.oxen.ai/api/ai/queue/{generation_id}", headers={"Authorization": "Bearer YOUR_API_KEY"}, ).json() if data["status"] in {"succeeded", "failed", "cancelled"}: break time.sleep(10) if data["status"] == "succeeded": print(f"Result: {data['result_url']}") else: print(f"Generation {data['status']}: {data.get('error_message')}") A generation is done when its `status` is `succeeded`, `failed`, or `cancelled`. On success, `result_url` points to the output file. ### [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/kling_o3_pro_reference_to_video#cancel) Cancel Python cURL import requests generation_id = "4ef840a4-..." response = requests.delete( f"https://hub.oxen.ai/api/ai/queue/{generation_id}", headers={"Authorization": "Bearer YOUR_API_KEY"}, ) print(response.json()) [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/kling_o3_pro_reference_to_video#errors) Errors ---------------------------------------------------------------------------------------------------------------------- | Error | Cause | Fix | | --- | --- | --- | | `Getting model response error: 422 - Value error, Cannot provide both 'prompt' and 'multi_prompt'.` | Sent both fields | Use one or the other | | `Getting model response error: 422 - Value error, Either 'prompt' or 'multi_prompt' must be provided.` | Neither sent, or empty array | Provide at least one | | `Field required` | `multi_prompt` item missing `prompt` | Every shot needs a `prompt` string | | `duration value '2' is invalid` | Total duration < 3 seconds | Ensure total across shots >= 3 | | `Total shot duration (16s) exceeds maximum allowed (15s)` | Total duration > 15 seconds | Keep total at 15 seconds or less | | `Input should be '1', '2', ... or '15'` | Single shot > 15 | Keep each shot at 15 seconds or less | | `num_generations must be an integer between 1 and 4` | Invalid count (via `/ai/queue`) | Use 1-4 | [​](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/kling_o3_pro_reference_to_video#other-kling-models) Other Kling Models ---------------------------------------------------------------------------------------------------------------------------------------------- | Model | Input | Use Case | Cost/sec | | --- | --- | --- | --- | | `kling-video-v2-6-pro-text-to-video` | Text only | Simple text-to-video | $0.070 | | `kling-video-v2-6-pro-image-to-video` | Image | Animate a single image | $0.070 | | `kling-video-o3-pro-image-to-video` | Image + text | Higher quality image animation | $0.224 | | `kling-video-o3-pro-reference-to-video` | Images + text | Reference-conditioned, multi-shot | $0.224 | | `kling-video-o3-pro-video-to-video-edit` | Video | Edit existing video | $0.336 | | `kling-video-v3-pro-motion-control` | Text + image + video | Camera/motion control | $0.168 | The O3 Pro models produce higher quality output than v2.x but cost roughly 3x more per second. [Model Walkthroughs](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/overview) [Kling O3 Edit: Video to Video](https://docs.oxen.ai/inference-api/reference/models/walkthroughs/kling_o3_pro_video_to_video_edit) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Cancel generation - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/fine-tuning-api/cancel-generation#content-area) Cancel generation cURL curl --request DELETE \ --url https://hub.oxen.ai/api/ai/queue/{generation_id} 200 404 { "generation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a" } DELETE / api / ai / queue / {generation\_id} Try it Cancel generation cURL curl --request DELETE \ --url https://hub.oxen.ai/api/ai/queue/{generation_id} 200 404 { "generation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a" } #### Path Parameters [​](https://docs.oxen.ai/fine-tuning-api/cancel-generation#parameter-generation-id) generation\_id string required #### Response 200 application/json Generation cancelled [​](https://docs.oxen.ai/fine-tuning-api/cancel-generation#response-generation-id) generation\_id string required [​](https://docs.oxen.ai/fine-tuning-api/cancel-generation#response-status) status enum required Available options: `success` [Get generation status](https://docs.oxen.ai/fine-tuning-api/get-generation-status) [Generate video](https://docs.oxen.ai/fine-tuning-api/generate-video) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Diff - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/python-api/diff/diff#content-area) [​](https://docs.oxen.ai/python-api/diff/diff#oxen-diff/diff) oxen.diff/diff =============================================================================== Oxen can be used to compare data frames and return a tabular diff. There is more information about the diff in the [Diff Getting Started Documentation](https://docs.oxen.ai/concepts/diffs) . For example comparing two data frames will give you an output data frame, where the `.oxen.diff.status` column shows if the row was `added`, `removed`, or `modified`. shape: (6, 7) +-------------+-----+-----+-------+--------+-------------+-------------------+ | file | x | y | width | height | label.right | .oxen.diff.status | | --- | --- | --- | --- | --- | --- | --- | | str | i64 | i64 | i64 | i64 | str | str | +-------------+-----+-----+-------+--------+-------------+-------------------+ | image_0.jpg | 0 | 0 | 10 | 10 | cat | modified | | image_1.jpg | 1 | 2 | 10 | 20 | null | removed | | image_1.jpg | 200 | 100 | 10 | 20 | dog | added | | image_2.jpg | 4 | 10 | 20 | 20 | null | removed | | image_3.jpg | 4 | 10 | 20 | 20 | dog | added | | image_4.jpg | 10 | 10 | 10 | 10 | dog | added | +-------------+-----+-----+-------+--------+-------------+-------------------+ [​](https://docs.oxen.ai/python-api/diff/diff#usage) Usage ------------------------------------------------------------- import os import oxen result = oxen.diff("dataset_1.csv", "dataset_2.csv") print(result.get()) [​](https://docs.oxen.ai/python-api/diff/diff#diff) diff ----------------------------------------------------------- def diff(path: os.PathLike, to: Optional[os.PathLike] = None, repo_dir: Optional[os.PathLike] = None, revision_left: Optional[str] = None, revision_right: Optional[str] = None, output: Optional[os.PathLike] = None, keys: list[str] = [], compares: list[str] = []) Compares data from two paths and returns a diff respecting the type of data. **Arguments**: * `path` - `os.PathLike` The path to diff. If `to` is not provided, this will compare the data frame to the previous commit. * `to` - `os.PathLike` An optional second path to compare to. If provided this will be the right side of the diff. * `repo_dir` - `os.PathLike` The path to the oxen repository. Must be provided if `compare_to` is not provided, or if `revision_left` or `revision_right` is provided. If not provided, the repository will be searched for in the current working directory. * `revision_left` - `str` The left revision to compare. Can be a commit hash or branch name. * `revision_right` - `str` The right revision to compare. Can be a commit hash or branch name. * `output` - `os.PathLike` The path to save the diff to. If not provided, the diff will not be saved. * `keys` - `list[str]` Only for tabular diffs. The keys to compare on. This is used to join the two data frames. Keys will be combined and hashed to create a identifier for each row. * `compares` - `list[str]` Only for tabular diffs. The compares to compare on. This is used to compare the values of the two data frames. [​](https://docs.oxen.ai/python-api/diff/diff#diff-objects) Diff Objects --------------------------------------------------------------------------- class Diff() Diff class wraps many types of diffs and provides a consistent interface. For example the diff can be tabular or text. Eventually we will extend this to support other types of diffs such as images, audio, etc. [​](https://docs.oxen.ai/python-api/diff/diff#format) format --------------------------------------------------------------- @property def format() -> str Returns the format of the diff. Ie. tabular, text, etc. [​](https://docs.oxen.ai/python-api/diff/diff#tabular) tabular ----------------------------------------------------------------- @property def tabular() -> Optional[TabularDiff] Returns the tabular diff if the diff is tabular. [​](https://docs.oxen.ai/python-api/diff/diff#text) text ----------------------------------------------------------- @property def text() -> Optional[TextDiff] Returns the text diff if the diff is text. [​](https://docs.oxen.ai/python-api/diff/diff#get) get --------------------------------------------------------- def get() Resolves the diff type and returns the appropriate diff object. [Df utils](https://docs.oxen.ai/python-api/df_utils) [Line diff](https://docs.oxen.ai/python-api/diff/line_diff) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Workspace - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/python-api/workspace#content-area) [​](https://docs.oxen.ai/python-api/workspace#oxen-workspace) oxen.workspace =============================================================================== [​](https://docs.oxen.ai/python-api/workspace#workspace-objects) Workspace Objects ------------------------------------------------------------------------------------- class Workspace() The Workspace class allows you to interact with an Oxen workspace without downloading the data locally. Workspaces can be created off a branch and is tied to the commit id of the branch at the time of creation. You can commit a Workspace back to the same branch if the branch has not advanced, otherwise you will have to commit to a new branch and merge. [​](https://docs.oxen.ai/python-api/workspace#examples) Examples ------------------------------------------------------------------- ### [​](https://docs.oxen.ai/python-api/workspace#adding-files-to-a-workspace) Adding Files to a Workspace Create a workspace from a branch. from oxen import RemoteRepo from oxen import Workspace # Connect to the remote repo repo = RemoteRepo("ox/CatDogBBox") # Create the workspace workspace = Workspace(repo, "my-branch") # Add a file to the workspace workspace.add("my-image.png") # Print the status of the workspace status = workspace.status() print(status.added_files()) # Commit the workspace workspace.commit("Adding my image to the workspace.") [​](https://docs.oxen.ai/python-api/workspace#init) \_\_init\_\_ ------------------------------------------------------------------- def __init__(repo: "RemoteRepo", branch: str, workspace_id: Optional[str] = None, workspace_name: Optional[str] = None, path: Optional[str] = None) Create a new Workspace. **Arguments**: * `repo` - `PyRemoteRepo` The remote repo to create the workspace from. * `branch` - `str` The branch name to create the workspace from. The workspace will be tied to the commit id of the branch at the time of creation. * `workspace_id` - `Optional[str]` The workspace id to create the workspace from. If left empty, will create a unique workspace id. * `workspace_name` - `Optional[str]` The name of the workspace. If left empty, the workspace will have no name. * `path` - `Optional[str]` The path to the workspace. If left empty, the workspace will be created in the root of the remote repo. [​](https://docs.oxen.ai/python-api/workspace#id) id ------------------------------------------------------- @property def id() Get the id of the workspace. [​](https://docs.oxen.ai/python-api/workspace#name) name ----------------------------------------------------------- @property def name() Get the name of the workspace. [​](https://docs.oxen.ai/python-api/workspace#branch) branch --------------------------------------------------------------- @property def branch() Get the branch that the workspace is tied to. [​](https://docs.oxen.ai/python-api/workspace#commit-id) commit\_id ---------------------------------------------------------------------- @property def commit_id() Get the commit id of the workspace. [​](https://docs.oxen.ai/python-api/workspace#repo) repo ----------------------------------------------------------- @property def repo() -> "RemoteRepo" Get the remote repo that the workspace is tied to. [​](https://docs.oxen.ai/python-api/workspace#status) status --------------------------------------------------------------- def status(path: str = "") Get the status of the workspace. **Arguments**: * `path` - `str` The path to check the status of. [​](https://docs.oxen.ai/python-api/workspace#add) add --------------------------------------------------------- def add(src: str, dst: str = "") Add a file to the workspace **Arguments**: * `src` - `str` The path to the local file to be staged * `dst` - `str` The path in the remote repo where the file will be added [​](https://docs.oxen.ai/python-api/workspace#rm) rm ------------------------------------------------------- def rm(path: str) Remove a file from the workspace **Arguments**: * `path` - `str` The path to the file on workspace to be removed [​](https://docs.oxen.ai/python-api/workspace#commit) commit --------------------------------------------------------------- def commit(message: str, branch_name: Optional[str] = None) -> PyCommit Commit the workspace to a branch **Arguments**: * `message` - `str` The message to commit with * `branch_name` - `Optional[str]` The name of the branch to commit to. If left empty, will commit to the branch the workspace was created from. [​](https://docs.oxen.ai/python-api/workspace#delete) delete --------------------------------------------------------------- def delete() Delete the workspace [Repositories](https://docs.oxen.ai/python-api/repositories) [πŸ“‘ Oxen Server](https://docs.oxen.ai/getting-started/oxen-server) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Delete custom model - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/fine-tuning-api/delete-custom-model#content-area) Delete custom model cURL curl --request DELETE \ --url https://hub.oxen.ai/api/ai/models/{id} 200 404 { "created": 123, "id": "", "owned_by": "", "capabilities": { "input": [\ ""\ ], "output": [\ ""\ ] }, "deployments": [\ {}\ ], "description": "", "developer": { "logo": "", "name": "" }, "display_name": "", "fine_tuning": { "actions": [\ ""\ ], "cost_per_second": 123 }, "image_url": "", "pricing": { "cost_per_image": 123, "cost_per_second": 123, "cost_per_second_high_res": 123, "cost_per_second_with_audio": 123, "input_cost_per_token": 123, "output_cost_per_token": 123 }, "released_at": "", "request_schema": {}, "showcase": { "gallery": [\ {\ "alt": "",\ "src": "",\ "category": "",\ "details": "",\ "prompt": "",\ "title": ""\ }\ ], "hero_image": "", "tagline": "" }, "source_model": "", "summary": "" } DELETE / api / ai / models / {id} Try it Delete custom model cURL curl --request DELETE \ --url https://hub.oxen.ai/api/ai/models/{id} 200 404 { "created": 123, "id": "", "owned_by": "", "capabilities": { "input": [\ ""\ ], "output": [\ ""\ ] }, "deployments": [\ {}\ ], "description": "", "developer": { "logo": "", "name": "" }, "display_name": "", "fine_tuning": { "actions": [\ ""\ ], "cost_per_second": 123 }, "image_url": "", "pricing": { "cost_per_image": 123, "cost_per_second": 123, "cost_per_second_high_res": 123, "cost_per_second_with_audio": 123, "input_cost_per_token": 123, "output_cost_per_token": 123 }, "released_at": "", "request_schema": {}, "showcase": { "gallery": [\ {\ "alt": "",\ "src": "",\ "category": "",\ "details": "",\ "prompt": "",\ "title": ""\ }\ ], "hero_image": "", "tagline": "" }, "source_model": "", "summary": "" } #### Path Parameters [​](https://docs.oxen.ai/fine-tuning-api/delete-custom-model#parameter-id) id string required #### Response 200 application/json Deleted model Represents a model available for inference or fine-tuning. Compatible with the OpenAI model object. [​](https://docs.oxen.ai/fine-tuning-api/delete-custom-model#response-created) created integer required Unix timestamp when the model was registered [​](https://docs.oxen.ai/fine-tuning-api/delete-custom-model#response-id) id string required Model identifier used in API calls [​](https://docs.oxen.ai/fine-tuning-api/delete-custom-model#response-object) object enum required Available options: `model` [​](https://docs.oxen.ai/fine-tuning-api/delete-custom-model#response-owned-by) owned\_by string required "oxen" for base models, owner namespace for custom models [​](https://docs.oxen.ai/fine-tuning-api/delete-custom-model#response-capabilities) capabilities object Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/delete-custom-model#response-deployments) deployments object\[\] Active deployments. Empty for base models. Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/delete-custom-model#response-description-one-of-0) description string | null [​](https://docs.oxen.ai/fine-tuning-api/delete-custom-model#response-developer-one-of-0) developer object Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/delete-custom-model#response-display-name) display\_name string [​](https://docs.oxen.ai/fine-tuning-api/delete-custom-model#response-endpoint) endpoint enum API endpoint to call this model Available options: `/chat/completions`, `/images/generate`, `/videos/generate` [​](https://docs.oxen.ai/fine-tuning-api/delete-custom-model#response-fine-tuning-one-of-0) fine\_tuning object Fine-tuning info, or null if model is not fine-tuneable Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/delete-custom-model#response-image-url-one-of-0) image\_url string | null [​](https://docs.oxen.ai/fine-tuning-api/delete-custom-model#response-model-type) model\_type enum Available options: `base`, `custom` [​](https://docs.oxen.ai/fine-tuning-api/delete-custom-model#response-pricing) pricing object Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/delete-custom-model#response-released-at-one-of-0) released\_at string | null [​](https://docs.oxen.ai/fine-tuning-api/delete-custom-model#response-request-schema-one-of-0) request\_schema object JSON Schema describing model-specific parameters [​](https://docs.oxen.ai/fine-tuning-api/delete-custom-model#response-showcase-one-of-0) showcase object Optional marketing content rendered on the public model showcase page Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/delete-custom-model#response-source-model-one-of-0) source\_model string | null Base model this was fine-tuned from [​](https://docs.oxen.ai/fine-tuning-api/delete-custom-model#response-summary-one-of-0) summary string | null [Update model](https://docs.oxen.ai/fine-tuning-api/update-model) [Activate model deployment](https://docs.oxen.ai/fine-tuning-api/activate-model-deployment) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Repositories - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/python-api/repositories#content-area) [​](https://docs.oxen.ai/python-api/repositories#repository-classes) Repository Classes ------------------------------------------------------------------------------------------ There are a few basic python classes you can use to interact with Oxen repositories. The full list of Python APIs can be found in the [API Documentation](https://docs.oxen.ai/python-api) . [​](https://docs.oxen.ai/python-api/repositories#remote-vs-local) Remote vs Local ------------------------------------------------------------------------------------ Oxen has the concept of [Remote Repositories](https://docs.oxen.ai/python-api/repositories#remote-repositories) and [Local Repositories](https://docs.oxen.ai/python-api/repositories#local-repositories) . One of the core tenets of Oxen is that data should feel like it is local, even if it is not. Hence the APIs for Local vs Remote are very similar, the only difference is where you are performing the operation. [​](https://docs.oxen.ai/python-api/repositories#remote-repositories) Remote Repositories -------------------------------------------------------------------------------------------- Remote Repositories only download pointers and metadata, so that you can interact with the data as if it was local. Here is the full documentation for the [RemoteRepo](https://docs.oxen.ai/python-api/remote_repo) . ### [​](https://docs.oxen.ai/python-api/repositories#integrate-with-pandas) Integrate with Pandas The fastest way to integrate Oxen into your existing workflow is to use the fact that Oxen gives you direct access to files and directories given a specific revision. For example, let’s load a data file given a specific commit into [Pandas](https://pandas.pydata.org/) Python from oxen import RemoteRepo import pandas as pd # Connect to the remote repo repo = RemoteRepo("ox/CatDogBBox") # Specify the version of the file you want to download branch = repo.get_branch("my-pets") # Download takes a file or directory a commit id repo.download("annotations", revision=branch.commit_id) # Once you have the data locally, use whatever library you want to explore the data df = pd.read_csv("annotations/train.csv") print(df.head()) All the files are also accessible directly over http, which removes some of the boilerplate as long as the files are of a reasonable size. The url structure is `https://hub.oxen.ai/api/repos/:namespace/:repo_name/file/:revision/:file_path` Python import pandas as pd df = pd.read_csv("https://hub.oxen.ai/api/repos/ox/CatDogBBox/file/main/annotations/test.csv") print(df.head()) ### [​](https://docs.oxen.ai/python-api/repositories#add-files) Add Files Oxen has the concept of [Remote Workspaces](https://docs.oxen.ai/getting-started/workspaces) that make it easy to add data to a remote repository without ever downloading it locally. Python from oxen import RemoteRepo # Connect to the Remote repo = RemoteRepo("ox/CatDogBBox") # Create a branch on the remote and check it out # similar to oxen checkout -b add-images repo.create_checkout_branch("add-images") [​](https://docs.oxen.ai/python-api/repositories#local-repositories) Local Repositories ------------------------------------------------------------------------------------------ (Local) [Repos](https://docs.oxen.ai/python-api/repo) have all the files versioned and accessible on your local machine. They duplicate the data between your working directory and a hidden .oxen directory so that you can quickly swap between versions and run experiments. If you are creating a new repository from scratch, this is a great place to start. The workflow is very similar to [git](https://git-scm.com/) in terms of initializing a repository, adding data, committing, and pushing to a remote. Let’s walk through some basic operations. ### [​](https://docs.oxen.ai/python-api/repositories#init) Init Assuming you are creating a brand new repository, first you will have to create an empty directory, point your `LocalRepo` to it and run `init()`. import os from oxen import Repo # Create an empty directory named CatsAndDogs directory = "CatsAndDogs" os.makedirs(directory) # Initialize the Oxen Repository repo = Repo(directory) repo.init() ### [​](https://docs.oxen.ai/python-api/repositories#add-files-2) Add Files Now let’s create a README.md file and add it to the local staging area. import os from oxen import Repo # write a file called README.md to disk directory = "CatsAndDogs" file_name = "README.md" file_path = os.path.join(directory, file_name) # Open the file in write mode with open(file_path, "w") as file: # Write the title to the file file.write("# " + directory + "\n") # Assuming the Repo is already initialized repo = Repo(directory) # add the path relative to the dir repo.add(file_name) # list added files status = repo.status() print(status.added_files()) You should see that we have one file added `[README.md]` ### [​](https://docs.oxen.ai/python-api/repositories#commit-staged-files) Commit Staged Files With your README.md staged you can now commit with a message from oxen import Repo # Assuming you have already added the data repo = Repo(directory) repo.commit("Adding README.md") πŸŽ‰ Congratulations you have just versioned your first file! Now to sync it with the rest of your team. ### [​](https://docs.oxen.ai/python-api/repositories#configure-remote) Configure Remote The easiest way to create a remote is in the [Oxen Hub web interface](https://oxen.ai/) . ![Oxen.ai authentication key](https://mintcdn.com/oxenai/s_o9ZlhOEkYJf27_/images/MyRepos.png?w=2500&fit=max&auto=format&n=s_o9ZlhOEkYJf27_&q=85&s=212696cf08d08311075c35344953a37e) Then once you have a remote created, set the remote on the repo object. from oxen import Repo # Once you have data committed that you want to sync repo = Repo(directory) # You can have multiple named remotes username = "YOUR_USERNAME" repo_name = "REMOTE_REPO_NAME" remote_name = "origin" remote_url = f"https://hub.oxen.ai/{username}/{repo_name}" repo.set_remote(remote_name, remote_url) ### [​](https://docs.oxen.ai/python-api/repositories#push-to-remote) Push to Remote With your remote set and auth key configured, you are ready to push the data! from oxen import Repo # Once you have committed data and set the remote, it's time to push your branch repo = Repo(directory) remote_name = "origin" remote_branch = "main" repo.push(remote_name, remote_branch) [Repo](https://docs.oxen.ai/python-api/repo) [Workspace](https://docs.oxen.ai/python-api/workspace) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Deactivate model deployment - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/fine-tuning-api/deactivate-model-deployment#content-area) Deactivate model deployment cURL curl --request POST \ --url https://hub.oxen.ai/api/ai/models/{id}/deactivate 200 { "created": 123, "id": "", "owned_by": "", "capabilities": { "input": [\ ""\ ], "output": [\ ""\ ] }, "deployments": [\ {}\ ], "description": "", "developer": { "logo": "", "name": "" }, "display_name": "", "fine_tuning": { "actions": [\ ""\ ], "cost_per_second": 123 }, "image_url": "", "pricing": { "cost_per_image": 123, "cost_per_second": 123, "cost_per_second_high_res": 123, "cost_per_second_with_audio": 123, "input_cost_per_token": 123, "output_cost_per_token": 123 }, "released_at": "", "request_schema": {}, "showcase": { "gallery": [\ {\ "alt": "",\ "src": "",\ "category": "",\ "details": "",\ "prompt": "",\ "title": ""\ }\ ], "hero_image": "", "tagline": "" }, "source_model": "", "summary": "" } POST / api / ai / models / {id} / deactivate Try it Deactivate model deployment cURL curl --request POST \ --url https://hub.oxen.ai/api/ai/models/{id}/deactivate 200 { "created": 123, "id": "", "owned_by": "", "capabilities": { "input": [\ ""\ ], "output": [\ ""\ ] }, "deployments": [\ {}\ ], "description": "", "developer": { "logo": "", "name": "" }, "display_name": "", "fine_tuning": { "actions": [\ ""\ ], "cost_per_second": 123 }, "image_url": "", "pricing": { "cost_per_image": 123, "cost_per_second": 123, "cost_per_second_high_res": 123, "cost_per_second_with_audio": 123, "input_cost_per_token": 123, "output_cost_per_token": 123 }, "released_at": "", "request_schema": {}, "showcase": { "gallery": [\ {\ "alt": "",\ "src": "",\ "category": "",\ "details": "",\ "prompt": "",\ "title": ""\ }\ ], "hero_image": "", "tagline": "" }, "source_model": "", "summary": "" } #### Path Parameters [​](https://docs.oxen.ai/fine-tuning-api/deactivate-model-deployment#parameter-id) id string required #### Response 200 - application/json Model deactivated Represents a model available for inference or fine-tuning. Compatible with the OpenAI model object. [​](https://docs.oxen.ai/fine-tuning-api/deactivate-model-deployment#response-created) created integer required Unix timestamp when the model was registered [​](https://docs.oxen.ai/fine-tuning-api/deactivate-model-deployment#response-id) id string required Model identifier used in API calls [​](https://docs.oxen.ai/fine-tuning-api/deactivate-model-deployment#response-object) object enum required Available options: `model` [​](https://docs.oxen.ai/fine-tuning-api/deactivate-model-deployment#response-owned-by) owned\_by string required "oxen" for base models, owner namespace for custom models [​](https://docs.oxen.ai/fine-tuning-api/deactivate-model-deployment#response-capabilities) capabilities object Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/deactivate-model-deployment#response-deployments) deployments object\[\] Active deployments. Empty for base models. Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/deactivate-model-deployment#response-description-one-of-0) description string | null [​](https://docs.oxen.ai/fine-tuning-api/deactivate-model-deployment#response-developer-one-of-0) developer object Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/deactivate-model-deployment#response-display-name) display\_name string [​](https://docs.oxen.ai/fine-tuning-api/deactivate-model-deployment#response-endpoint) endpoint enum API endpoint to call this model Available options: `/chat/completions`, `/images/generate`, `/videos/generate` [​](https://docs.oxen.ai/fine-tuning-api/deactivate-model-deployment#response-fine-tuning-one-of-0) fine\_tuning object Fine-tuning info, or null if model is not fine-tuneable Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/deactivate-model-deployment#response-image-url-one-of-0) image\_url string | null [​](https://docs.oxen.ai/fine-tuning-api/deactivate-model-deployment#response-model-type) model\_type enum Available options: `base`, `custom` [​](https://docs.oxen.ai/fine-tuning-api/deactivate-model-deployment#response-pricing) pricing object Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/deactivate-model-deployment#response-released-at-one-of-0) released\_at string | null [​](https://docs.oxen.ai/fine-tuning-api/deactivate-model-deployment#response-request-schema-one-of-0) request\_schema object JSON Schema describing model-specific parameters [​](https://docs.oxen.ai/fine-tuning-api/deactivate-model-deployment#response-showcase-one-of-0) showcase object Optional marketing content rendered on the public model showcase page Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/deactivate-model-deployment#response-source-model-one-of-0) source\_model string | null Base model this was fine-tuned from [​](https://docs.oxen.ai/fine-tuning-api/deactivate-model-deployment#response-summary-one-of-0) summary string | null [Activate model deployment](https://docs.oxen.ai/fine-tuning-api/activate-model-deployment) [Favorite a model](https://docs.oxen.ai/fine-tuning-api/favorite-a-model) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Oxen fs - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/python-api/oxen_fs#content-area) [​](https://docs.oxen.ai/python-api/oxen_fs#oxen-oxen_fs) oxen.oxen\_fs ========================================================================== [​](https://docs.oxen.ai/python-api/oxen_fs#oxenfs-objects) OxenFS Objects ----------------------------------------------------------------------------- class OxenFS(fsspec.AbstractFileSystem) OxenFS is a filesystem interface for Oxen repositories that implements the [fsspec](https://filesystem-spec.readthedocs.io/en/latest/) protocol. This allows you to interact with Oxen repositories using familiar filesystem operations and integrate with other compatible libraries like Pandas. [​](https://docs.oxen.ai/python-api/oxen_fs#basic-usage) Basic Usage ----------------------------------------------------------------------- ### [​](https://docs.oxen.ai/python-api/oxen_fs#creating-a-filesystem-instance) Creating a Filesystem Instance import oxen # For Oxen Hub repositories fs = oxen.OxenFS("ox", "Flowers") # For local oxen-server fs = oxen.OxenFS("ox", "test-repo", host="localhost:3000", scheme="http") ### [​](https://docs.oxen.ai/python-api/oxen_fs#reading-files) Reading Files with fs.open("data/train.csv") as f: content = f.read() ### [​](https://docs.oxen.ai/python-api/oxen_fs#writing-files) Writing Files You must have write access to the repository to write files. See: [https://docs.oxen.ai/python-api#private-repositories](https://docs.oxen.ai/python-api#private-repositories) OxenFS will automatically commit the file to the repository when the context is exited (or the file is closed some other way). New directories are automatically created as needed. # Write with custom commit message with fs.open("data/test.txt", mode="wb", commit_message="Added test.txt") as f: f.write("Hello, world!") # You can also set/update the commit message inside the context with fs.open("data/test.txt", mode="wb") as f: f.commit_message = "Updated test.txt" f.write("Hello, world again!") [​](https://docs.oxen.ai/python-api/oxen_fs#writing-file-objects) Writing file objects ----------------------------------------------------------------------------------------- If you’re integrating Oxen in a situation where you already have a file object, you can save it to your repo by using `shutil.copyfileobj` like this: import shutil file_object_from_somewhere = open("data.csv") with fs.open("train/data.csv", mode="wb") as output_file: output_file.commit_message = "Copy from a file object" shutil.copyfileobj(file_object_from_somewhere, output_file) [​](https://docs.oxen.ai/python-api/oxen_fs#integration-with-third-party-libraries-pandas-etc) Integration with Third Party Libraries (Pandas, etc.) ------------------------------------------------------------------------------------------------------------------------------------------------------- OxenFS works seamlessly with Pandas and other fsspec-compatible libraries using the URL format: `oxen://namespace:repo@revision/path/to/file` ### [​](https://docs.oxen.ai/python-api/oxen_fs#reading-data) Reading Data These will work with Pandas `{to,from}_{csv,parquet,json,etc.}` functions. import pandas as pd # Read parquet directly from Oxen repository df = pd.read_parquet("oxen://openai:gsm8k@main/gsm8k_test.parquet") ### [​](https://docs.oxen.ai/python-api/oxen_fs#writing-data) Writing Data # Write DataFrame directly to Oxen repository df.to_csv("oxen://ox:my-repo@main/data/test.csv", index=False) [​](https://docs.oxen.ai/python-api/oxen_fs#notes) Notes ----------------------------------------------------------- * Only binary read (β€œrb”) and write (β€œwb”) modes are currently supported * But writing will automatically encode strings to bytes * Does not yet support streaming files. All operations use temporary local files. [​](https://docs.oxen.ai/python-api/oxen_fs#__init__) \_\_init\_\_ --------------------------------------------------------------------- def __init__(namespace: str, repo: str, host: str = "hub.oxen.ai", revision: str = "main", scheme: str = "https", **kwargs) Initialize the OxenFS instance. **Arguments**: * `namespace` - `str` The namespace of the repository. * `repo` - `str` The name of the repository. * `host` - `str` The host to connect to. Defaults to β€˜hub.oxen.ai’ * `revision` - `str` The branch name or commit id to checkout. Defaults to β€˜main’ * `scheme` - `str` The scheme to use for the remote url. Default: β€˜https’ [​](https://docs.oxen.ai/python-api/oxen_fs#ls) ls ----------------------------------------------------- def ls(path: str = "", detail: bool = False) List the contents of a directory. **Arguments**: * `path` - `str` The path to list the contents of. * `detail` - `bool` If True, return a list of dictionaries with detailed metadata. Otherwise, return a list of strings with the filenames. [​](https://docs.oxen.ai/python-api/oxen_fs#oxenfsfilewriter-objects) OxenFSFileWriter Objects ------------------------------------------------------------------------------------------------- class OxenFSFileWriter() A file writer for the OxenFS backend. This is normally called through `OxenFS.open()` or `fsspec.open()`. [​](https://docs.oxen.ai/python-api/oxen_fs#write) write ----------------------------------------------------------- def write(data: str | bytes) Write string or binary data to the file. [​](https://docs.oxen.ai/python-api/oxen_fs#flush) flush ----------------------------------------------------------- def flush() Flush the file to disk. [​](https://docs.oxen.ai/python-api/oxen_fs#tell) tell --------------------------------------------------------- def tell() Return the current position of the file. [​](https://docs.oxen.ai/python-api/oxen_fs#seek) seek --------------------------------------------------------- def seek(offset: int, whence: int = os.SEEK_SET) Seek to a specific position in the file. [​](https://docs.oxen.ai/python-api/oxen_fs#commit) commit ------------------------------------------------------------- def commit(commit_message: Optional[str] = None) Commit the file to the remote repo. [​](https://docs.oxen.ai/python-api/oxen_fs#close) close ----------------------------------------------------------- def close() Close the file writer. This will commit the file to the remote repo. [Init](https://docs.oxen.ai/python-api/init) [Remote repo](https://docs.oxen.ai/python-api/remote_repo) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Repo - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/python-api/repo#content-area) [​](https://docs.oxen.ai/python-api/repo#oxen-repo) oxen.repo ================================================================ [​](https://docs.oxen.ai/python-api/repo#repo-objects) Repo Objects ---------------------------------------------------------------------- class Repo() The Repo class that allows you to interact with your local oxen repo. [​](https://docs.oxen.ai/python-api/repo#examples) Examples -------------------------------------------------------------- ### [​](https://docs.oxen.ai/python-api/repo#init-add-commit-and-push) Init, Add, Commit and Push Adding and committing a file to a remote workspace. import os from oxen import Repo # Initialize the Oxen Repository in a CatsAndDogs directory directory = "CatsAndDogs" repo = Repo(directory) repo.init() repo.add("images") repo.commit("Adding all the images") # Replace and with your values repo.set_remote("origin", "https://hub.oxen.ai//") repo.push() [​](https://docs.oxen.ai/python-api/repo#init) \_\_init\_\_ -------------------------------------------------------------- def __init__(path: str = "", mkdir=False) Create a new Repo object. Use .init() to initialize a new oxen repository, or pass the path to an existing one. **Arguments**: * `path` - `str` Path to the main working directory of your oxen repo. * `mkdir` - `bool` Whether to create the directory if one doesn’t exist. Default: False [​](https://docs.oxen.ai/python-api/repo#init-2) init -------------------------------------------------------- def init() Initializes a new oxen repository at the path specified in the constructor. Will create a .oxen folder to store all the versions and metadata. [​](https://docs.oxen.ai/python-api/repo#clone) clone -------------------------------------------------------- def clone(url: str, branch: str = "main", all=False) Clone repository from a remote url. **Arguments**: * `url` - `str` The url of the remote repository. ex) [https://hub.oxen.ai/ox/chatbot](https://hub.oxen.ai/ox/chatbot) * `branch` - `str` The name of the branch to clone. Default: main * `all` - `bool` Whether to clone the full commit history or not. Default: False [​](https://docs.oxen.ai/python-api/repo#branches) branches -------------------------------------------------------------- def branches() List all branches for a repo [​](https://docs.oxen.ai/python-api/repo#branch) branch ---------------------------------------------------------- def branch(name: str, delete=False) [​](https://docs.oxen.ai/python-api/repo#checkout) checkout -------------------------------------------------------------- def checkout(revision: str, create=False) Checkout a branch or commit id. **Arguments**: * `revision` - `str` The name of the branch or commit id to checkout. * `create` - `bool` Whether to create a new branch if it doesn’t exist. Default: False [​](https://docs.oxen.ai/python-api/repo#add) add ---------------------------------------------------- def add(path: str) Stage a file or directory to be committed. [​](https://docs.oxen.ai/python-api/repo#add-schema-metadata) add\_schema\_metadata -------------------------------------------------------------------------------------- def add_schema_metadata(path: str, column_name: str, metadata: str) Add schema to the local repository [​](https://docs.oxen.ai/python-api/repo#rm) rm -------------------------------------------------- def rm(path: str, recursive=False, staged=False) Remove a file or directory from being tracked. This will not delete the file or directory. **Arguments**: * `path` - `str` The path to the file or directory to remove. * `recursive` - `bool` Whether to remove the file or directory recursively. Default: False * `staged` - `bool` Whether to remove the file or directory from the staging area. * `Default` - False * `remote` - `bool` Whether to remove the file or directory from a remote workspace. * `Default` - False [​](https://docs.oxen.ai/python-api/repo#status) status ---------------------------------------------------------- def status() Check the status of the repo. Returns a StagedData object. [​](https://docs.oxen.ai/python-api/repo#commit) commit ---------------------------------------------------------- def commit(message: str) Commit the staged data in a repo with a message. **Arguments**: * `message` - `str` The commit message. [​](https://docs.oxen.ai/python-api/repo#log) log ---------------------------------------------------- def log() Get the commit history for a repo. [​](https://docs.oxen.ai/python-api/repo#set-remote) set\_remote ------------------------------------------------------------------- def set_remote(name: str, url: str) Map a name to a remote url. **Arguments**: * `name` - `str` The name of the remote. Ex) origin * `url` - `str` The url you want to map the name to. Ex) [https://hub.oxen.ai/ox/chatbot](https://hub.oxen.ai/ox/chatbot) [​](https://docs.oxen.ai/python-api/repo#push) push ------------------------------------------------------ def push(remote_name: str = "origin", branch: str = "main", delete: bool = False) Push data to a remote repo from a local repo. **Arguments**: * `remote_name` - `str` The name of the remote to push to. * `branch` - `str` The name of the branch to push to. [​](https://docs.oxen.ai/python-api/repo#pull) pull ------------------------------------------------------ def pull(remote_name: str = "origin", branch: str = "main", all=False) Pull data from a remote repo to a local repo. **Arguments**: * `remote_name` - `str` The name of the remote to pull from. * `branch` - `str` The name of the branch to pull from. * `all` - `bool` Whether to pull all data from branch history or not. Default: False [​](https://docs.oxen.ai/python-api/repo#path) path ------------------------------------------------------ @property def path() Returns the path to the repo. [​](https://docs.oxen.ai/python-api/repo#current-branch) current\_branch --------------------------------------------------------------------------- @property def current_branch() Returns the current branch. [​](https://docs.oxen.ai/python-api/repo#merge) merge -------------------------------------------------------- def merge(branch: str) Merge a branch into the current branch. [Remote repo](https://docs.oxen.ai/python-api/remote_repo) [Repositories](https://docs.oxen.ai/python-api/repositories) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Edit image - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/fine-tuning-api/edit-image#content-area) Edit image cURL curl --request POST \ --url https://hub.oxen.ai/api/ai/images/edit \ --header 'Content-Type: application/json' \ --data ' { "image": "", "model": "", "prompt": "", "mask": "", "n": 1, "size": "" } ' 200 400 { "created": 123, "images": [\ {\ "revised_prompt": "",\ "url": ""\ }\ ], "model": "" } POST / api / ai / images / edit Try it Edit image cURL curl --request POST \ --url https://hub.oxen.ai/api/ai/images/edit \ --header 'Content-Type: application/json' \ --data ' { "image": "", "model": "", "prompt": "", "mask": "", "n": 1, "size": "" } ' 200 400 { "created": 123, "images": [\ {\ "revised_prompt": "",\ "url": ""\ }\ ], "model": "" } #### Body application/json Image edit request [​](https://docs.oxen.ai/fine-tuning-api/edit-image#body-image) image string required URL of the source image [​](https://docs.oxen.ai/fine-tuning-api/edit-image#body-model) model string required [​](https://docs.oxen.ai/fine-tuning-api/edit-image#body-prompt) prompt string required Text instruction for the edit [​](https://docs.oxen.ai/fine-tuning-api/edit-image#body-mask-one-of-0) mask string | null URL of the mask image [​](https://docs.oxen.ai/fine-tuning-api/edit-image#body-n) n integer default:1 [​](https://docs.oxen.ai/fine-tuning-api/edit-image#body-size-one-of-0) size string | null #### Response 200 application/json Edited images [​](https://docs.oxen.ai/fine-tuning-api/edit-image#response-created) created integer [​](https://docs.oxen.ai/fine-tuning-api/edit-image#response-images) images object\[\] Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/edit-image#response-model) model string [Get generation details](https://docs.oxen.ai/fine-tuning-api/get-generation-details) [Generate image](https://docs.oxen.ai/fine-tuning-api/generate-image) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Create chat completion - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/fine-tuning-api/create-chat-completion#content-area) Create chat completion cURL curl --request POST \ --url https://hub.oxen.ai/api/ai/chat/completions \ --header 'Content-Type: application/json' \ --data ' { "messages": [\ {\ "content": "",\ "name": "",\ "tool_call_id": "",\ "tool_calls": [\ {}\ ]\ }\ ], "model": "gpt-4o", "frequency_penalty": 123, "max_tokens": 123, "presence_penalty": 123, "response_format": {}, "temperature": 123, "tool_choice": "", "tools": [\ {}\ ], "top_p": 123 } ' 200 400 { "choices": [\ {\ "finish_reason": "",\ "index": 123,\ "message": {\ "content": "",\ "role": "",\ "tool_calls": [\ {}\ ]\ }\ }\ ], "created": 123, "id": "", "model": "", "usage": { "completion_tokens": 123, "prompt_tokens": 123, "total_tokens": 123 } } POST / api / ai / chat / completions Try it Create chat completion cURL curl --request POST \ --url https://hub.oxen.ai/api/ai/chat/completions \ --header 'Content-Type: application/json' \ --data ' { "messages": [\ {\ "content": "",\ "name": "",\ "tool_call_id": "",\ "tool_calls": [\ {}\ ]\ }\ ], "model": "gpt-4o", "frequency_penalty": 123, "max_tokens": 123, "presence_penalty": 123, "response_format": {}, "temperature": 123, "tool_choice": "", "tools": [\ {}\ ], "top_p": 123 } ' 200 400 { "choices": [\ {\ "finish_reason": "",\ "index": 123,\ "message": {\ "content": "",\ "role": "",\ "tool_calls": [\ {}\ ]\ }\ }\ ], "created": 123, "id": "", "model": "", "usage": { "completion_tokens": 123, "prompt_tokens": 123, "total_tokens": 123 } } #### Body application/json Chat completion request Request to generate a chat completion. Compatible with the OpenAI chat completions API. [​](https://docs.oxen.ai/fine-tuning-api/create-chat-completion#body-messages) messages object\[\] required Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/create-chat-completion#body-model) model string required Model ID to use Example: `"gpt-4o"` [​](https://docs.oxen.ai/fine-tuning-api/create-chat-completion#body-frequency-penalty-one-of-0) frequency\_penalty number | null [​](https://docs.oxen.ai/fine-tuning-api/create-chat-completion#body-max-tokens-one-of-0) max\_tokens integer | null [​](https://docs.oxen.ai/fine-tuning-api/create-chat-completion#body-presence-penalty-one-of-0) presence\_penalty number | null [​](https://docs.oxen.ai/fine-tuning-api/create-chat-completion#body-response-format-one-of-0) response\_format object [​](https://docs.oxen.ai/fine-tuning-api/create-chat-completion#body-temperature-one-of-0) temperature number | null [​](https://docs.oxen.ai/fine-tuning-api/create-chat-completion#body-tool-choice-one-of-0) tool\_choice stringobjectstringobject [​](https://docs.oxen.ai/fine-tuning-api/create-chat-completion#body-tools-one-of-0) tools object\[\] | null [​](https://docs.oxen.ai/fine-tuning-api/create-chat-completion#body-top-p-one-of-0) top\_p number | null #### Response 200 application/json Chat completion [​](https://docs.oxen.ai/fine-tuning-api/create-chat-completion#response-choices) choices object\[\] Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/create-chat-completion#response-created) created integer [​](https://docs.oxen.ai/fine-tuning-api/create-chat-completion#response-id) id string [​](https://docs.oxen.ai/fine-tuning-api/create-chat-completion#response-model) model string [​](https://docs.oxen.ai/fine-tuning-api/create-chat-completion#response-object) object enum Available options: `chat.completion` [​](https://docs.oxen.ai/fine-tuning-api/create-chat-completion#response-usage-one-of-0) usage object Show child attributes [Parameter Guide](https://docs.oxen.ai/fine-tuning-api/parameters) [List past generations](https://docs.oxen.ai/fine-tuning-api/list-past-generations) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Enqueue generation - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/fine-tuning-api/enqueue-generation#content-area) Enqueue generation cURL curl --request POST \ --url https://hub.oxen.ai/api/ai/queue \ --header 'Content-Type: application/json' \ --data ' { "model": "", "prompt": "", "aspect_ratio": "", "duration": 123, "num_generations": 1, "seed": 123, "target_directory": "", "target_namespace": "", "target_repo": "" } ' 200 400 { "generations": [\ {\ "generation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"\ }\ ] } POST / api / ai / queue Try it Enqueue generation cURL curl --request POST \ --url https://hub.oxen.ai/api/ai/queue \ --header 'Content-Type: application/json' \ --data ' { "model": "", "prompt": "", "aspect_ratio": "", "duration": 123, "num_generations": 1, "seed": 123, "target_directory": "", "target_namespace": "", "target_repo": "" } ' 200 400 { "generations": [\ {\ "generation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"\ }\ ] } #### Body application/json Queue request Enqueue an async image or video generation job. [​](https://docs.oxen.ai/fine-tuning-api/enqueue-generation#body-model) model string required Model ID to use [​](https://docs.oxen.ai/fine-tuning-api/enqueue-generation#body-prompt) prompt string required Text prompt for generation [​](https://docs.oxen.ai/fine-tuning-api/enqueue-generation#body-aspect-ratio-one-of-0) aspect\_ratio string | null [​](https://docs.oxen.ai/fine-tuning-api/enqueue-generation#body-duration-one-of-0) duration integer | null [​](https://docs.oxen.ai/fine-tuning-api/enqueue-generation#body-num-generations) num\_generations integer default:1 Required range: `1 <= x <= 12` [​](https://docs.oxen.ai/fine-tuning-api/enqueue-generation#body-seed-one-of-0) seed integer | null [​](https://docs.oxen.ai/fine-tuning-api/enqueue-generation#body-target-directory-one-of-0) target\_directory string | null [​](https://docs.oxen.ai/fine-tuning-api/enqueue-generation#body-target-namespace-one-of-0) target\_namespace string | null Namespace to store results. Defaults to current user. [​](https://docs.oxen.ai/fine-tuning-api/enqueue-generation#body-target-repo-one-of-0) target\_repo string | null #### Response 200 application/json Generation enqueued [​](https://docs.oxen.ai/fine-tuning-api/enqueue-generation#response-generations) generations object\[\] required Show child attributes [List in-flight queue items](https://docs.oxen.ai/fine-tuning-api/list-in-flight-queue-items) [Get generation status](https://docs.oxen.ai/fine-tuning-api/get-generation-status) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Get a fine-tune job - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/fine-tuning-api/fine_tunes/get-a-fine-tune-job#content-area) Get a fine-tune job cURL curl --request GET \ --url https://hub.oxen.ai/api/repos/{namespace}/{repo_name}/fine_tunes/{id} \ --header 'Authorization: Bearer ' 200 404 { "fine_tune": { "base_model": "", "created_at": "", "id": "", "name": "", "status": "", "updated_at": "" }, "status": "", "status_message": "" } GET / api / repos / {namespace} / {repo\_name} / fine\_tunes / {id} Try it Get a fine-tune job cURL curl --request GET \ --url https://hub.oxen.ai/api/repos/{namespace}/{repo_name}/fine_tunes/{id} \ --header 'Authorization: Bearer ' 200 404 { "fine_tune": { "base_model": "", "created_at": "", "id": "", "name": "", "status": "", "updated_at": "" }, "status": "", "status_message": "" } #### Authorizations [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/get-a-fine-tune-job#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/get-a-fine-tune-job#parameter-id) id string required Fine-tune ID #### Response 200 application/json Fine-tune response Standard wrapper for fine-tune responses. [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/get-a-fine-tune-job#response-fine-tune) fine\_tune FineTune Β· object Fine-tune job resource Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/get-a-fine-tune-job#response-status) status string High-level status string (for example, 'success'). [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/get-a-fine-tune-job#response-status-message) status\_message string Human-readable status message (for example, 'resource\_found'). [Create a fine-tune job](https://docs.oxen.ai/fine-tuning-api/fine_tunes/create-a-fine-tune-job) [Delete a fine-tune job](https://docs.oxen.ai/fine-tuning-api/fine_tunes/delete-a-fine-tune-job) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Favorite a model - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/fine-tuning-api/favorite-a-model#content-area) Favorite a model cURL curl --request POST \ --url https://hub.oxen.ai/api/ai/models/{id}/favorite 200 { "created": 123, "id": "", "owned_by": "", "capabilities": { "input": [\ ""\ ], "output": [\ ""\ ] }, "deployments": [\ {}\ ], "description": "", "developer": { "logo": "", "name": "" }, "display_name": "", "fine_tuning": { "actions": [\ ""\ ], "cost_per_second": 123 }, "image_url": "", "pricing": { "cost_per_image": 123, "cost_per_second": 123, "cost_per_second_high_res": 123, "cost_per_second_with_audio": 123, "input_cost_per_token": 123, "output_cost_per_token": 123 }, "released_at": "", "request_schema": {}, "showcase": { "gallery": [\ {\ "alt": "",\ "src": "",\ "category": "",\ "details": "",\ "prompt": "",\ "title": ""\ }\ ], "hero_image": "", "tagline": "" }, "source_model": "", "summary": "" } POST / api / ai / models / {id} / favorite Try it Favorite a model cURL curl --request POST \ --url https://hub.oxen.ai/api/ai/models/{id}/favorite 200 { "created": 123, "id": "", "owned_by": "", "capabilities": { "input": [\ ""\ ], "output": [\ ""\ ] }, "deployments": [\ {}\ ], "description": "", "developer": { "logo": "", "name": "" }, "display_name": "", "fine_tuning": { "actions": [\ ""\ ], "cost_per_second": 123 }, "image_url": "", "pricing": { "cost_per_image": 123, "cost_per_second": 123, "cost_per_second_high_res": 123, "cost_per_second_with_audio": 123, "input_cost_per_token": 123, "output_cost_per_token": 123 }, "released_at": "", "request_schema": {}, "showcase": { "gallery": [\ {\ "alt": "",\ "src": "",\ "category": "",\ "details": "",\ "prompt": "",\ "title": ""\ }\ ], "hero_image": "", "tagline": "" }, "source_model": "", "summary": "" } #### Path Parameters [​](https://docs.oxen.ai/fine-tuning-api/favorite-a-model#parameter-id) id string required #### Response 200 - application/json Model favorited Represents a model available for inference or fine-tuning. Compatible with the OpenAI model object. [​](https://docs.oxen.ai/fine-tuning-api/favorite-a-model#response-created) created integer required Unix timestamp when the model was registered [​](https://docs.oxen.ai/fine-tuning-api/favorite-a-model#response-id) id string required Model identifier used in API calls [​](https://docs.oxen.ai/fine-tuning-api/favorite-a-model#response-object) object enum required Available options: `model` [​](https://docs.oxen.ai/fine-tuning-api/favorite-a-model#response-owned-by) owned\_by string required "oxen" for base models, owner namespace for custom models [​](https://docs.oxen.ai/fine-tuning-api/favorite-a-model#response-capabilities) capabilities object Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/favorite-a-model#response-deployments) deployments object\[\] Active deployments. Empty for base models. Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/favorite-a-model#response-description-one-of-0) description string | null [​](https://docs.oxen.ai/fine-tuning-api/favorite-a-model#response-developer-one-of-0) developer object Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/favorite-a-model#response-display-name) display\_name string [​](https://docs.oxen.ai/fine-tuning-api/favorite-a-model#response-endpoint) endpoint enum API endpoint to call this model Available options: `/chat/completions`, `/images/generate`, `/videos/generate` [​](https://docs.oxen.ai/fine-tuning-api/favorite-a-model#response-fine-tuning-one-of-0) fine\_tuning object Fine-tuning info, or null if model is not fine-tuneable Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/favorite-a-model#response-image-url-one-of-0) image\_url string | null [​](https://docs.oxen.ai/fine-tuning-api/favorite-a-model#response-model-type) model\_type enum Available options: `base`, `custom` [​](https://docs.oxen.ai/fine-tuning-api/favorite-a-model#response-pricing) pricing object Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/favorite-a-model#response-released-at-one-of-0) released\_at string | null [​](https://docs.oxen.ai/fine-tuning-api/favorite-a-model#response-request-schema-one-of-0) request\_schema object JSON Schema describing model-specific parameters [​](https://docs.oxen.ai/fine-tuning-api/favorite-a-model#response-showcase-one-of-0) showcase object Optional marketing content rendered on the public model showcase page Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/favorite-a-model#response-source-model-one-of-0) source\_model string | null Base model this was fine-tuned from [​](https://docs.oxen.ai/fine-tuning-api/favorite-a-model#response-summary-one-of-0) summary string | null [Deactivate model deployment](https://docs.oxen.ai/fine-tuning-api/deactivate-model-deployment) [Unfavorite a model](https://docs.oxen.ai/fine-tuning-api/unfavorite-a-model) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Create an evaluation - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/fine-tuning-api/evaluations/create-an-evaluation#content-area) Create an evaluation cURL curl --request POST \ --url 'https://hub.oxen.ai/api/repos/{namespace}/{repo_name}/evaluations/*resource_path' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "model_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "prompt": "", "target_column": "", "auto_commit": false, "batch_size": 10, "commit_message": "", "is_sample": false, "name": "", "sample_count": 10, "target_branch": "", "target_path": "" } ' 200 400 { "evaluation": { "cancelled_at": "", "completed_at": "", "completion_tokens_used": 123, "created_by": { "id": "", "image": "", "name": "", "username": "" }, "credits_used": 123, "error_message": "", "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "inserted_at": "", "is_sample": true, "model": {}, "name": "", "progress": { "processed": 123, "total": 123 }, "prompt": "", "prompt_tokens_used": 123, "repository_id": "", "resource": { "path": "", "version": "" }, "sample_count": 123, "started_at": "", "target_branch": "", "target_column": "", "target_path": "", "tokens_used": 123 }, "status": "", "status_message": "" } POST / api / repos / {namespace} / {repo\_name} / evaluations / \*resource\_path Try it Create an evaluation cURL curl --request POST \ --url 'https://hub.oxen.ai/api/repos/{namespace}/{repo_name}/evaluations/*resource_path' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "model_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "prompt": "", "target_column": "", "auto_commit": false, "batch_size": 10, "commit_message": "", "is_sample": false, "name": "", "sample_count": 10, "target_branch": "", "target_path": "" } ' 200 400 { "evaluation": { "cancelled_at": "", "completed_at": "", "completion_tokens_used": 123, "created_by": { "id": "", "image": "", "name": "", "username": "" }, "credits_used": 123, "error_message": "", "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "inserted_at": "", "is_sample": true, "model": {}, "name": "", "progress": { "processed": 123, "total": 123 }, "prompt": "", "prompt_tokens_used": 123, "repository_id": "", "resource": { "path": "", "version": "" }, "sample_count": 123, "started_at": "", "target_branch": "", "target_column": "", "target_path": "", "tokens_used": 123 }, "status": "", "status_message": "" } #### Authorizations [​](https://docs.oxen.ai/fine-tuning-api/evaluations/create-an-evaluation#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Body application/json Create evaluation request Request payload to create an evaluation. The resource path (branch + file path) is specified in the URL after `/evaluations/`, for example: `POST /api/repos/{namespace}/{repo}/evaluations/main/datasets/training.parquet`. [​](https://docs.oxen.ai/fine-tuning-api/evaluations/create-an-evaluation#body-input-type) input\_type enum required Type of input data Available options: `text`, `image`, `video` [​](https://docs.oxen.ai/fine-tuning-api/evaluations/create-an-evaluation#body-model-id) model\_id string required ID of the model to run inference with [​](https://docs.oxen.ai/fine-tuning-api/evaluations/create-an-evaluation#body-output-type) output\_type enum required Type of output produced by the model Available options: `text`, `image`, `video`, `embeddings` [​](https://docs.oxen.ai/fine-tuning-api/evaluations/create-an-evaluation#body-prompt) prompt string required Prompt template sent to the model. Use `{column_name}` placeholders to inject values from each row. [​](https://docs.oxen.ai/fine-tuning-api/evaluations/create-an-evaluation#body-target-column) target\_column string required Column where the model output will be written [​](https://docs.oxen.ai/fine-tuning-api/evaluations/create-an-evaluation#body-auto-commit) auto\_commit boolean default:false If true, automatically commit the results when the evaluation completes [​](https://docs.oxen.ai/fine-tuning-api/evaluations/create-an-evaluation#body-batch-size) batch\_size integer default:10 Number of rows to process per inference batch [​](https://docs.oxen.ai/fine-tuning-api/evaluations/create-an-evaluation#body-commit-message-one-of-0) commit\_message string | null Commit message used when auto\_commit is true [​](https://docs.oxen.ai/fine-tuning-api/evaluations/create-an-evaluation#body-is-sample) is\_sample boolean default:false If true, only evaluate a subset of rows. If false, evaluate all rows. [​](https://docs.oxen.ai/fine-tuning-api/evaluations/create-an-evaluation#body-name) name string Human-readable name for the evaluation [​](https://docs.oxen.ai/fine-tuning-api/evaluations/create-an-evaluation#body-sample-count) sample\_count integer default:10 Number of rows to sample when is\_sample is true [​](https://docs.oxen.ai/fine-tuning-api/evaluations/create-an-evaluation#body-target-branch) target\_branch string Branch where evaluation results are committed [​](https://docs.oxen.ai/fine-tuning-api/evaluations/create-an-evaluation#body-target-path) target\_path string File path for the output data frame #### Response 200 application/json Evaluation created Standard response wrapper for a single evaluation. [​](https://docs.oxen.ai/fine-tuning-api/evaluations/create-an-evaluation#response-evaluation) evaluation Evaluation Β· object Evaluation resource Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/evaluations/create-an-evaluation#response-status) status string High-level status string (for example, 'success'). [​](https://docs.oxen.ai/fine-tuning-api/evaluations/create-an-evaluation#response-status-message) status\_message string Human-readable status message (for example, 'resource\_found'). [List fine-tunes for a user](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-fine-tunes-for-a-user) [Get evaluation status](https://docs.oxen.ai/fine-tuning-api/evaluations/get-evaluation-status) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Create a fine-tune job - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/fine-tuning-api/fine_tunes/create-a-fine-tune-job#content-area) Create a fine-tune job cURL curl --request POST \ --url https://hub.oxen.ai/api/repos/{namespace}/{repo_name}/fine_tunes \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "base_model": "", "resource": "", "script_type": "", "is_public": false, "oxen_model_path": "", "training_params": { "batch_size": 123, "caption_column": "", "gradient_accumulation": 123, "image_column": "", "learning_rate": 123, "lora_alpha": 123, "lora_rank": 123, "sample_every": 123, "samples": 123, "steps": 123, "timestep_type": "", "use_lora": true } } ' 201 400 { "fine_tune": { "base_model": "", "created_at": "", "id": "", "name": "", "status": "", "updated_at": "" }, "status": "", "status_message": "" } POST / api / repos / {namespace} / {repo\_name} / fine\_tunes Try it Create a fine-tune job cURL curl --request POST \ --url https://hub.oxen.ai/api/repos/{namespace}/{repo_name}/fine_tunes \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "base_model": "", "resource": "", "script_type": "", "is_public": false, "oxen_model_path": "", "training_params": { "batch_size": 123, "caption_column": "", "gradient_accumulation": 123, "image_column": "", "learning_rate": 123, "lora_alpha": 123, "lora_rank": 123, "sample_every": 123, "samples": 123, "steps": 123, "timestep_type": "", "use_lora": true } } ' 201 400 { "fine_tune": { "base_model": "", "created_at": "", "id": "", "name": "", "status": "", "updated_at": "" }, "status": "", "status_message": "" } #### Authorizations [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/create-a-fine-tune-job#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Body application/json Create fine-tune request Request payload to create a fine-tune job for a repository. [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/create-a-fine-tune-job#body-base-model) base\_model string required Canonical name of the base model to fine-tune [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/create-a-fine-tune-job#body-resource) resource string required Repository path to the training data file or directory [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/create-a-fine-tune-job#body-script-type) script\_type string required Name of the fine-tune script to run [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/create-a-fine-tune-job#body-is-public) is\_public boolean default:false Whether the resulting fine-tuned model should be public. Defaults to false. [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/create-a-fine-tune-job#body-oxen-model-path-one-of-0) oxen\_model\_path string | null Optional override for where the resulting model weights live in Oxen. Defaults to the fine-tune resource. [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/create-a-fine-tune-job#body-training-params) training\_params object Training configuration parameters Show child attributes #### Response 201 application/json Create fine-tune response Standard wrapper for fine-tune responses. [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/create-a-fine-tune-job#response-fine-tune) fine\_tune FineTune Β· object Fine-tune job resource Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/create-a-fine-tune-job#response-status) status string High-level status string (for example, 'success'). [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/create-a-fine-tune-job#response-status-message) status\_message string Human-readable status message (for example, 'resource\_found'). [List fine-tunes in a repository](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-fine-tunes-in-a-repository) [Get a fine-tune job](https://docs.oxen.ai/fine-tuning-api/fine_tunes/get-a-fine-tune-job) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Delete a fine-tune job - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/fine-tuning-api/fine_tunes/delete-a-fine-tune-job#content-area) Delete a fine-tune job cURL curl --request DELETE \ --url https://hub.oxen.ai/api/repos/{namespace}/{repo_name}/fine_tunes/{id} \ --header 'Authorization: Bearer ' 200 404 { "fine_tune": { "base_model": "", "created_at": "", "id": "", "name": "", "status": "", "updated_at": "" }, "status": "", "status_message": "" } DELETE / api / repos / {namespace} / {repo\_name} / fine\_tunes / {id} Try it Delete a fine-tune job cURL curl --request DELETE \ --url https://hub.oxen.ai/api/repos/{namespace}/{repo_name}/fine_tunes/{id} \ --header 'Authorization: Bearer ' 200 404 { "fine_tune": { "base_model": "", "created_at": "", "id": "", "name": "", "status": "", "updated_at": "" }, "status": "", "status_message": "" } #### Authorizations [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/delete-a-fine-tune-job#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/delete-a-fine-tune-job#parameter-id) id string required Fine-tune ID #### Response 200 application/json Deleted fine-tune response Standard wrapper for fine-tune responses. [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/delete-a-fine-tune-job#response-fine-tune) fine\_tune FineTune Β· object Fine-tune job resource Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/delete-a-fine-tune-job#response-status) status string High-level status string (for example, 'success'). [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/delete-a-fine-tune-job#response-status-message) status\_message string Human-readable status message (for example, 'resource\_found'). [Get a fine-tune job](https://docs.oxen.ai/fine-tuning-api/fine_tunes/get-a-fine-tune-job) [Update a fine-tune job](https://docs.oxen.ai/fine-tuning-api/fine_tunes/update-a-fine-tune-job) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Get evaluation status - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/fine-tuning-api/evaluations/get-evaluation-status#content-area) Get evaluation status cURL curl --request GET \ --url https://hub.oxen.ai/api/repos/{namespace}/{repo_name}/evaluations/{evaluation_id} \ --header 'Authorization: Bearer ' 200 404 { "evaluation": { "cancelled_at": "", "completed_at": "", "completion_tokens_used": 123, "created_by": { "id": "", "image": "", "name": "", "username": "" }, "credits_used": 123, "error_message": "", "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "inserted_at": "", "is_sample": true, "model": {}, "name": "", "progress": { "processed": 123, "total": 123 }, "prompt": "", "prompt_tokens_used": 123, "repository_id": "", "resource": { "path": "", "version": "" }, "sample_count": 123, "started_at": "", "target_branch": "", "target_column": "", "target_path": "", "tokens_used": 123 }, "status": "", "status_message": "" } GET / api / repos / {namespace} / {repo\_name} / evaluations / {evaluation\_id} Try it Get evaluation status cURL curl --request GET \ --url https://hub.oxen.ai/api/repos/{namespace}/{repo_name}/evaluations/{evaluation_id} \ --header 'Authorization: Bearer ' 200 404 { "evaluation": { "cancelled_at": "", "completed_at": "", "completion_tokens_used": 123, "created_by": { "id": "", "image": "", "name": "", "username": "" }, "credits_used": 123, "error_message": "", "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "inserted_at": "", "is_sample": true, "model": {}, "name": "", "progress": { "processed": 123, "total": 123 }, "prompt": "", "prompt_tokens_used": 123, "repository_id": "", "resource": { "path": "", "version": "" }, "sample_count": 123, "started_at": "", "target_branch": "", "target_column": "", "target_path": "", "tokens_used": 123 }, "status": "", "status_message": "" } #### Authorizations [​](https://docs.oxen.ai/fine-tuning-api/evaluations/get-evaluation-status#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://docs.oxen.ai/fine-tuning-api/evaluations/get-evaluation-status#parameter-evaluation-id) evaluation\_id string required Evaluation ID #### Response 200 application/json Evaluation details Standard response wrapper for a single evaluation. [​](https://docs.oxen.ai/fine-tuning-api/evaluations/get-evaluation-status#response-evaluation) evaluation Evaluation Β· object Evaluation resource Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/evaluations/get-evaluation-status#response-status) status string High-level status string (for example, 'success'). [​](https://docs.oxen.ai/fine-tuning-api/evaluations/get-evaluation-status#response-status-message) status\_message string Human-readable status message (for example, 'resource\_found'). [Create an evaluation](https://docs.oxen.ai/fine-tuning-api/evaluations/create-an-evaluation) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Get logs for a fine-tune job - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/fine-tuning-api/fine_tunes/get-logs-for-a-fine-tune-job#content-area) Get logs for a fine-tune job cURL curl --request GET \ --url https://hub.oxen.ai/api/repos/{namespace}/{repo_name}/fine_tunes/{id}/logs \ --header 'Authorization: Bearer ' 200 404 {} GET / api / repos / {namespace} / {repo\_name} / fine\_tunes / {id} / logs Try it Get logs for a fine-tune job cURL curl --request GET \ --url https://hub.oxen.ai/api/repos/{namespace}/{repo_name}/fine_tunes/{id}/logs \ --header 'Authorization: Bearer ' 200 404 {} #### Authorizations [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/get-logs-for-a-fine-tune-job#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/get-logs-for-a-fine-tune-job#parameter-id) id string required Fine-tune ID #### Response 200 application/json Fine-tune logs response Fine-tune log payload [Deploy a checkpoint from a fine-tune job](https://docs.oxen.ai/fine-tuning-api/fine_tunes/deploy-a-checkpoint-from-a-fine-tune-job) [Tokenize data for a fine-tune job](https://docs.oxen.ai/fine-tuning-api/fine_tunes/tokenize-data-for-a-fine-tune-job) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Get training status for a fine-tune job - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/fine-tuning-api/fine_tunes/get-training-status-for-a-fine-tune-job#content-area) Get training status for a fine-tune job cURL curl --request GET \ --url https://hub.oxen.ai/api/repos/{namespace}/{repo_name}/fine_tunes/{id}/train_status \ --header 'Authorization: Bearer ' 200 404 {} GET / api / repos / {namespace} / {repo\_name} / fine\_tunes / {id} / train\_status Try it Get training status for a fine-tune job cURL curl --request GET \ --url https://hub.oxen.ai/api/repos/{namespace}/{repo_name}/fine_tunes/{id}/train_status \ --header 'Authorization: Bearer ' 200 404 {} #### Authorizations [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/get-training-status-for-a-fine-tune-job#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/get-training-status-for-a-fine-tune-job#parameter-id) id string required Fine-tune ID #### Response 200 application/json Training status response Training status information [Tokenize data for a fine-tune job](https://docs.oxen.ai/fine-tuning-api/fine_tunes/tokenize-data-for-a-fine-tune-job) [Update training status for a fine-tune job](https://docs.oxen.ai/fine-tuning-api/fine_tunes/update-training-status-for-a-fine-tune-job) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Remote repo - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/python-api/remote_repo#content-area) [​](https://docs.oxen.ai/python-api/remote_repo#oxen-remote-repo) oxen.remote\_repo ====================================================================================== [​](https://docs.oxen.ai/python-api/remote_repo#get-repo) get\_repo ---------------------------------------------------------------------- def get_repo(name: str, host: str = "hub.oxen.ai", scheme: str = "https") Get a RemoteRepo object for the specified name. For example β€˜ox/CatDogBBox’. **Arguments**: * `name` - `str` Name of the repository in the format β€˜namespace/repo\_name’. * `host` - `str` The host to connect to. Defaults to β€˜hub.oxen.ai’ **Returns**: [RemoteRepo](https://docs.oxen.ai/python-api/remote_repo) [​](https://docs.oxen.ai/python-api/remote_repo#create-repo) create\_repo ---------------------------------------------------------------------------- def create_repo(name: str, description="", is_public: bool = True, host: str = "hub.oxen.ai", scheme: str = "https", files: List[Tuple[str, str]] = []) Create a new repository on the remote server. **Arguments**: * `name` - `str` Name of the repository in the format β€˜namespace/repo\_name’. * `description` - `str` Description of the repository. Only applicable to [OxenHub](https://oxen.ai/) . * `is_public` - `bool` Whether the repository is public or private. Only applicable to [OxenHub](https://oxen.ai/) . * `host` - `str` The host to connect to. Defaults to β€˜hub.oxen.ai’ * `scheme` - `str` The scheme to use for the remote url. Default: β€˜https’ * `files` - `List[Tuple[str, str]]` A list of tuples containing the path to the file and the contents of the file that you would like to seed the repository with. **Returns**: [RemoteRepo](https://docs.oxen.ai/python-api/remote_repo) [​](https://docs.oxen.ai/python-api/remote_repo#remoterepo-objects) RemoteRepo Objects ----------------------------------------------------------------------------------------- class RemoteRepo() The RemoteRepo class allows you to interact with an Oxen repository without downloading the data locally. [​](https://docs.oxen.ai/python-api/remote_repo#examples) Examples --------------------------------------------------------------------- ### [​](https://docs.oxen.ai/python-api/remote_repo#add-&-commit-files) Add & Commit Files Adding and committing a file to a remote workspace. from oxen import RemoteRepo repo = RemoteRepo("ox/CatDogBBox") repo.add("/path/to/image.png") status = repo.status() print(status.added_files()) repo.commit("Adding my image to the remote workspace.") ### [​](https://docs.oxen.ai/python-api/remote_repo#downloading-specific-files) Downloading Specific Files Grab a specific file revision and load it into pandas. from oxen import RemoteRepo import pandas as pd # Connect to the remote repo repo = RemoteRepo("ox/CatDogBBox") # Specify the version of the file you want to download branch = repo.get_branch("my-pets") # Download takes a file or directory a commit id repo.download("annotations", revision=branch.commit_id) # Once you have the data locally, use whatever library you want to explore the data df = pd.read_csv("annotations/train.csv") print(df.head()) [​](https://docs.oxen.ai/python-api/remote_repo#init) \_\_init\_\_ --------------------------------------------------------------------- def __init__(repo_id: str, host: str = "hub.oxen.ai", revision: str = "main", scheme: str = "https") Create a new RemoteRepo object to interact with. **Arguments**: * `repo_id` - `str` Name of the repository in the format β€˜namespace/repo\_name’. For example β€˜ox/chatbot’ * `host` - `str` The host to connect to. Defaults to β€˜hub.oxen.ai’ * `revision` - `str` The branch name or commit id to checkout. Defaults to β€˜main’ * `scheme` - `str` The scheme to use for the remote url. Default: β€˜https’ [​](https://docs.oxen.ai/python-api/remote_repo#create) create ----------------------------------------------------------------- def create(empty: bool = False, is_public: bool = False) Will create the repo on the remote server. **Arguments**: * `empty` - `bool` Whether to create an empty repo or not. Default: False * `is_public` - `bool` Whether the repository is public or private. Default: False [​](https://docs.oxen.ai/python-api/remote_repo#exists) exists ----------------------------------------------------------------- def exists() -> bool Checks if this remote repo exists on the server. [​](https://docs.oxen.ai/python-api/remote_repo#delete) delete ----------------------------------------------------------------- def delete() Delete this remote repo from the server. [​](https://docs.oxen.ai/python-api/remote_repo#checkout) checkout --------------------------------------------------------------------- def checkout(revision: str, create=False) Switches the remote repo to the specified revision. **Arguments**: * `revision` - `str` The name of the branch or commit id to checkout. * `create` - `bool` Whether to create a new branch if it doesn’t exist. Default: False [​](https://docs.oxen.ai/python-api/remote_repo#ls) ls --------------------------------------------------------- def ls(directory: Optional[str] = None, page_num: int = 1, page_size: int = 100) Lists the contents of a directory in the remote repo. **Arguments**: * `directory` - `str` The directory to list. If None, will list the root directory. * `page_num` - `int` The page number to return. Default: 1 * `page_size` - `int` The number of items to return per page. Default: 100 [​](https://docs.oxen.ai/python-api/remote_repo#scan) scan ------------------------------------------------------------- def scan(directory: Optional[str] = None, page_size: int = 100) Generator over the contents of a directory in the remote repo **Arguments**: * `directory` - `str` The directory to list. If None, will list the root directory * `page_size` - `int` The number of items to return per page. Default: 100 [​](https://docs.oxen.ai/python-api/remote_repo#download) download --------------------------------------------------------------------- def download(src: str, dst: Optional[str] = None, revision: Optional[str] = None) Download a file or directory from the remote repo. **Arguments**: * `src` - `str` The path to the remote file * `dst` - `str | None` The path to the local file. If None, will download to the same path as `src` * `revision` - `str | None` The branch or commit id to download. Defaults to `self.revision` [​](https://docs.oxen.ai/python-api/remote_repo#add) add ----------------------------------------------------------- def add(src: str, dst: Optional[str] = "", branch: Optional[str] = None, workspace_name: Optional[str] = None) Stage a file to a workspace in the remote repo. **Arguments**: * `src` - `str` The path to the local file to upload * `dst` - `str | None` The directory to upload the file to. If None, will upload to the root directory. * `branch` - `str | None` The branch to upload the file to. Defaults to `self.revision` **Returns**: [Workspace](https://docs.oxen.ai/python-api/workspace) [​](https://docs.oxen.ai/python-api/remote_repo#status) status ----------------------------------------------------------------- def status() Get the status of the workspace. [​](https://docs.oxen.ai/python-api/remote_repo#commit) commit ----------------------------------------------------------------- def commit(message: str) Commit the workspace to the remote repo. [​](https://docs.oxen.ai/python-api/remote_repo#upload) upload ----------------------------------------------------------------- def upload(src: str, commit_message: str, file_name: Optional[str] = None, dst_dir: Optional[str] = "", branch: Optional[str] = None) Upload a file to the remote repo. **Arguments**: * `src` - `str` The path to the local file to upload * `file_name` - `str | None` The name of the file to upload. If None, will use the name of the file in `src` * `dst_dir` - `str | None` The directory to upload the file to. If None, will upload to the root directory. * `branch` - `str | None` The branch to upload the file to. Defaults to `self.revision` [​](https://docs.oxen.ai/python-api/remote_repo#metadata) metadata --------------------------------------------------------------------- def metadata(path: str) Get the metadata for a file in the remote repo. [​](https://docs.oxen.ai/python-api/remote_repo#file-exists) file\_exists ---------------------------------------------------------------------------- def file_exists(path: str, revision: str = None) Check if a file exists in the remote repo. **Arguments**: * `path` - `str` The path to the file to check * `revision` - `str` The revision to check against, defaults to `self.revision` [​](https://docs.oxen.ai/python-api/remote_repo#file-has-changes) file\_has\_changes --------------------------------------------------------------------------------------- def file_has_changes(local_path: str, remote_path: str = None, revision: str = None) Check if a local file has changed compared to a remote revision **Arguments**: * `local_path` - `str` The local path to the file to check * `remote_path` - `str` The remote path to the file to check, will default to `local_path` if not provided * `revision` - `str` The revision to check against, defaults to `self.revision` [​](https://docs.oxen.ai/python-api/remote_repo#log) log ----------------------------------------------------------- def log() Get the commit history for a remote repo [​](https://docs.oxen.ai/python-api/remote_repo#branch-exists) branch\_exists -------------------------------------------------------------------------------- def branch_exists(name: str) -> bool Check if a branch exists in the remote repo. **Arguments**: * `name` - `str` The name of the branch to check [​](https://docs.oxen.ai/python-api/remote_repo#branch) branch ----------------------------------------------------------------- def branch() Get the current branch for a remote repo [​](https://docs.oxen.ai/python-api/remote_repo#branches) branches --------------------------------------------------------------------- def branches() List all branches for a remote repo [​](https://docs.oxen.ai/python-api/remote_repo#list-workspaces) list\_workspaces ------------------------------------------------------------------------------------ def list_workspaces() List all workspaces for a remote repo [​](https://docs.oxen.ai/python-api/remote_repo#get-branch) get\_branch -------------------------------------------------------------------------- def get_branch(branch: str) Return a branch by name on this repo, if exists **Arguments**: * `branch` - `str` The name of the branch to return [​](https://docs.oxen.ai/python-api/remote_repo#create-branch) create\_branch -------------------------------------------------------------------------------- def create_branch(branch: str) Return a branch by name on this repo, creating it from the currently checked out branch if it doesn’t exist **Arguments**: * `branch` - `str` The name to assign to the created branch [​](https://docs.oxen.ai/python-api/remote_repo#create-checkout-branch) create\_checkout\_branch --------------------------------------------------------------------------------------------------- def create_checkout_branch(branch: str) Create a new branch from the currently checked out branch, and switch to it **Arguments**: * `branch` - `str` The name to assign to the created branch [​](https://docs.oxen.ai/python-api/remote_repo#merge) merge --------------------------------------------------------------- def merge(base_branch: str, head_branch: str) Merge the head branch into the base branch on the remote repo. **Arguments**: * `base_branch` - `str` The base branch to merge into * `head_branch` - `str` The head branch to merge [​](https://docs.oxen.ai/python-api/remote_repo#namespace) namespace ----------------------------------------------------------------------- @property def namespace() -> str The namespace for the repo. [​](https://docs.oxen.ai/python-api/remote_repo#name) name ------------------------------------------------------------- @property def name() -> str The name of the repo. [​](https://docs.oxen.ai/python-api/remote_repo#identifier) identifier ------------------------------------------------------------------------- @property def identifier() The namespace/name of the repo. [​](https://docs.oxen.ai/python-api/remote_repo#url) url ----------------------------------------------------------- @property def url() -> str The remote url for the repo. [​](https://docs.oxen.ai/python-api/remote_repo#revision) revision --------------------------------------------------------------------- @property def revision() -> str The branch or commit id for the repo [Oxen fs](https://docs.oxen.ai/python-api/oxen_fs) [Repo](https://docs.oxen.ai/python-api/repo) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Deploy a checkpoint from a fine-tune job - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/fine-tuning-api/fine_tunes/deploy-a-checkpoint-from-a-fine-tune-job#content-area) Deploy a checkpoint from a fine-tune job cURL curl --request POST \ --url https://hub.oxen.ai/api/repos/{namespace}/{repo_name}/fine_tunes/{id}/checkpoints/{step}/deploy \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "deployment_type": "normal" } ' 200 404 { "deployment_id": "", "fine_tune": { "base_model": "", "created_by": { "id": "", "image": "", "name": "", "username": "" }, "credits_used": "", "deployed_model": {}, "description": "", "display_name": "", "error": "", "fine_tune_script": { "description": "", "display_name": "", "docker_image_name": "", "fine_tune_schema": { "description": "", "id": "", "name": "", "schema": { "additionalProperties": true, "basic": [\ ""\ ], "properties": {}, "required": [\ ""\ ], "type": "" } }, "id": "", "name": "", "script_type": "" }, "finished_at": "", "gpu_count": 123, "gpu_model": "", "id": "", "inserted_at": "", "last_credit_check": "", "name": "", "output_resource": {}, "queue_position": 123, "rate_per_second": "", "repository_id": "", "resource": { "path": "", "version": "" }, "source_model": {}, "started_at": "", "status": "", "total_token_count": 0, "training_params": { "answer_column": "", "batch_size": 123, "enable_thinking": true, "epochs": 123, "grad_accum": 123, "learning_rate": 123, "logging_steps": 123, "lora_alpha": 123, "lora_rank": 123, "neftune_noise_alpha": 123, "question_column": "", "save_steps_ratio": 123, "save_strategy": "", "seq_length": 123, "use_lora": true }, "updated_at": "", "use_lora": true }, "model": {}, "status": "", "status_message": "" } POST / api / repos / {namespace} / {repo\_name} / fine\_tunes / {id} / checkpoints / {step} / deploy Try it Deploy a checkpoint from a fine-tune job cURL curl --request POST \ --url https://hub.oxen.ai/api/repos/{namespace}/{repo_name}/fine_tunes/{id}/checkpoints/{step}/deploy \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "deployment_type": "normal" } ' 200 404 { "deployment_id": "", "fine_tune": { "base_model": "", "created_by": { "id": "", "image": "", "name": "", "username": "" }, "credits_used": "", "deployed_model": {}, "description": "", "display_name": "", "error": "", "fine_tune_script": { "description": "", "display_name": "", "docker_image_name": "", "fine_tune_schema": { "description": "", "id": "", "name": "", "schema": { "additionalProperties": true, "basic": [\ ""\ ], "properties": {}, "required": [\ ""\ ], "type": "" } }, "id": "", "name": "", "script_type": "" }, "finished_at": "", "gpu_count": 123, "gpu_model": "", "id": "", "inserted_at": "", "last_credit_check": "", "name": "", "output_resource": {}, "queue_position": 123, "rate_per_second": "", "repository_id": "", "resource": { "path": "", "version": "" }, "source_model": {}, "started_at": "", "status": "", "total_token_count": 0, "training_params": { "answer_column": "", "batch_size": 123, "enable_thinking": true, "epochs": 123, "grad_accum": 123, "learning_rate": 123, "logging_steps": 123, "lora_alpha": 123, "lora_rank": 123, "neftune_noise_alpha": 123, "question_column": "", "save_steps_ratio": 123, "save_strategy": "", "seq_length": 123, "use_lora": true }, "updated_at": "", "use_lora": true }, "model": {}, "status": "", "status_message": "" } #### Authorizations [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/deploy-a-checkpoint-from-a-fine-tune-job#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/deploy-a-checkpoint-from-a-fine-tune-job#parameter-id) id string required Fine-tune ID [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/deploy-a-checkpoint-from-a-fine-tune-job#parameter-step) step integer required Checkpoint step number #### Query Parameters [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/deploy-a-checkpoint-from-a-fine-tune-job#parameter-retry) retry boolean If true, cleanup the existing deployment and model for this checkpoint before creating a new one. #### Body application/json Deployment configuration Request payload to deploy a specific checkpoint from a fine-tune job. [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/deploy-a-checkpoint-from-a-fine-tune-job#body-deployment-type) deployment\_type enum default:normal Deployment type: 'fast' for faster inference instances, 'normal' for standard instances. Available options: `fast`, `normal` #### Response 200 application/json Deployment created response Standard wrapper for checkpoint deployment responses. [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/deploy-a-checkpoint-from-a-fine-tune-job#response-deployment-id) deployment\_id string ID of the created Baseten deployment. [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/deploy-a-checkpoint-from-a-fine-tune-job#response-fine-tune) fine\_tune FineTuneRun Β· object Fine-tune job the deployed checkpoint belongs to. Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/deploy-a-checkpoint-from-a-fine-tune-job#response-model) model object Model record created for this checkpoint deployment. [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/deploy-a-checkpoint-from-a-fine-tune-job#response-status) status string High-level status string (for example, 'success'). [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/deploy-a-checkpoint-from-a-fine-tune-job#response-status-message) status\_message string Human-readable status message (for example, 'resource\_found'). [List checkpoints for a fine-tune job](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-checkpoints-for-a-fine-tune-job) [Get logs for a fine-tune job](https://docs.oxen.ai/fine-tuning-api/fine_tunes/get-logs-for-a-fine-tune-job) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # List fine-tunes for a user - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-fine-tunes-for-a-user#content-area) List fine-tunes for a user cURL curl --request GET \ --url https://hub.oxen.ai/api/users/{username}/fine_tunes \ --header 'Authorization: Bearer ' 200 401 404 { "fine_tunes": [\ {\ "base_model": "",\ "created_at": "",\ "id": "",\ "name": "",\ "status": "",\ "updated_at": ""\ }\ ], "status": "", "status_message": "" } GET / api / users / {username} / fine\_tunes Try it List fine-tunes for a user cURL curl --request GET \ --url https://hub.oxen.ai/api/users/{username}/fine_tunes \ --header 'Authorization: Bearer ' 200 401 404 { "fine_tunes": [\ {\ "base_model": "",\ "created_at": "",\ "id": "",\ "name": "",\ "status": "",\ "updated_at": ""\ }\ ], "status": "", "status_message": "" } #### Authorizations [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-fine-tunes-for-a-user#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-fine-tunes-for-a-user#parameter-username) username string required Username #### Query Parameters [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-fine-tunes-for-a-user#parameter-page) page integer Page number (1-indexed) [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-fine-tunes-for-a-user#parameter-page-size) page\_size integer Number of items per page [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-fine-tunes-for-a-user#parameter-search) search string Search across fine-tune name, display name, base model, and repository (case-insensitive substring match). For example: 'qwen', 'ox/Delorean', 'customer-support'. [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-fine-tunes-for-a-user#parameter-status) status string Filter by status. One of: created, tokenizing, enqueued, running, completed, stopped, errored, deployed [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-fine-tunes-for-a-user#parameter-created-by) created\_by string Filter by creator username (exact match) [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-fine-tunes-for-a-user#parameter-sort) sort string Sort order by creation date: 'newest' (default) or 'oldest' #### Response 200 application/json List fine-tunes response Standard wrapper for fine-tune list responses. [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-fine-tunes-for-a-user#response-fine-tunes) fine\_tunes FineTune Β· object\[\] List of fine-tune job resources Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-fine-tunes-for-a-user#response-status) status string High-level status string (for example, 'success'). [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-fine-tunes-for-a-user#response-status-message) status\_message string Human-readable status message (for example, 'resource\_found'). [List all fine-tunes accessible to the current user](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-all-fine-tunes-accessible-to-the-current-user) [Create an evaluation](https://docs.oxen.ai/fine-tuning-api/evaluations/create-an-evaluation) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Update training status for a fine-tune job - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/fine-tuning-api/fine_tunes/update-training-status-for-a-fine-tune-job#content-area) Update training status for a fine-tune job cURL curl --request PUT \ --url https://hub.oxen.ai/api/repos/{namespace}/{repo_name}/fine_tunes/{id}/train_status/{new_status} \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "new_status": "" } ' 200 404 {} PUT / api / repos / {namespace} / {repo\_name} / fine\_tunes / {id} / train\_status / {new\_status} Try it Update training status for a fine-tune job cURL curl --request PUT \ --url https://hub.oxen.ai/api/repos/{namespace}/{repo_name}/fine_tunes/{id}/train_status/{new_status} \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "new_status": "" } ' 200 404 {} #### Authorizations [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/update-training-status-for-a-fine-tune-job#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/update-training-status-for-a-fine-tune-job#parameter-id) id string required Fine-tune ID #### Body application/json Training status update [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/update-training-status-for-a-fine-tune-job#body-new-status) new\_status string required New training status #### Response 200 application/json Training status updated Updated training status [Get training status for a fine-tune job](https://docs.oxen.ai/fine-tuning-api/fine_tunes/get-training-status-for-a-fine-tune-job) [List all fine-tunes accessible to the current user](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-all-fine-tunes-accessible-to-the-current-user) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # List all fine-tunes accessible to the current user - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-all-fine-tunes-accessible-to-the-current-user#content-area) List all fine-tunes accessible to the current user cURL curl --request GET \ --url https://hub.oxen.ai/api/user/fine_tunes \ --header 'Authorization: Bearer ' 200 401 { "fine_tunes": [\ {\ "base_model": "",\ "created_at": "",\ "id": "",\ "name": "",\ "status": "",\ "updated_at": ""\ }\ ], "status": "", "status_message": "" } GET / api / user / fine\_tunes Try it List all fine-tunes accessible to the current user cURL curl --request GET \ --url https://hub.oxen.ai/api/user/fine_tunes \ --header 'Authorization: Bearer ' 200 401 { "fine_tunes": [\ {\ "base_model": "",\ "created_at": "",\ "id": "",\ "name": "",\ "status": "",\ "updated_at": ""\ }\ ], "status": "", "status_message": "" } #### Authorizations [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-all-fine-tunes-accessible-to-the-current-user#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Query Parameters [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-all-fine-tunes-accessible-to-the-current-user#parameter-page) page integer Page number (1-indexed) [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-all-fine-tunes-accessible-to-the-current-user#parameter-page-size) page\_size integer Number of items per page [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-all-fine-tunes-accessible-to-the-current-user#parameter-search) search string Search across fine-tune name, display name, base model, and repository (case-insensitive substring match). For example: 'qwen', 'ox/Delorean', 'customer-support'. [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-all-fine-tunes-accessible-to-the-current-user#parameter-status) status string Filter by status. One of: created, tokenizing, enqueued, running, completed, stopped, errored, deployed [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-all-fine-tunes-accessible-to-the-current-user#parameter-created-by) created\_by string Filter by creator username (exact match) [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-all-fine-tunes-accessible-to-the-current-user#parameter-sort) sort string Sort order by creation date: 'newest' (default) or 'oldest' #### Response 200 application/json List fine-tunes response Standard wrapper for fine-tune list responses. [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-all-fine-tunes-accessible-to-the-current-user#response-fine-tunes) fine\_tunes FineTune Β· object\[\] List of fine-tune job resources Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-all-fine-tunes-accessible-to-the-current-user#response-status) status string High-level status string (for example, 'success'). [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-all-fine-tunes-accessible-to-the-current-user#response-status-message) status\_message string Human-readable status message (for example, 'resource\_found'). [Update training status for a fine-tune job](https://docs.oxen.ai/fine-tuning-api/fine_tunes/update-training-status-for-a-fine-tune-job) [List fine-tunes for a user](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-fine-tunes-for-a-user) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # List checkpoints for a fine-tune job - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-checkpoints-for-a-fine-tune-job#content-area) List checkpoints for a fine-tune job cURL curl --request GET \ --url https://hub.oxen.ai/api/repos/{namespace}/{repo_name}/fine_tunes/{id}/checkpoints \ --header 'Authorization: Bearer ' 200 404 { "branch": "", "checkpoints": [\ {\ "created_at": "",\ "deployment_status": "",\ "inference_samples": [\ {}\ ],\ "metrics": {\ "epoch": 123,\ "grad_norm": 123,\ "learning_rate": 123,\ "loss": 123,\ "mean_token_accuracy": 123\ },\ "model_id": "",\ "model_name": "",\ "path": "",\ "size_bytes": 123,\ "step": 123\ }\ ], "fine_tune_id": "", "status": "", "status_message": "", "total_checkpoints": 123 } GET / api / repos / {namespace} / {repo\_name} / fine\_tunes / {id} / checkpoints Try it List checkpoints for a fine-tune job cURL curl --request GET \ --url https://hub.oxen.ai/api/repos/{namespace}/{repo_name}/fine_tunes/{id}/checkpoints \ --header 'Authorization: Bearer ' 200 404 { "branch": "", "checkpoints": [\ {\ "created_at": "",\ "deployment_status": "",\ "inference_samples": [\ {}\ ],\ "metrics": {\ "epoch": 123,\ "grad_norm": 123,\ "learning_rate": 123,\ "loss": 123,\ "mean_token_accuracy": 123\ },\ "model_id": "",\ "model_name": "",\ "path": "",\ "size_bytes": 123,\ "step": 123\ }\ ], "fine_tune_id": "", "status": "", "status_message": "", "total_checkpoints": 123 } #### Authorizations [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-checkpoints-for-a-fine-tune-job#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-checkpoints-for-a-fine-tune-job#parameter-id) id string required Fine-tune ID #### Response 200 application/json Checkpoints list Standard wrapper for the list-checkpoints response. [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-checkpoints-for-a-fine-tune-job#response-branch) branch string Oxen branch where the model and its checkpoints are stored. [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-checkpoints-for-a-fine-tune-job#response-checkpoints) checkpoints Checkpoint Β· object\[\] Checkpoints saved during the fine-tune run, sorted by step ascending. Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-checkpoints-for-a-fine-tune-job#response-fine-tune-id) fine\_tune\_id string ID of the fine-tune job these checkpoints belong to. [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-checkpoints-for-a-fine-tune-job#response-status) status string High-level status string (for example, 'success'). [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-checkpoints-for-a-fine-tune-job#response-status-message) status\_message string Human-readable status message (for example, 'resource\_found'). [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-checkpoints-for-a-fine-tune-job#response-total-checkpoints) total\_checkpoints integer Total number of checkpoints returned. [Stop a running fine-tune job](https://docs.oxen.ai/fine-tuning-api/fine_tunes/stop-a-running-fine-tune-job) [Deploy a checkpoint from a fine-tune job](https://docs.oxen.ai/fine-tuning-api/fine_tunes/deploy-a-checkpoint-from-a-fine-tune-job) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Tokenize data for a fine-tune job - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/fine-tuning-api/fine_tunes/tokenize-data-for-a-fine-tune-job#content-area) Tokenize data for a fine-tune job cURL curl --request POST \ --url https://hub.oxen.ai/api/repos/{namespace}/{repo_name}/fine_tunes/{id}/tokenize \ --header 'Authorization: Bearer ' 200 404 {} POST / api / repos / {namespace} / {repo\_name} / fine\_tunes / {id} / tokenize Try it Tokenize data for a fine-tune job cURL curl --request POST \ --url https://hub.oxen.ai/api/repos/{namespace}/{repo_name}/fine_tunes/{id}/tokenize \ --header 'Authorization: Bearer ' 200 404 {} #### Authorizations [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/tokenize-data-for-a-fine-tune-job#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/tokenize-data-for-a-fine-tune-job#parameter-id) id string required Fine-tune ID #### Response 200 application/json Tokenize fine-tune response Wrapped fine-tune object [Get logs for a fine-tune job](https://docs.oxen.ai/fine-tuning-api/fine_tunes/get-logs-for-a-fine-tune-job) [Get training status for a fine-tune job](https://docs.oxen.ai/fine-tuning-api/fine_tunes/get-training-status-for-a-fine-tune-job) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Generate video - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/fine-tuning-api/generate-video#content-area) Generate video cURL curl --request POST \ --url https://hub.oxen.ai/api/ai/videos/generate \ --header 'Content-Type: application/json' \ --data ' { "model": "", "prompt": "", "aspect_ratio": "", "duration": 123, "seed": 123 } ' 200 400 { "created": 123, "model": "", "videos": [\ {\ "url": ""\ }\ ] } POST / api / ai / videos / generate Try it Generate video cURL curl --request POST \ --url https://hub.oxen.ai/api/ai/videos/generate \ --header 'Content-Type: application/json' \ --data ' { "model": "", "prompt": "", "aspect_ratio": "", "duration": 123, "seed": 123 } ' 200 400 { "created": 123, "model": "", "videos": [\ {\ "url": ""\ }\ ] } #### Body application/json Video generation request [​](https://docs.oxen.ai/fine-tuning-api/generate-video#body-model) model string required [​](https://docs.oxen.ai/fine-tuning-api/generate-video#body-prompt) prompt string required Text prompt describing the desired video [​](https://docs.oxen.ai/fine-tuning-api/generate-video#body-aspect-ratio-one-of-0) aspect\_ratio string | null [​](https://docs.oxen.ai/fine-tuning-api/generate-video#body-duration-one-of-0) duration integer | null Duration in seconds [​](https://docs.oxen.ai/fine-tuning-api/generate-video#body-seed-one-of-0) seed integer | null #### Response 200 application/json Generated videos [​](https://docs.oxen.ai/fine-tuning-api/generate-video#response-created) created integer [​](https://docs.oxen.ai/fine-tuning-api/generate-video#response-model) model string [​](https://docs.oxen.ai/fine-tuning-api/generate-video#response-videos) videos object\[\] Show child attributes [Cancel generation](https://docs.oxen.ai/fine-tuning-api/cancel-generation) [List fine-tunes for an organization](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-fine-tunes-for-an-organization) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # List fine-tunes in a repository - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-fine-tunes-in-a-repository#content-area) List fine-tunes in a repository cURL curl --request GET \ --url https://hub.oxen.ai/api/repos/{namespace}/{repo_name}/fine_tunes \ --header 'Authorization: Bearer ' 200 404 { "fine_tunes": [\ {\ "base_model": "",\ "created_at": "",\ "id": "",\ "name": "",\ "status": "",\ "updated_at": ""\ }\ ], "status": "", "status_message": "" } GET / api / repos / {namespace} / {repo\_name} / fine\_tunes Try it List fine-tunes in a repository cURL curl --request GET \ --url https://hub.oxen.ai/api/repos/{namespace}/{repo_name}/fine_tunes \ --header 'Authorization: Bearer ' 200 404 { "fine_tunes": [\ {\ "base_model": "",\ "created_at": "",\ "id": "",\ "name": "",\ "status": "",\ "updated_at": ""\ }\ ], "status": "", "status_message": "" } #### Authorizations [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-fine-tunes-in-a-repository#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Query Parameters [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-fine-tunes-in-a-repository#parameter-page) page integer Page number (1-indexed) [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-fine-tunes-in-a-repository#parameter-page-size) page\_size integer Number of items per page [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-fine-tunes-in-a-repository#parameter-search) search string Search across fine-tune name, display name, base model, and repository (case-insensitive substring match). For example: 'qwen', 'ox/Delorean', 'customer-support'. [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-fine-tunes-in-a-repository#parameter-status) status string Filter by status. One of: created, tokenizing, enqueued, running, completed, stopped, errored, deployed [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-fine-tunes-in-a-repository#parameter-created-by) created\_by string Filter by creator username (exact match) [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-fine-tunes-in-a-repository#parameter-sort) sort string Sort order by creation date: 'newest' (default) or 'oldest' #### Response 200 application/json List fine-tunes response Standard wrapper for fine-tune list responses. [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-fine-tunes-in-a-repository#response-fine-tunes) fine\_tunes FineTune Β· object\[\] List of fine-tune job resources Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-fine-tunes-in-a-repository#response-status) status string High-level status string (for example, 'success'). [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-fine-tunes-in-a-repository#response-status-message) status\_message string Human-readable status message (for example, 'resource\_found'). [List fine-tunes for an organization](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-fine-tunes-for-an-organization) [Create a fine-tune job](https://docs.oxen.ai/fine-tuning-api/fine_tunes/create-a-fine-tune-job) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Generate image - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/fine-tuning-api/generate-image#content-area) Generate image cURL curl --request POST \ --url https://hub.oxen.ai/api/ai/images/generate \ --header 'Content-Type: application/json' \ --data ' { "model": "", "prompt": "", "n": 1, "seed": 123, "size": "" } ' 200 400 { "created": 123, "images": [\ {\ "revised_prompt": "",\ "url": ""\ }\ ], "model": "" } POST / api / ai / images / generate Try it Generate image cURL curl --request POST \ --url https://hub.oxen.ai/api/ai/images/generate \ --header 'Content-Type: application/json' \ --data ' { "model": "", "prompt": "", "n": 1, "seed": 123, "size": "" } ' 200 400 { "created": 123, "images": [\ {\ "revised_prompt": "",\ "url": ""\ }\ ], "model": "" } #### Body application/json Image generation request [​](https://docs.oxen.ai/fine-tuning-api/generate-image#body-model) model string required Model ID to use for image generation [​](https://docs.oxen.ai/fine-tuning-api/generate-image#body-prompt) prompt string required Text prompt describing the desired image [​](https://docs.oxen.ai/fine-tuning-api/generate-image#body-n) n integer default:1 Number of images to generate [​](https://docs.oxen.ai/fine-tuning-api/generate-image#body-seed-one-of-0) seed integer | null [​](https://docs.oxen.ai/fine-tuning-api/generate-image#body-size-one-of-0) size string | null Image size #### Response 200 application/json Generated images [​](https://docs.oxen.ai/fine-tuning-api/generate-image#response-created) created integer [​](https://docs.oxen.ai/fine-tuning-api/generate-image#response-images) images object\[\] Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/generate-image#response-model) model string [Edit image](https://docs.oxen.ai/fine-tuning-api/edit-image) [List models](https://docs.oxen.ai/fine-tuning-api/list-models) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Update a fine-tune job - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/fine-tuning-api/fine_tunes/update-a-fine-tune-job#content-area) Update a fine-tune job cURL curl --request PATCH \ --url https://hub.oxen.ai/api/repos/{namespace}/{repo_name}/fine_tunes/{id} \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{}' 200 404 { "fine_tune": { "base_model": "", "created_at": "", "id": "", "name": "", "status": "", "updated_at": "" }, "status": "", "status_message": "" } PATCH / api / repos / {namespace} / {repo\_name} / fine\_tunes / {id} Try it Update a fine-tune job cURL curl --request PATCH \ --url https://hub.oxen.ai/api/repos/{namespace}/{repo_name}/fine_tunes/{id} \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{}' 200 404 { "fine_tune": { "base_model": "", "created_at": "", "id": "", "name": "", "status": "", "updated_at": "" }, "status": "", "status_message": "" } #### Authorizations [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/update-a-fine-tune-job#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/update-a-fine-tune-job#parameter-id) id string required Fine-tune ID #### Body application/json Fine-tune update request Subset of fine-tune fields to update #### Response 200 application/json Updated fine-tune response Standard wrapper for fine-tune responses. [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/update-a-fine-tune-job#response-fine-tune) fine\_tune FineTune Β· object Fine-tune job resource Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/update-a-fine-tune-job#response-status) status string High-level status string (for example, 'success'). [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/update-a-fine-tune-job#response-status-message) status\_message string Human-readable status message (for example, 'resource\_found'). [Delete a fine-tune job](https://docs.oxen.ai/fine-tuning-api/fine_tunes/delete-a-fine-tune-job) [Run a fine-tune job](https://docs.oxen.ai/fine-tuning-api/fine_tunes/run-a-fine-tune-job) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # List in-flight queue items - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/fine-tuning-api/list-in-flight-queue-items#content-area) List in-flight queue items cURL curl --request GET \ --url https://hub.oxen.ai/api/ai/queue 200 { "count": 123, "generations": [\ {\ "enqueued_at": 123,\ "generation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",\ "model_name": "",\ "completed_at": 123,\ "error_message": "",\ "result_url": "",\ "started_at": 123,\ "target_directory": "",\ "target_namespace": "",\ "target_repo": ""\ }\ ] } GET / api / ai / queue Try it List in-flight queue items cURL curl --request GET \ --url https://hub.oxen.ai/api/ai/queue 200 { "count": 123, "generations": [\ {\ "enqueued_at": 123,\ "generation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",\ "model_name": "",\ "completed_at": 123,\ "error_message": "",\ "result_url": "",\ "started_at": 123,\ "target_directory": "",\ "target_namespace": "",\ "target_repo": ""\ }\ ] } #### Query Parameters [​](https://docs.oxen.ai/fine-tuning-api/list-in-flight-queue-items#parameter-namespace) namespace string [​](https://docs.oxen.ai/fine-tuning-api/list-in-flight-queue-items#parameter-model) model string [​](https://docs.oxen.ai/fine-tuning-api/list-in-flight-queue-items#parameter-media-type) media\_type enum Available options: `image`, `video` [​](https://docs.oxen.ai/fine-tuning-api/list-in-flight-queue-items#parameter-status) status enum Available options: `queued`, `processing`, `succeeded`, `failed`, `cancelled` [​](https://docs.oxen.ai/fine-tuning-api/list-in-flight-queue-items#parameter-repo) repo string [​](https://docs.oxen.ai/fine-tuning-api/list-in-flight-queue-items#parameter-folder) folder string #### Response 200 - application/json Generation list Lean polling view of the workbench render queue. Active (`queued`/`processing`) rows by default; pass an explicit `status=` filter to include terminal rows. For paginated browse with cost aggregates, see `/api/ai/generations`. [​](https://docs.oxen.ai/fine-tuning-api/list-in-flight-queue-items#response-count) count integer required [​](https://docs.oxen.ai/fine-tuning-api/list-in-flight-queue-items#response-generations) generations object\[\] required Show child attributes [Unfavorite a model](https://docs.oxen.ai/fine-tuning-api/unfavorite-a-model) [Enqueue generation](https://docs.oxen.ai/fine-tuning-api/enqueue-generation) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # List fine-tunes for an organization - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-fine-tunes-for-an-organization#content-area) List fine-tunes for an organization cURL curl --request GET \ --url https://hub.oxen.ai/api/orgs/{name}/fine_tunes \ --header 'Authorization: Bearer ' 200 401 404 { "fine_tunes": [\ {\ "base_model": "",\ "created_at": "",\ "id": "",\ "name": "",\ "status": "",\ "updated_at": ""\ }\ ], "status": "", "status_message": "" } GET / api / orgs / {name} / fine\_tunes Try it List fine-tunes for an organization cURL curl --request GET \ --url https://hub.oxen.ai/api/orgs/{name}/fine_tunes \ --header 'Authorization: Bearer ' 200 401 404 { "fine_tunes": [\ {\ "base_model": "",\ "created_at": "",\ "id": "",\ "name": "",\ "status": "",\ "updated_at": ""\ }\ ], "status": "", "status_message": "" } #### Authorizations [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-fine-tunes-for-an-organization#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-fine-tunes-for-an-organization#parameter-name) name string required Organization name #### Query Parameters [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-fine-tunes-for-an-organization#parameter-page) page integer Page number (1-indexed) [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-fine-tunes-for-an-organization#parameter-page-size) page\_size integer Number of items per page [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-fine-tunes-for-an-organization#parameter-search) search string Search across fine-tune name, display name, base model, and repository (case-insensitive substring match). For example: 'qwen', 'ox/Delorean', 'customer-support'. [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-fine-tunes-for-an-organization#parameter-status) status string Filter by status. One of: created, tokenizing, enqueued, running, completed, stopped, errored, deployed [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-fine-tunes-for-an-organization#parameter-created-by) created\_by string Filter by creator username (exact match) [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-fine-tunes-for-an-organization#parameter-sort) sort string Sort order by creation date: 'newest' (default) or 'oldest' #### Response 200 application/json List fine-tunes response Standard wrapper for fine-tune list responses. [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-fine-tunes-for-an-organization#response-fine-tunes) fine\_tunes FineTune Β· object\[\] List of fine-tune job resources Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-fine-tunes-for-an-organization#response-status) status string High-level status string (for example, 'success'). [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-fine-tunes-for-an-organization#response-status-message) status\_message string Human-readable status message (for example, 'resource\_found'). [Generate video](https://docs.oxen.ai/fine-tuning-api/generate-video) [List fine-tunes in a repository](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-fine-tunes-in-a-repository) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Get generation details - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/fine-tuning-api/get-generation-details#content-area) Get generation details cURL curl --request GET \ --url https://hub.oxen.ai/api/ai/generations/{generation_id} 200 404 { "generation": { "enqueued_at": 123, "generation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "model_name": "", "completed_at": 123, "cost": "", "error_message": "", "result_url": "", "started_at": 123, "target_directory": "", "target_namespace": "", "target_repo": "", "user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "user_image": "", "username": "" }, "status": "success", "status_message": "resource_found" } GET / api / ai / generations / {generation\_id} Try it Get generation details cURL curl --request GET \ --url https://hub.oxen.ai/api/ai/generations/{generation_id} 200 404 { "generation": { "enqueued_at": 123, "generation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "model_name": "", "completed_at": 123, "cost": "", "error_message": "", "result_url": "", "started_at": 123, "target_directory": "", "target_namespace": "", "target_repo": "", "user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "user_image": "", "username": "" }, "status": "success", "status_message": "resource_found" } #### Path Parameters [​](https://docs.oxen.ai/fine-tuning-api/get-generation-details#parameter-generation-id) generation\_id string required #### Response 200 application/json Generation details Standard success envelope wrapping a single generation under `generation`. The inner object is the same per-row shape returned by the list endpoint (request params merged in at the top level), so the frontend can reuse one type for both. [​](https://docs.oxen.ai/fine-tuning-api/get-generation-details#response-generation) generation object required Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/get-generation-details#response-status) status string required Example: `"success"` [​](https://docs.oxen.ai/fine-tuning-api/get-generation-details#response-status-message) status\_message string required Example: `"resource_found"` [List past generations](https://docs.oxen.ai/fine-tuning-api/list-past-generations) [Edit image](https://docs.oxen.ai/fine-tuning-api/edit-image) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # List past generations - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/fine-tuning-api/list-past-generations#content-area) List past generations cURL curl --request GET \ --url https://hub.oxen.ai/api/ai/generations 200 { "count": 123, "generations": [\ {\ "enqueued_at": 123,\ "generation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",\ "model_name": "",\ "completed_at": 123,\ "cost": "",\ "error_message": "",\ "result_url": "",\ "started_at": 123,\ "target_directory": "",\ "target_namespace": "",\ "target_repo": "",\ "user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",\ "user_image": "",\ "username": ""\ }\ ], "page_number": 123, "page_size": 123, "total_cost": "", "total_entries": 123, "total_pages": 123 } GET / api / ai / generations Try it List past generations cURL curl --request GET \ --url https://hub.oxen.ai/api/ai/generations 200 { "count": 123, "generations": [\ {\ "enqueued_at": 123,\ "generation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",\ "model_name": "",\ "completed_at": 123,\ "cost": "",\ "error_message": "",\ "result_url": "",\ "started_at": 123,\ "target_directory": "",\ "target_namespace": "",\ "target_repo": "",\ "user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",\ "user_image": "",\ "username": ""\ }\ ], "page_number": 123, "page_size": 123, "total_cost": "", "total_entries": 123, "total_pages": 123 } #### Query Parameters [​](https://docs.oxen.ai/fine-tuning-api/list-past-generations#parameter-namespace) namespace string [​](https://docs.oxen.ai/fine-tuning-api/list-past-generations#parameter-model) model string [​](https://docs.oxen.ai/fine-tuning-api/list-past-generations#parameter-media-type) media\_type enum Available options: `image`, `video` [​](https://docs.oxen.ai/fine-tuning-api/list-past-generations#parameter-status) status enum Available options: `queued`, `processing`, `succeeded`, `failed`, `cancelled` [​](https://docs.oxen.ai/fine-tuning-api/list-past-generations#parameter-repo) repo string [​](https://docs.oxen.ai/fine-tuning-api/list-past-generations#parameter-folder) folder string [​](https://docs.oxen.ai/fine-tuning-api/list-past-generations#parameter-page) page integer default:1 Required range: `x >= 1` [​](https://docs.oxen.ai/fine-tuning-api/list-past-generations#parameter-page-size) page\_size integer default:50 Required range: `1 <= x <= 1000` #### Response 200 - application/json Generation list Paginated browse view of past generations for a namespace. Includes the per-filter cost aggregate. Each row carries any additional request params (prompt, duration, etc.) merged in at the top level. [​](https://docs.oxen.ai/fine-tuning-api/list-past-generations#response-count) count integer required Number of entries in this response (<= page\_size) [​](https://docs.oxen.ai/fine-tuning-api/list-past-generations#response-generations) generations object\[\] required Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/list-past-generations#response-page-number) page\_number integer required Current page number (1-indexed) [​](https://docs.oxen.ai/fine-tuning-api/list-past-generations#response-page-size) page\_size integer required [​](https://docs.oxen.ai/fine-tuning-api/list-past-generations#response-total-cost-one-of-0) total\_cost string | null required Sum of charged amounts across the filter set (decimal as string). Null when nothing in the set has been charged. [​](https://docs.oxen.ai/fine-tuning-api/list-past-generations#response-total-entries) total\_entries integer required [​](https://docs.oxen.ai/fine-tuning-api/list-past-generations#response-total-pages) total\_pages integer required [Create chat completion](https://docs.oxen.ai/fine-tuning-api/create-chat-completion) [Get generation details](https://docs.oxen.ai/fine-tuning-api/get-generation-details) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # List models - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/fine-tuning-api/list-models#content-area) List models cURL curl --request GET \ --url https://hub.oxen.ai/api/ai/models 200 { "data": [\ {\ "created": 123,\ "id": "",\ "owned_by": "",\ "capabilities": {\ "input": [\ ""\ ],\ "output": [\ ""\ ]\ },\ "deployments": [\ {}\ ],\ "description": "",\ "developer": {\ "logo": "",\ "name": ""\ },\ "display_name": "",\ "fine_tuning": {\ "actions": [\ ""\ ],\ "cost_per_second": 123\ },\ "image_url": "",\ "pricing": {\ "cost_per_image": 123,\ "cost_per_second": 123,\ "cost_per_second_high_res": 123,\ "cost_per_second_with_audio": 123,\ "input_cost_per_token": 123,\ "output_cost_per_token": 123\ },\ "released_at": "",\ "request_schema": {},\ "showcase": {\ "gallery": [\ {\ "alt": "",\ "src": "",\ "category": "",\ "details": "",\ "prompt": "",\ "title": ""\ }\ ],\ "hero_image": "",\ "tagline": ""\ },\ "source_model": "",\ "summary": ""\ }\ ] } GET / api / ai / models Try it List models cURL curl --request GET \ --url https://hub.oxen.ai/api/ai/models 200 { "data": [\ {\ "created": 123,\ "id": "",\ "owned_by": "",\ "capabilities": {\ "input": [\ ""\ ],\ "output": [\ ""\ ]\ },\ "deployments": [\ {}\ ],\ "description": "",\ "developer": {\ "logo": "",\ "name": ""\ },\ "display_name": "",\ "fine_tuning": {\ "actions": [\ ""\ ],\ "cost_per_second": 123\ },\ "image_url": "",\ "pricing": {\ "cost_per_image": 123,\ "cost_per_second": 123,\ "cost_per_second_high_res": 123,\ "cost_per_second_with_audio": 123,\ "input_cost_per_token": 123,\ "output_cost_per_token": 123\ },\ "released_at": "",\ "request_schema": {},\ "showcase": {\ "gallery": [\ {\ "alt": "",\ "src": "",\ "category": "",\ "details": "",\ "prompt": "",\ "title": ""\ }\ ],\ "hero_image": "",\ "tagline": ""\ },\ "source_model": "",\ "summary": ""\ }\ ] } #### Query Parameters [​](https://docs.oxen.ai/fine-tuning-api/list-models#parameter-provider-name) provider\_name string [​](https://docs.oxen.ai/fine-tuning-api/list-models#parameter-developer-name) developer\_name string [​](https://docs.oxen.ai/fine-tuning-api/list-models#parameter-action) action string #### Response 200 - application/json Model list OpenAI-compatible response for listing models. [​](https://docs.oxen.ai/fine-tuning-api/list-models#response-data) data Model Β· object\[\] required Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/list-models#response-object) object enum required Available options: `list` [Generate image](https://docs.oxen.ai/fine-tuning-api/generate-image) [List favorite models](https://docs.oxen.ai/fine-tuning-api/list-favorite-models) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Async Queue - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/inference-api/reference/async_queue#content-area) [​](https://docs.oxen.ai/inference-api/reference/async_queue#why-use-the-async-queue) Why Use the Async Queue ---------------------------------------------------------------------------------------------------------------- The synchronous endpoints (`/ai/images/generate`, `/ai/videos/generate`) block until the result is ready. For video generation, this can be 1-10+ minutes. The async queue returns immediately with generation IDs so you can: * Run many generations in parallel (up to 4 per request, no limit on total queued) * Avoid long-lived HTTP connections * Build progress-tracking UIs * Query completed generations and their output URLs at any time [​](https://docs.oxen.ai/inference-api/reference/async_queue#workflow) Workflow ---------------------------------------------------------------------------------- 1. POST /ai/queue β†’ Get generation IDs (status: queued) 2. GET /ai/queue or /ai/queue/:id β†’ Poll until status is succeeded or failed 3. Read result_url from the completed generation Generations persist after reaching a terminal state (`succeeded`, `failed`, or `cancelled`), so you can retrieve results at any time. A Server-Sent Events stream at `GET /api/events` can also deliver completion notifications with the output file URL. See [Completion Events](https://docs.oxen.ai/inference-api/reference/async_queue#completion-events) . * * * [​](https://docs.oxen.ai/inference-api/reference/async_queue#enqueue) Enqueue -------------------------------------------------------------------------------- POST /api/ai/queue Submit an async image or video generation job. ### [​](https://docs.oxen.ai/inference-api/reference/async_queue#required-parameters) Required Parameters | Parameter | Type | Description | | --- | --- | --- | | `model` | string | Must be an image or video model. Text-only models are rejected. | ### [​](https://docs.oxen.ai/inference-api/reference/async_queue#additional-parameters) Additional Parameters | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `num_generations` | integer | `1` | How many generations to enqueue per request. Range: 1-4. Call the endpoint multiple times to queue more. | | `target_namespace` | string | your username | Namespace to store results and bill to. | All other parameters (e.g. `prompt`, `multi_prompt`, `input_image`, `input_video`, `aspect_ratio`, `duration`, `seed`, `generate_audio`, `response_format`) are passed through to the model. Consult the model’s `request_schema` via `GET /api/ai/models/:id` for supported parameters and their constraints. ### [​](https://docs.oxen.ai/inference-api/reference/async_queue#response) Response { "generations": [\ {"generation_id": "bb8f5eb7-361e-4e13-ab73-67457bc8057e", "status": "queued"},\ {"generation_id": "e9bede09-cd0e-46cf-bbcd-cb1a50099351", "status": "queued"}\ ] } ### [​](https://docs.oxen.ai/inference-api/reference/async_queue#validation) Validation The API validates at enqueue time that: * The model exists and has image or video output capability * `num_generations` is 1-4 * The user is authenticated with sufficient credits Model-specific parameter validation (prompt content, duration ranges, aspect ratio values) happens **when the generation runs**, not at enqueue time. If a parameter is invalid, the generation transitions to `failed` status with an `error_message`. To validate parameters and get immediate error feedback, use `/ai/images/generate` or `/ai/videos/generate` instead. * * * [​](https://docs.oxen.ai/inference-api/reference/async_queue#list-generations) List Generations -------------------------------------------------------------------------------------------------- GET /api/ai/queue Lists generations for the authenticated user’s namespace. By default, only active generations (`queued` or `processing`) are returned. Pass an explicit `status` filter to include terminal states. ### [​](https://docs.oxen.ai/inference-api/reference/async_queue#query-parameters) Query Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `namespace` | string | no | Namespace to query. Defaults to the authenticated user. | | `model` | string | no | Filter by model name. | | `status` | string | no | Filter by status: `queued`, `processing`, `succeeded`, `failed`, or `cancelled`. When omitted, only active generations are returned. | | `media_type` | string | no | Filter by `image` or `video`. | | `repo` | string | no | Filter by target repository name. | | `folder` | string | no | Filter by target directory. | ### [​](https://docs.oxen.ai/inference-api/reference/async_queue#response-2) Response { "count": 2, "generations": [\ {\ "generation_id": "7cf9b23a-1234-5678-9abc-def012345678",\ "model_name": "kling-video-o3-pro-reference-to-video",\ "prompt": "An astronaut walking on Mars",\ "media_type": "video",\ "status": "processing",\ "result_url": null,\ "error_message": null,\ "enqueued_at": 1775091431,\ "started_at": 1775091432,\ "completed_at": null,\ "aspect_ratio": "16:9",\ "duration": 10\ },\ {\ "generation_id": "bb8f5eb7-361e-4e13-ab73-67457bc8057e",\ "model_name": "black-forest-labs-flux-2-klein-4b",\ "prompt": "Abstract geometric pattern in blue and gold",\ "media_type": "image",\ "status": "queued",\ "result_url": null,\ "error_message": null,\ "enqueued_at": 1775091440,\ "started_at": null,\ "completed_at": null\ }\ ] } | Field | Always Present | Description | | --- | --- | --- | | `count` | yes | Number of generations in the response | | `generation_id` | yes | Unique ID for this generation | | `model_name` | yes | Model name | | `prompt` | yes | Text prompt (from original request parameters) | | `media_type` | yes | `"image"` or `"video"` | | `status` | yes | `"queued"`, `"processing"`, `"succeeded"`, `"failed"`, or `"cancelled"` | | `result_url` | yes | Output file URL when succeeded, otherwise `null` | | `error_message` | yes | Error details when failed, otherwise `null` | | `enqueued_at` | yes | Unix timestamp when the job was enqueued | | `started_at` | yes | Unix timestamp when processing began, or `null` | | `completed_at` | yes | Unix timestamp when the job reached a terminal state, or `null` | | `seed` | if submitted | Random seed | | `aspect_ratio` | if submitted | Aspect ratio | | `duration` | if submitted | Video duration | Any additional parameters from the original enqueue request (e.g. `seed`, `aspect_ratio`, `duration`, `input_image`) are included in the response alongside the fields above. ### [​](https://docs.oxen.ai/inference-api/reference/async_queue#polling-strategy) Polling Strategy * **Image generation** (FLUX, etc.): typically completes in 5-30 seconds. Poll every 2-5 seconds. * **Video generation** (Kling, etc.): typically takes 1-5 minutes. Poll every 10-30 seconds. Poll until every generation’s `status` is a terminal value (`succeeded`, `failed`, or `cancelled`), or until `count` reaches 0 when using the default active-only filter. * * * [​](https://docs.oxen.ai/inference-api/reference/async_queue#get-generation) Get Generation ---------------------------------------------------------------------------------------------- GET /api/ai/queue/:generation_id Retrieves metadata for a single generation. Includes `result_url` when the generation has succeeded and `error_message` when it has failed. ### [​](https://docs.oxen.ai/inference-api/reference/async_queue#path-parameters) Path Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `generation_id` | string (UUID) | **yes** | The generation ID returned by the enqueue endpoint. | ### [​](https://docs.oxen.ai/inference-api/reference/async_queue#response-in-progress) Response (in progress) { "generation_id": "7cf9b23a-1234-5678-9abc-def012345678", "model_name": "kling-video-o3-pro-reference-to-video", "prompt": "An astronaut walking on Mars", "media_type": "video", "status": "processing", "result_url": null, "error_message": null, "enqueued_at": 1775091431, "started_at": 1775091432, "completed_at": null, "aspect_ratio": "16:9", "duration": 10 } ### [​](https://docs.oxen.ai/inference-api/reference/async_queue#response-succeeded) Response (succeeded) { "generation_id": "7cf9b23a-1234-5678-9abc-def012345678", "model_name": "kling-video-o3-pro-reference-to-video", "prompt": "An astronaut walking on Mars", "media_type": "video", "status": "succeeded", "result_url": "https://hub.oxen.ai/api/repos/...", "error_message": null, "enqueued_at": 1775091431, "started_at": 1775091432, "completed_at": 1775091590, "aspect_ratio": "16:9", "duration": 10 } ### [​](https://docs.oxen.ai/inference-api/reference/async_queue#response-failed) Response (failed) { "generation_id": "7cf9b23a-1234-5678-9abc-def012345678", "model_name": "kling-video-o3-pro-reference-to-video", "prompt": "An astronaut walking on Mars", "media_type": "video", "status": "failed", "result_url": null, "error_message": "Insufficient credits", "enqueued_at": 1775091431, "started_at": 1775091432, "completed_at": 1775091435 } ### [​](https://docs.oxen.ai/inference-api/reference/async_queue#response-not-found) Response (not found) Returns 404 when the generation ID does not exist: { "error": { "type": "resource_not_found", "title": "The requested resource could not be found" }, "status": "error", "status_message": "resource_not_found" } * * * [​](https://docs.oxen.ai/inference-api/reference/async_queue#cancel-generation) Cancel Generation ---------------------------------------------------------------------------------------------------- DELETE /api/ai/queue/:generation_id Cancels a queued or in-progress generation. ### [​](https://docs.oxen.ai/inference-api/reference/async_queue#path-parameters-2) Path Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `generation_id` | string (UUID) | **yes** | The generation ID to cancel. | ### [​](https://docs.oxen.ai/inference-api/reference/async_queue#response-success) Response (success) { "status": "success", "generation_id": "bb8f5eb7-361e-4e13-ab73-67457bc8057e" } ### [​](https://docs.oxen.ai/inference-api/reference/async_queue#response-not-found-2) Response (not found) Returns 404 when the generation ID does not exist: { "error": { "type": "resource_not_found", "title": "The requested resource could not be found" }, "status": "error", "status_message": "resource_not_found" } You can only cancel generations that are still active (`queued` or `processing`). Cancelling a generation that has already reached a terminal state (`succeeded`, `failed`, or `cancelled`) has no effect. * * * [​](https://docs.oxen.ai/inference-api/reference/async_queue#completion-events) Completion Events ---------------------------------------------------------------------------------------------------- GET /api/events Server-Sent Events stream that emits `media_generation_completed` events when generations reach a terminal state. ### [​](https://docs.oxen.ai/inference-api/reference/async_queue#connect) Connect GET /api/events Authorization: Bearer $OXEN_API_KEY Response is `Content-Type: text/event-stream`. The server sends `: keep-alive\n\n` every 15 seconds when idle. Events are broadcast to currently-connected subscribers with no buffering. Anything that fires before you connect is lost. Subscribe before calling `POST /ai/queue` to avoid missing events. ### [​](https://docs.oxen.ai/inference-api/reference/async_queue#event-media_generation_completed) Event: media\_generation\_completed Fires once per generation on terminal state. Success wire format: event: media_generation_completed data: {"generation_id":"bb8f5eb7-...","status":"succeeded","media_type":"video","model":"kling-video-o3-pro-reference-to-video","url":"https://hub.oxen.ai/api/repos/..."} Failure: event: media_generation_completed data: {"generation_id":"bb8f5eb7-...","status":"failed","media_type":"video","error":"Insufficient credits"} ### [​](https://docs.oxen.ai/inference-api/reference/async_queue#fields) Fields | Field | succeeded | failed | Description | | --- | --- | --- | --- | | `generation_id` | yes | yes | Matches the ID returned by `POST /ai/queue` | | `status` | `"succeeded"` | `"failed"` | Only these two values appear | | `media_type` | yes | yes | `"image"` or `"video"` | | `model` | yes | no | Model name | | `url` | yes | no | Presigned URL to the output file. Expires after a limited time. | | `error` | no | yes | Human-readable failure reason | ### [​](https://docs.oxen.ai/inference-api/reference/async_queue#other-events-on-this-stream) Other events on this stream `GET /api/events` is a user-scoped stream that may carry unrelated event types (e.g. deployment events). Filter on the `event:` line and ignore anything other than `media_generation_completed`. ### [​](https://docs.oxen.ai/inference-api/reference/async_queue#example) Example Python cURL import json import requests import threading import time API_KEY = "YOUR_API_KEY" HEADERS = {"Authorization": f"Bearer {API_KEY}"} def listen(results): with requests.get( "https://hub.oxen.ai/api/events", headers=HEADERS, stream=True, ) as resp: event_name = None for line in resp.iter_lines(decode_unicode=True): if line is None or line == "": event_name = None continue if line.startswith(":"): continue # keep-alive comment if line.startswith("event:"): event_name = line[6:].strip() elif line.startswith("data:") and event_name == "media_generation_completed": payload = json.loads(line[5:].strip()) results[payload["generation_id"]] = payload # Start listening BEFORE enqueuing results = {} threading.Thread(target=listen, args=(results,), daemon=True).start() print("SSE listener connected, waiting for events...") # Enqueue prompt = "A red cube" model = "black-forest-labs-flux-2-klein-4b" print(f"\nEnqueuing {model}") print(f" prompt: \"{prompt}\"") resp = requests.post( "https://hub.oxen.ai/api/ai/queue", headers={**HEADERS, "Content-Type": "application/json"}, json={ "model": model, "prompt": prompt, }, ) gen_id = resp.json()["generations"][0]["generation_id"] print(f" generation_id: {gen_id}") # Wait for completion event start = time.time() while gen_id not in results: elapsed = time.time() - start print(f" Waiting for SSE completion event... ({elapsed:.1f}s)") time.sleep(2) elapsed = time.time() - start event = results[gen_id] if event["status"] == "succeeded": print(f"\nGeneration succeeded in {elapsed:.1f}s") print(f" URL: {event['url']}") else: print(f"\nGeneration failed after {elapsed:.1f}s") print(f" Error: {event['error']}") ### [​](https://docs.oxen.ai/inference-api/reference/async_queue#terminal-states-without-events) Terminal states without events `media_generation_completed` does not fire for cancelled generations (you called `DELETE /ai/queue/:id`). You can still retrieve the final status of any generation via `GET /ai/queue/:id`. * * * [​](https://docs.oxen.ai/inference-api/reference/async_queue#examples) Examples ---------------------------------------------------------------------------------- ### [​](https://docs.oxen.ai/inference-api/reference/async_queue#batch-image-generation-with-polling) Batch image generation with polling Python cURL import requests import time API_KEY = "YOUR_API_KEY" HEADERS = { "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json", } # Enqueue 4 images model = "black-forest-labs-flux-2-klein-4b" prompt = "Abstract geometric pattern in blue and gold" print(f"Enqueuing 4 generations of {model}") print(f" prompt: \"{prompt}\"") response = requests.post( "https://hub.oxen.ai/api/ai/queue", headers=HEADERS, json={ "model": model, "prompt": prompt, "num_generations": 4, }, ) gen_ids = [g["generation_id"] for g in response.json()["generations"]] for gid in gen_ids: print(f" generation_id: {gid}") # Poll individual generations until all reach a terminal status terminal = {"succeeded", "failed", "cancelled"} start = time.time() while True: statuses = {} for gid in gen_ids: resp = requests.get( f"https://hub.oxen.ai/api/ai/queue/{gid}", headers=HEADERS, ).json() statuses[gid] = resp["status"] done = sum(1 for s in statuses.values() if s in terminal) elapsed = time.time() - start print(f" [{elapsed:5.1f}s] {done}/{len(gen_ids)} complete") if done == len(gen_ids): break time.sleep(5) elapsed = time.time() - start print(f"\nAll {len(gen_ids)} images generated in {elapsed:.1f}s!") for gid, s in statuses.items(): print(f" {gid}: {s}") ### [​](https://docs.oxen.ai/inference-api/reference/async_queue#async-video-generation) Async video generation Python cURL import requests response = requests.post( "https://hub.oxen.ai/api/ai/queue", headers={ "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, json={ "model": "kling-video-o3-pro-reference-to-video", "multi_prompt": [\ {"prompt": "Aerial view of waves crashing on a rocky shore", "duration": 5},\ {"prompt": "Camera pulls back to reveal the full coastline", "duration": 5},\ ], "aspect_ratio": "16:9", }, ) print(response.json()) ### [​](https://docs.oxen.ai/inference-api/reference/async_queue#poll-a-single-generation-by-id) Poll a single generation by ID Python cURL import requests import time API_KEY = "YOUR_API_KEY" HEADERS = {"Authorization": f"Bearer {API_KEY}"} # After enqueuing, grab a generation ID generation_id = "YOUR_GENERATION_ID" print(f"Polling generation {generation_id}") terminal = {"succeeded", "failed", "cancelled"} start = time.time() poll_count = 0 while True: poll_count += 1 data = requests.get( f"https://hub.oxen.ai/api/ai/queue/{generation_id}", headers=HEADERS, ).json() elapsed = time.time() - start status = data["status"] if status in terminal: print(f" [{elapsed:5.1f}s] Generation {status}") if status == "succeeded": print(f" result_url: {data['result_url']}") elif status == "failed": print(f" error: {data['error_message']}") break print(f" [{elapsed:5.1f}s] Poll #{poll_count} β€” {status} ({data['model_name']}, {data['media_type']})") time.sleep(10) ### [​](https://docs.oxen.ai/inference-api/reference/async_queue#end-to-end-enqueue-wait-for-sse-download) End-to-end: enqueue, wait for SSE, download Python import json import queue import requests import threading import time API_KEY = "YOUR_API_KEY" HEADERS = {"Authorization": f"Bearer {API_KEY}"} def listen(events): with requests.get( "https://hub.oxen.ai/api/events", headers=HEADERS, stream=True, ) as resp: event_name = None for line in resp.iter_lines(decode_unicode=True): if not line: event_name = None continue if line.startswith(":"): continue if line.startswith("event:"): event_name = line[6:].strip() elif line.startswith("data:") and event_name == "media_generation_completed": events.put(json.loads(line[5:])) # Subscribe before enqueuing so no events are missed events = queue.Queue() threading.Thread(target=listen, args=(events,), daemon=True).start() print("SSE listener connected, waiting for events...") # Enqueue model = "black-forest-labs-flux-2-klein-4b" prompt = "A cathedral in the clouds" print(f"\nEnqueuing {model}") print(f" prompt: \"{prompt}\"") resp = requests.post( "https://hub.oxen.ai/api/ai/queue", headers={**HEADERS, "Content-Type": "application/json"}, json={ "model": model, "prompt": prompt, }, ).json() gen_id = resp["generations"][0]["generation_id"] print(f" generation_id: {gen_id}") # Wait for the matching completion event start = time.time() print(f"\nWaiting for SSE completion event...") while True: try: event = events.get(timeout=3) if event["generation_id"] == gen_id: break print(f" [{time.time() - start:5.1f}s] Received event for different generation, skipping...") except queue.Empty: print(f" [{time.time() - start:5.1f}s] Still waiting...") elapsed = time.time() - start if event["status"] == "succeeded": print(f"\nGeneration succeeded in {elapsed:.1f}s") print(f" Downloading {event['url']}") with open("output.png", "wb") as f: f.write(requests.get(event["url"]).content) print(" Saved output.png") else: print(f"\nGeneration failed after {elapsed:.1f}s") print(f" Error: {event['error']}") [​](https://docs.oxen.ai/inference-api/reference/async_queue#errors) Errors ------------------------------------------------------------------------------ | Condition | Error | | --- | --- | | `num_generations` out of range | `"num_generations must be an integer between 1 and 4"` | | Model not found | `"Model not found: "` | | Text-only model | `":unsupported_media_type"` | | 404 on GET/DELETE | Generation ID does not exist | [Video Generation](https://docs.oxen.ai/inference-api/reference/video_generation) [Models](https://docs.oxen.ai/inference-api/reference/models/overview) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # List featured models - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/fine-tuning-api/list-featured-models#content-area) List featured models cURL curl --request GET \ --url https://hub.oxen.ai/api/ai/models/featured 200 { "data": [\ {\ "created": 123,\ "id": "",\ "owned_by": "",\ "capabilities": {\ "input": [\ ""\ ],\ "output": [\ ""\ ]\ },\ "deployments": [\ {}\ ],\ "description": "",\ "developer": {\ "logo": "",\ "name": ""\ },\ "display_name": "",\ "fine_tuning": {\ "actions": [\ ""\ ],\ "cost_per_second": 123\ },\ "image_url": "",\ "pricing": {\ "cost_per_image": 123,\ "cost_per_second": 123,\ "cost_per_second_high_res": 123,\ "cost_per_second_with_audio": 123,\ "input_cost_per_token": 123,\ "output_cost_per_token": 123\ },\ "released_at": "",\ "request_schema": {},\ "showcase": {\ "gallery": [\ {\ "alt": "",\ "src": "",\ "category": "",\ "details": "",\ "prompt": "",\ "title": ""\ }\ ],\ "hero_image": "",\ "tagline": ""\ },\ "source_model": "",\ "summary": ""\ }\ ] } GET / api / ai / models / featured Try it List featured models cURL curl --request GET \ --url https://hub.oxen.ai/api/ai/models/featured 200 { "data": [\ {\ "created": 123,\ "id": "",\ "owned_by": "",\ "capabilities": {\ "input": [\ ""\ ],\ "output": [\ ""\ ]\ },\ "deployments": [\ {}\ ],\ "description": "",\ "developer": {\ "logo": "",\ "name": ""\ },\ "display_name": "",\ "fine_tuning": {\ "actions": [\ ""\ ],\ "cost_per_second": 123\ },\ "image_url": "",\ "pricing": {\ "cost_per_image": 123,\ "cost_per_second": 123,\ "cost_per_second_high_res": 123,\ "cost_per_second_with_audio": 123,\ "input_cost_per_token": 123,\ "output_cost_per_token": 123\ },\ "released_at": "",\ "request_schema": {},\ "showcase": {\ "gallery": [\ {\ "alt": "",\ "src": "",\ "category": "",\ "details": "",\ "prompt": "",\ "title": ""\ }\ ],\ "hero_image": "",\ "tagline": ""\ },\ "source_model": "",\ "summary": ""\ }\ ] } #### Response 200 - application/json Featured models OpenAI-compatible response for listing models. [​](https://docs.oxen.ai/fine-tuning-api/list-featured-models#response-data) data Model Β· object\[\] required Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/list-featured-models#response-object) object enum required Available options: `list` [List favorite models](https://docs.oxen.ai/fine-tuning-api/list-favorite-models) [Search models](https://docs.oxen.ai/fine-tuning-api/search-models) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Run a fine-tune job - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/fine-tuning-api/fine_tunes/run-a-fine-tune-job#content-area) Run a fine-tune job cURL curl --request POST \ --url https://hub.oxen.ai/api/repos/{namespace}/{repo_name}/fine_tunes/{id}/actions/run \ --header 'Authorization: Bearer ' 200 404 { "fine_tune": { "base_model": "", "created_by": { "id": "", "image": "", "name": "", "username": "" }, "credits_used": "", "deployed_model": {}, "description": "", "display_name": "", "error": "", "fine_tune_script": { "description": "", "display_name": "", "docker_image_name": "", "fine_tune_schema": { "description": "", "id": "", "name": "", "schema": { "additionalProperties": true, "basic": [\ ""\ ], "properties": {}, "required": [\ ""\ ], "type": "" } }, "id": "", "name": "", "script_type": "" }, "finished_at": "", "gpu_count": 123, "gpu_model": "", "id": "", "inserted_at": "", "last_credit_check": "", "name": "", "output_resource": {}, "queue_position": 123, "rate_per_second": "", "repository_id": "", "resource": { "path": "", "version": "" }, "source_model": {}, "started_at": "", "status": "", "total_token_count": 0, "training_params": { "answer_column": "", "batch_size": 123, "enable_thinking": true, "epochs": 123, "grad_accum": 123, "learning_rate": 123, "logging_steps": 123, "lora_alpha": 123, "lora_rank": 123, "neftune_noise_alpha": 123, "question_column": "", "save_steps_ratio": 123, "save_strategy": "", "seq_length": 123, "use_lora": true }, "updated_at": "", "use_lora": true }, "status": "", "status_message": "" } POST / api / repos / {namespace} / {repo\_name} / fine\_tunes / {id} / actions / run Try it Run a fine-tune job cURL curl --request POST \ --url https://hub.oxen.ai/api/repos/{namespace}/{repo_name}/fine_tunes/{id}/actions/run \ --header 'Authorization: Bearer ' 200 404 { "fine_tune": { "base_model": "", "created_by": { "id": "", "image": "", "name": "", "username": "" }, "credits_used": "", "deployed_model": {}, "description": "", "display_name": "", "error": "", "fine_tune_script": { "description": "", "display_name": "", "docker_image_name": "", "fine_tune_schema": { "description": "", "id": "", "name": "", "schema": { "additionalProperties": true, "basic": [\ ""\ ], "properties": {}, "required": [\ ""\ ], "type": "" } }, "id": "", "name": "", "script_type": "" }, "finished_at": "", "gpu_count": 123, "gpu_model": "", "id": "", "inserted_at": "", "last_credit_check": "", "name": "", "output_resource": {}, "queue_position": 123, "rate_per_second": "", "repository_id": "", "resource": { "path": "", "version": "" }, "source_model": {}, "started_at": "", "status": "", "total_token_count": 0, "training_params": { "answer_column": "", "batch_size": 123, "enable_thinking": true, "epochs": 123, "grad_accum": 123, "learning_rate": 123, "logging_steps": 123, "lora_alpha": 123, "lora_rank": 123, "neftune_noise_alpha": 123, "question_column": "", "save_steps_ratio": 123, "save_strategy": "", "seq_length": 123, "use_lora": true }, "updated_at": "", "use_lora": true }, "status": "", "status_message": "" } #### Authorizations [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/run-a-fine-tune-job#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/run-a-fine-tune-job#parameter-id) id string required Fine-tune ID #### Response 200 application/json Run fine-tune response Standard wrapper for fine-tune /run responses. [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/run-a-fine-tune-job#response-fine-tune) fine\_tune FineTuneRun Β· object Fine-tune job resource as returned by /run Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/run-a-fine-tune-job#response-status) status string High-level status string (for example, 'success'). [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/run-a-fine-tune-job#response-status-message) status\_message string Human-readable status message (for example, 'resource\_found'). [Update a fine-tune job](https://docs.oxen.ai/fine-tuning-api/fine_tunes/update-a-fine-tune-job) [Stop a running fine-tune job](https://docs.oxen.ai/fine-tuning-api/fine_tunes/stop-a-running-fine-tune-job) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Get generation status - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/fine-tuning-api/get-generation-status#content-area) Get generation status cURL curl --request GET \ --url https://hub.oxen.ai/api/ai/queue/{generation_id} 200 404 { "enqueued_at": 123, "generation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "model_name": "", "completed_at": 123, "error_message": "", "result_url": "", "started_at": 123, "target_directory": "", "target_namespace": "", "target_repo": "" } GET / api / ai / queue / {generation\_id} Try it Get generation status cURL curl --request GET \ --url https://hub.oxen.ai/api/ai/queue/{generation_id} 200 404 { "enqueued_at": 123, "generation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "model_name": "", "completed_at": 123, "error_message": "", "result_url": "", "started_at": 123, "target_directory": "", "target_namespace": "", "target_repo": "" } #### Path Parameters [​](https://docs.oxen.ai/fine-tuning-api/get-generation-status#parameter-generation-id) generation\_id string required #### Response 200 application/json Generation details Compact status payload for a single queued generation, used by the workbench to poll progress. For the full payload (cost, user, etc.), see `/api/ai/generations/:id`. [​](https://docs.oxen.ai/fine-tuning-api/get-generation-status#response-enqueued-at) enqueued\_at integer required Unix timestamp [​](https://docs.oxen.ai/fine-tuning-api/get-generation-status#response-generation-id) generation\_id string required [​](https://docs.oxen.ai/fine-tuning-api/get-generation-status#response-media-type) media\_type enum required Available options: `image`, `video` [​](https://docs.oxen.ai/fine-tuning-api/get-generation-status#response-model-name) model\_name string required [​](https://docs.oxen.ai/fine-tuning-api/get-generation-status#response-status) status enum required Available options: `queued`, `processing`, `succeeded`, `failed`, `cancelled` [​](https://docs.oxen.ai/fine-tuning-api/get-generation-status#response-completed-at-one-of-0) completed\_at integer | null Unix timestamp [​](https://docs.oxen.ai/fine-tuning-api/get-generation-status#response-error-message-one-of-0) error\_message string | null [​](https://docs.oxen.ai/fine-tuning-api/get-generation-status#response-result-url-one-of-0) result\_url string | null [​](https://docs.oxen.ai/fine-tuning-api/get-generation-status#response-started-at-one-of-0) started\_at integer | null Unix timestamp [​](https://docs.oxen.ai/fine-tuning-api/get-generation-status#response-target-directory-one-of-0) target\_directory string | null [​](https://docs.oxen.ai/fine-tuning-api/get-generation-status#response-target-namespace-one-of-0) target\_namespace string | null [​](https://docs.oxen.ai/fine-tuning-api/get-generation-status#response-target-repo-one-of-0) target\_repo string | null [Enqueue generation](https://docs.oxen.ai/fine-tuning-api/enqueue-generation) [Cancel generation](https://docs.oxen.ai/fine-tuning-api/cancel-generation) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # List favorite models - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/fine-tuning-api/list-favorite-models#content-area) List favorite models cURL curl --request GET \ --url https://hub.oxen.ai/api/ai/models/favorites 200 { "data": [\ {\ "created": 123,\ "id": "",\ "owned_by": "",\ "capabilities": {\ "input": [\ ""\ ],\ "output": [\ ""\ ]\ },\ "deployments": [\ {}\ ],\ "description": "",\ "developer": {\ "logo": "",\ "name": ""\ },\ "display_name": "",\ "fine_tuning": {\ "actions": [\ ""\ ],\ "cost_per_second": 123\ },\ "image_url": "",\ "pricing": {\ "cost_per_image": 123,\ "cost_per_second": 123,\ "cost_per_second_high_res": 123,\ "cost_per_second_with_audio": 123,\ "input_cost_per_token": 123,\ "output_cost_per_token": 123\ },\ "released_at": "",\ "request_schema": {},\ "showcase": {\ "gallery": [\ {\ "alt": "",\ "src": "",\ "category": "",\ "details": "",\ "prompt": "",\ "title": ""\ }\ ],\ "hero_image": "",\ "tagline": ""\ },\ "source_model": "",\ "summary": ""\ }\ ] } GET / api / ai / models / favorites Try it List favorite models cURL curl --request GET \ --url https://hub.oxen.ai/api/ai/models/favorites 200 { "data": [\ {\ "created": 123,\ "id": "",\ "owned_by": "",\ "capabilities": {\ "input": [\ ""\ ],\ "output": [\ ""\ ]\ },\ "deployments": [\ {}\ ],\ "description": "",\ "developer": {\ "logo": "",\ "name": ""\ },\ "display_name": "",\ "fine_tuning": {\ "actions": [\ ""\ ],\ "cost_per_second": 123\ },\ "image_url": "",\ "pricing": {\ "cost_per_image": 123,\ "cost_per_second": 123,\ "cost_per_second_high_res": 123,\ "cost_per_second_with_audio": 123,\ "input_cost_per_token": 123,\ "output_cost_per_token": 123\ },\ "released_at": "",\ "request_schema": {},\ "showcase": {\ "gallery": [\ {\ "alt": "",\ "src": "",\ "category": "",\ "details": "",\ "prompt": "",\ "title": ""\ }\ ],\ "hero_image": "",\ "tagline": ""\ },\ "source_model": "",\ "summary": ""\ }\ ] } #### Response 200 - application/json Favorite models OpenAI-compatible response for listing models. [​](https://docs.oxen.ai/fine-tuning-api/list-favorite-models#response-data) data Model Β· object\[\] required Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/list-favorite-models#response-object) object enum required Available options: `list` [List models](https://docs.oxen.ai/fine-tuning-api/list-models) [List featured models](https://docs.oxen.ai/fine-tuning-api/list-featured-models) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Search models - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/fine-tuning-api/search-models#content-area) Search models cURL curl --request GET \ --url https://hub.oxen.ai/api/ai/models/search 200 { "data": [\ {\ "created": 123,\ "id": "",\ "owned_by": "",\ "capabilities": {\ "input": [\ ""\ ],\ "output": [\ ""\ ]\ },\ "deployments": [\ {}\ ],\ "description": "",\ "developer": {\ "logo": "",\ "name": ""\ },\ "display_name": "",\ "fine_tuning": {\ "actions": [\ ""\ ],\ "cost_per_second": 123\ },\ "image_url": "",\ "pricing": {\ "cost_per_image": 123,\ "cost_per_second": 123,\ "cost_per_second_high_res": 123,\ "cost_per_second_with_audio": 123,\ "input_cost_per_token": 123,\ "output_cost_per_token": 123\ },\ "released_at": "",\ "request_schema": {},\ "showcase": {\ "gallery": [\ {\ "alt": "",\ "src": "",\ "category": "",\ "details": "",\ "prompt": "",\ "title": ""\ }\ ],\ "hero_image": "",\ "tagline": ""\ },\ "source_model": "",\ "summary": ""\ }\ ] } GET / api / ai / models / search Try it Search models cURL curl --request GET \ --url https://hub.oxen.ai/api/ai/models/search 200 { "data": [\ {\ "created": 123,\ "id": "",\ "owned_by": "",\ "capabilities": {\ "input": [\ ""\ ],\ "output": [\ ""\ ]\ },\ "deployments": [\ {}\ ],\ "description": "",\ "developer": {\ "logo": "",\ "name": ""\ },\ "display_name": "",\ "fine_tuning": {\ "actions": [\ ""\ ],\ "cost_per_second": 123\ },\ "image_url": "",\ "pricing": {\ "cost_per_image": 123,\ "cost_per_second": 123,\ "cost_per_second_high_res": 123,\ "cost_per_second_with_audio": 123,\ "input_cost_per_token": 123,\ "output_cost_per_token": 123\ },\ "released_at": "",\ "request_schema": {},\ "showcase": {\ "gallery": [\ {\ "alt": "",\ "src": "",\ "category": "",\ "details": "",\ "prompt": "",\ "title": ""\ }\ ],\ "hero_image": "",\ "tagline": ""\ },\ "source_model": "",\ "summary": ""\ }\ ] } #### Query Parameters [​](https://docs.oxen.ai/fine-tuning-api/search-models#parameter-search) search string required #### Response 200 - application/json Search results OpenAI-compatible response for listing models. [​](https://docs.oxen.ai/fine-tuning-api/search-models#response-data) data Model Β· object\[\] required Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/search-models#response-object) object enum required Available options: `list` [List featured models](https://docs.oxen.ai/fine-tuning-api/list-featured-models) [Retrieve model](https://docs.oxen.ai/fine-tuning-api/retrieve-model) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Data frame - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/python-api/data_frame#content-area) [​](https://docs.oxen.ai/python-api/data_frame#oxen-data_frame) oxen.data\_frame =================================================================================== [​](https://docs.oxen.ai/python-api/data_frame#dataframe-objects) DataFrame Objects -------------------------------------------------------------------------------------- class DataFrame() The DataFrame class allows you to perform CRUD operations on a remote data frame. If you pass in a [Workspace](https://docs.oxen.ai/getting-started/workspaces) or a [RemoteRepo](https://docs.oxen.ai/concepts/remote-repos) the data is indexed into DuckDB on an oxen-server without downloading the data locally. [​](https://docs.oxen.ai/python-api/data_frame#examples) Examples -------------------------------------------------------------------- ### [​](https://docs.oxen.ai/python-api/data_frame#crud-operations) CRUD Operations Index a data frame in a workspace. from oxen import DataFrame # Connect to and index the data frame # Note: This must be an existing file committed to the repo # indexing may take a while for large files data_frame = DataFrame("datasets/SpamOrHam", "data.tsv") # Add a row row_id = data_frame.insert_row({"category": "spam", "message": "Hello, do I have an offer for you!"}) # Get a row by id row = data_frame.get_row_by_id(row_id) print(row) # Update a row row = data_frame.update_row(row_id, {"category": "ham"}) print(row) # Delete a row data_frame.delete_row(row_id) # Get the current changes to the data frame status = data_frame.diff() print(status.added_files()) # Commit the changes data_frame.commit("Updating data.csv") [​](https://docs.oxen.ai/python-api/data_frame#__init__) \_\_init\_\_ ------------------------------------------------------------------------ def __init__(remote: Union[str, RemoteRepo, Workspace], path: str, host: str = "hub.oxen.ai", branch: Optional[str] = None, scheme: str = "https", workspace_name: Optional[str] = None) Initialize the DataFrame class. Will index the data frame into duckdb on init. Will throw an error if the data frame does not exist. **Arguments**: * `remote` - `str`, `RemoteRepo`, or `Workspace` The workspace or remote repo the data frame is in. * `path` - `str` The path of the data frame file in the repository. * `host` - `str` The host of the oxen-server. Defaults to β€œhub.oxen.ai”. * `branch` - `Optional[str]` The branch of the remote repo. Defaults to None. * `scheme` - `str` The scheme of the remote repo. Defaults to β€œhttps”. [​](https://docs.oxen.ai/python-api/data_frame#workspace_url) workspace\_url ------------------------------------------------------------------------------- def workspace_url(host: str = "oxen.ai", scheme: str = "https") -> str Get the url of the data frame. [​](https://docs.oxen.ai/python-api/data_frame#size) size ------------------------------------------------------------ def size() -> tuple[int, int] Get the size of the data frame. Returns a tuple of (rows, columns) [​](https://docs.oxen.ai/python-api/data_frame#page_size) page\_size ----------------------------------------------------------------------- def page_size() -> int Get the page size of the data frame for pagination in list() command. **Returns**: The page size of the data frame. [​](https://docs.oxen.ai/python-api/data_frame#total_pages) total\_pages --------------------------------------------------------------------------- def total_pages() -> int Get the total number of pages in the data frame for pagination in list() command. **Returns**: The total number of pages in the data frame. [​](https://docs.oxen.ai/python-api/data_frame#list_page) list\_page ----------------------------------------------------------------------- def list_page(page_num: int = 1) -> List[dict] List the rows within the data frame. **Arguments**: * `page_num` - `int` The page number of the data frame to list. We default to page size of 100 for now. **Returns**: A list of rows from the data frame. [​](https://docs.oxen.ai/python-api/data_frame#insert_row) insert\_row ------------------------------------------------------------------------- def insert_row(data: dict) Insert a single row of data into the data frame. **Arguments**: * `data` - `dict` A dictionary representing a single row of data. The keys must match a subset of the columns in the data frame. If a column is not present in the dictionary, it will be set to an empty value. **Returns**: The id of the row that was inserted. [​](https://docs.oxen.ai/python-api/data_frame#where_sql_from_dict) where\_sql\_from\_dict --------------------------------------------------------------------------------------------- def where_sql_from_dict(attributes: dict, operator: str = "AND") -> str Generate the SQL from the attributes. [​](https://docs.oxen.ai/python-api/data_frame#select_sql_from_dict) select\_sql\_from\_dict ----------------------------------------------------------------------------------------------- def select_sql_from_dict(attributes: dict, columns: Optional[List[str]] = None) -> str Generate the SQL from the attributes. [​](https://docs.oxen.ai/python-api/data_frame#get_embeddings) get\_embeddings --------------------------------------------------------------------------------- def get_embeddings(attributes: dict, column: str = "embedding") -> List[float] Get the embedding from the data frame. [​](https://docs.oxen.ai/python-api/data_frame#is_nearest_neighbors_enabled) is\_nearest\_neighbors\_enabled --------------------------------------------------------------------------------------------------------------- def is_nearest_neighbors_enabled(column="embedding") Check if the embeddings column is indexed in the data frame. [​](https://docs.oxen.ai/python-api/data_frame#enable_nearest_neighbors) enable\_nearest\_neighbors ------------------------------------------------------------------------------------------------------ def enable_nearest_neighbors(column: str = "embedding") Index the embeddings in the data frame. [​](https://docs.oxen.ai/python-api/data_frame#query) query -------------------------------------------------------------- def query(sql: Optional[str] = None, find_embedding_where: Optional[dict] = None, embedding: Optional[list[float]] = None, sort_by_similarity_to: Optional[str] = None, page_num: int = 1, page_size: int = 10) Sort the data frame by the embedding. [​](https://docs.oxen.ai/python-api/data_frame#nearest_neighbors_search) nearest\_neighbors\_search ------------------------------------------------------------------------------------------------------ def nearest_neighbors_search(find_embedding_where: dict, sort_by_similarity_to: str = "embedding") Get the nearest neighbors to the embedding. [​](https://docs.oxen.ai/python-api/data_frame#get_by) get\_by ----------------------------------------------------------------- def get_by(attributes: dict) Get a single row of data by attributes. [​](https://docs.oxen.ai/python-api/data_frame#get_row) get\_row ------------------------------------------------------------------- def get_row(idx: int) Get a single row of data by index. **Arguments**: * `idx` - `int` The index of the row to get. **Returns**: A dictionary representing the row. [​](https://docs.oxen.ai/python-api/data_frame#get_row_by_id) get\_row\_by\_id --------------------------------------------------------------------------------- def get_row_by_id(id: str) Get a single row of data by id. **Arguments**: * `id` - `str` The id of the row to get. **Returns**: A dictionary representing the row. [​](https://docs.oxen.ai/python-api/data_frame#update_row) update\_row ------------------------------------------------------------------------- def update_row(id: str, data: dict) Update a single row of data by id. **Arguments**: * `id` - `str` The id of the row to update. * `data` - `dict` A dictionary representing a single row of data. The keys must match a subset of the columns in the data frame. If a column is not present in the dictionary, it will be set to an empty value. **Returns**: The updated row as a dictionary. [​](https://docs.oxen.ai/python-api/data_frame#delete_row) delete\_row ------------------------------------------------------------------------- def delete_row(id: str) Delete a single row of data by id. **Arguments**: * `id` - `str` The id of the row to delete. [​](https://docs.oxen.ai/python-api/data_frame#restore) restore ------------------------------------------------------------------ def restore() Unstage any changes to the schema or contents of a data frame [​](https://docs.oxen.ai/python-api/data_frame#commit) commit ---------------------------------------------------------------- def commit(message: str, branch: Optional[str] = None) Commit the current changes to the data frame. **Arguments**: * `message` - `str` The message to commit the changes. * `branch` - `str` The branch to commit the changes to. Defaults to the current branch. [Clone](https://docs.oxen.ai/python-api/clone) [Datasets](https://docs.oxen.ai/python-api/datasets) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Stop a running fine-tune job - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/fine-tuning-api/fine_tunes/stop-a-running-fine-tune-job#content-area) Stop a running fine-tune job cURL curl --request POST \ --url https://hub.oxen.ai/api/repos/{namespace}/{repo_name}/fine_tunes/{id}/actions/stop \ --header 'Authorization: Bearer ' 200 404 { "fine_tune": { "base_model": "", "created_by": { "id": "", "image": "", "name": "", "username": "" }, "credits_used": "", "deployed_model": {}, "description": "", "display_name": "", "error": "", "fine_tune_script": { "description": "", "display_name": "", "docker_image_name": "", "fine_tune_schema": { "description": "", "id": "", "name": "", "schema": { "additionalProperties": true, "basic": [\ ""\ ], "properties": {}, "required": [\ ""\ ], "type": "" } }, "id": "", "name": "", "script_type": "" }, "finished_at": "", "gpu_count": 123, "gpu_model": "", "id": "", "inserted_at": "", "last_credit_check": "", "name": "", "output_resource": {}, "queue_position": 123, "rate_per_second": "", "repository_id": "", "resource": { "path": "", "version": "" }, "source_model": {}, "started_at": "", "status": "", "total_token_count": 0, "training_params": { "answer_column": "", "batch_size": 123, "enable_thinking": true, "epochs": 123, "grad_accum": 123, "learning_rate": 123, "logging_steps": 123, "lora_alpha": 123, "lora_rank": 123, "neftune_noise_alpha": 123, "question_column": "", "save_steps_ratio": 123, "save_strategy": "", "seq_length": 123, "use_lora": true }, "updated_at": "", "use_lora": true }, "status": "", "status_message": "" } POST / api / repos / {namespace} / {repo\_name} / fine\_tunes / {id} / actions / stop Try it Stop a running fine-tune job cURL curl --request POST \ --url https://hub.oxen.ai/api/repos/{namespace}/{repo_name}/fine_tunes/{id}/actions/stop \ --header 'Authorization: Bearer ' 200 404 { "fine_tune": { "base_model": "", "created_by": { "id": "", "image": "", "name": "", "username": "" }, "credits_used": "", "deployed_model": {}, "description": "", "display_name": "", "error": "", "fine_tune_script": { "description": "", "display_name": "", "docker_image_name": "", "fine_tune_schema": { "description": "", "id": "", "name": "", "schema": { "additionalProperties": true, "basic": [\ ""\ ], "properties": {}, "required": [\ ""\ ], "type": "" } }, "id": "", "name": "", "script_type": "" }, "finished_at": "", "gpu_count": 123, "gpu_model": "", "id": "", "inserted_at": "", "last_credit_check": "", "name": "", "output_resource": {}, "queue_position": 123, "rate_per_second": "", "repository_id": "", "resource": { "path": "", "version": "" }, "source_model": {}, "started_at": "", "status": "", "total_token_count": 0, "training_params": { "answer_column": "", "batch_size": 123, "enable_thinking": true, "epochs": 123, "grad_accum": 123, "learning_rate": 123, "logging_steps": 123, "lora_alpha": 123, "lora_rank": 123, "neftune_noise_alpha": 123, "question_column": "", "save_steps_ratio": 123, "save_strategy": "", "seq_length": 123, "use_lora": true }, "updated_at": "", "use_lora": true }, "status": "", "status_message": "" } #### Authorizations [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/stop-a-running-fine-tune-job#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/stop-a-running-fine-tune-job#parameter-id) id string required Fine-tune ID #### Response 200 application/json Stop fine-tune response Standard wrapper for fine-tune /stop responses. [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/stop-a-running-fine-tune-job#response-fine-tune) fine\_tune FineTuneRun Β· object Fine-tune job resource as returned by /stop Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/stop-a-running-fine-tune-job#response-status) status string High-level status string (for example, 'success'). [​](https://docs.oxen.ai/fine-tuning-api/fine_tunes/stop-a-running-fine-tune-job#response-status-message) status\_message string Human-readable status message (for example, 'resource\_found'). [Run a fine-tune job](https://docs.oxen.ai/fine-tuning-api/fine_tunes/run-a-fine-tune-job) [List checkpoints for a fine-tune job](https://docs.oxen.ai/fine-tuning-api/fine_tunes/list-checkpoints-for-a-fine-tune-job) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Update model - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/fine-tuning-api/update-model#content-area) Update model cURL curl --request PUT \ --url https://hub.oxen.ai/api/ai/models/{id} \ --header 'Content-Type: application/json' \ --data '{}' 200 { "created": 123, "id": "", "owned_by": "", "capabilities": { "input": [\ ""\ ], "output": [\ ""\ ] }, "deployments": [\ {}\ ], "description": "", "developer": { "logo": "", "name": "" }, "display_name": "", "fine_tuning": { "actions": [\ ""\ ], "cost_per_second": 123 }, "image_url": "", "pricing": { "cost_per_image": 123, "cost_per_second": 123, "cost_per_second_high_res": 123, "cost_per_second_with_audio": 123, "input_cost_per_token": 123, "output_cost_per_token": 123 }, "released_at": "", "request_schema": {}, "showcase": { "gallery": [\ {\ "alt": "",\ "src": "",\ "category": "",\ "details": "",\ "prompt": "",\ "title": ""\ }\ ], "hero_image": "", "tagline": "" }, "source_model": "", "summary": "" } PUT / api / ai / models / {id} Try it Update model cURL curl --request PUT \ --url https://hub.oxen.ai/api/ai/models/{id} \ --header 'Content-Type: application/json' \ --data '{}' 200 { "created": 123, "id": "", "owned_by": "", "capabilities": { "input": [\ ""\ ], "output": [\ ""\ ] }, "deployments": [\ {}\ ], "description": "", "developer": { "logo": "", "name": "" }, "display_name": "", "fine_tuning": { "actions": [\ ""\ ], "cost_per_second": 123 }, "image_url": "", "pricing": { "cost_per_image": 123, "cost_per_second": 123, "cost_per_second_high_res": 123, "cost_per_second_with_audio": 123, "input_cost_per_token": 123, "output_cost_per_token": 123 }, "released_at": "", "request_schema": {}, "showcase": { "gallery": [\ {\ "alt": "",\ "src": "",\ "category": "",\ "details": "",\ "prompt": "",\ "title": ""\ }\ ], "hero_image": "", "tagline": "" }, "source_model": "", "summary": "" } #### Path Parameters [​](https://docs.oxen.ai/fine-tuning-api/update-model#parameter-id) id string required #### Body application/json Model update params The body is of type `object`. #### Response 200 - application/json Updated model Represents a model available for inference or fine-tuning. Compatible with the OpenAI model object. [​](https://docs.oxen.ai/fine-tuning-api/update-model#response-created) created integer required Unix timestamp when the model was registered [​](https://docs.oxen.ai/fine-tuning-api/update-model#response-id) id string required Model identifier used in API calls [​](https://docs.oxen.ai/fine-tuning-api/update-model#response-object) object enum required Available options: `model` [​](https://docs.oxen.ai/fine-tuning-api/update-model#response-owned-by) owned\_by string required "oxen" for base models, owner namespace for custom models [​](https://docs.oxen.ai/fine-tuning-api/update-model#response-capabilities) capabilities object Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/update-model#response-deployments) deployments object\[\] Active deployments. Empty for base models. Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/update-model#response-description-one-of-0) description string | null [​](https://docs.oxen.ai/fine-tuning-api/update-model#response-developer-one-of-0) developer object Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/update-model#response-display-name) display\_name string [​](https://docs.oxen.ai/fine-tuning-api/update-model#response-endpoint) endpoint enum API endpoint to call this model Available options: `/chat/completions`, `/images/generate`, `/videos/generate` [​](https://docs.oxen.ai/fine-tuning-api/update-model#response-fine-tuning-one-of-0) fine\_tuning object Fine-tuning info, or null if model is not fine-tuneable Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/update-model#response-image-url-one-of-0) image\_url string | null [​](https://docs.oxen.ai/fine-tuning-api/update-model#response-model-type) model\_type enum Available options: `base`, `custom` [​](https://docs.oxen.ai/fine-tuning-api/update-model#response-pricing) pricing object Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/update-model#response-released-at-one-of-0) released\_at string | null [​](https://docs.oxen.ai/fine-tuning-api/update-model#response-request-schema-one-of-0) request\_schema object JSON Schema describing model-specific parameters [​](https://docs.oxen.ai/fine-tuning-api/update-model#response-showcase-one-of-0) showcase object Optional marketing content rendered on the public model showcase page Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/update-model#response-source-model-one-of-0) source\_model string | null Base model this was fine-tuned from [​](https://docs.oxen.ai/fine-tuning-api/update-model#response-summary-one-of-0) summary string | null [Retrieve model](https://docs.oxen.ai/fine-tuning-api/retrieve-model) [Delete custom model](https://docs.oxen.ai/fine-tuning-api/delete-custom-model) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Retrieve model - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/fine-tuning-api/retrieve-model#content-area) Retrieve model cURL curl --request GET \ --url https://hub.oxen.ai/api/ai/models/{id} 200 404 { "created": 123, "id": "", "owned_by": "", "capabilities": { "input": [\ ""\ ], "output": [\ ""\ ] }, "deployments": [\ {}\ ], "description": "", "developer": { "logo": "", "name": "" }, "display_name": "", "fine_tuning": { "actions": [\ ""\ ], "cost_per_second": 123 }, "image_url": "", "pricing": { "cost_per_image": 123, "cost_per_second": 123, "cost_per_second_high_res": 123, "cost_per_second_with_audio": 123, "input_cost_per_token": 123, "output_cost_per_token": 123 }, "released_at": "", "request_schema": {}, "showcase": { "gallery": [\ {\ "alt": "",\ "src": "",\ "category": "",\ "details": "",\ "prompt": "",\ "title": ""\ }\ ], "hero_image": "", "tagline": "" }, "source_model": "", "summary": "" } GET / api / ai / models / {id} Try it Retrieve model cURL curl --request GET \ --url https://hub.oxen.ai/api/ai/models/{id} 200 404 { "created": 123, "id": "", "owned_by": "", "capabilities": { "input": [\ ""\ ], "output": [\ ""\ ] }, "deployments": [\ {}\ ], "description": "", "developer": { "logo": "", "name": "" }, "display_name": "", "fine_tuning": { "actions": [\ ""\ ], "cost_per_second": 123 }, "image_url": "", "pricing": { "cost_per_image": 123, "cost_per_second": 123, "cost_per_second_high_res": 123, "cost_per_second_with_audio": 123, "input_cost_per_token": 123, "output_cost_per_token": 123 }, "released_at": "", "request_schema": {}, "showcase": { "gallery": [\ {\ "alt": "",\ "src": "",\ "category": "",\ "details": "",\ "prompt": "",\ "title": ""\ }\ ], "hero_image": "", "tagline": "" }, "source_model": "", "summary": "" } #### Path Parameters [​](https://docs.oxen.ai/fine-tuning-api/retrieve-model#parameter-id) id string required Model ID (UUID) or name #### Query Parameters [​](https://docs.oxen.ai/fine-tuning-api/retrieve-model#parameter-deployment-status) deployment\_status enum Pass "live" to refresh deployment status from provider before responding Available options: `live` #### Response 200 application/json Model details Represents a model available for inference or fine-tuning. Compatible with the OpenAI model object. [​](https://docs.oxen.ai/fine-tuning-api/retrieve-model#response-created) created integer required Unix timestamp when the model was registered [​](https://docs.oxen.ai/fine-tuning-api/retrieve-model#response-id) id string required Model identifier used in API calls [​](https://docs.oxen.ai/fine-tuning-api/retrieve-model#response-object) object enum required Available options: `model` [​](https://docs.oxen.ai/fine-tuning-api/retrieve-model#response-owned-by) owned\_by string required "oxen" for base models, owner namespace for custom models [​](https://docs.oxen.ai/fine-tuning-api/retrieve-model#response-capabilities) capabilities object Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/retrieve-model#response-deployments) deployments object\[\] Active deployments. Empty for base models. Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/retrieve-model#response-description-one-of-0) description string | null [​](https://docs.oxen.ai/fine-tuning-api/retrieve-model#response-developer-one-of-0) developer object Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/retrieve-model#response-display-name) display\_name string [​](https://docs.oxen.ai/fine-tuning-api/retrieve-model#response-endpoint) endpoint enum API endpoint to call this model Available options: `/chat/completions`, `/images/generate`, `/videos/generate` [​](https://docs.oxen.ai/fine-tuning-api/retrieve-model#response-fine-tuning-one-of-0) fine\_tuning object Fine-tuning info, or null if model is not fine-tuneable Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/retrieve-model#response-image-url-one-of-0) image\_url string | null [​](https://docs.oxen.ai/fine-tuning-api/retrieve-model#response-model-type) model\_type enum Available options: `base`, `custom` [​](https://docs.oxen.ai/fine-tuning-api/retrieve-model#response-pricing) pricing object Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/retrieve-model#response-released-at-one-of-0) released\_at string | null [​](https://docs.oxen.ai/fine-tuning-api/retrieve-model#response-request-schema-one-of-0) request\_schema object JSON Schema describing model-specific parameters [​](https://docs.oxen.ai/fine-tuning-api/retrieve-model#response-showcase-one-of-0) showcase object Optional marketing content rendered on the public model showcase page Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/retrieve-model#response-source-model-one-of-0) source\_model string | null Base model this was fine-tuned from [​](https://docs.oxen.ai/fine-tuning-api/retrieve-model#response-summary-one-of-0) summary string | null [Search models](https://docs.oxen.ai/fine-tuning-api/search-models) [Update model](https://docs.oxen.ai/fine-tuning-api/update-model) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Unfavorite a model - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/fine-tuning-api/unfavorite-a-model#content-area) Unfavorite a model cURL curl --request DELETE \ --url https://hub.oxen.ai/api/ai/models/{id}/favorite 200 { "created": 123, "id": "", "owned_by": "", "capabilities": { "input": [\ ""\ ], "output": [\ ""\ ] }, "deployments": [\ {}\ ], "description": "", "developer": { "logo": "", "name": "" }, "display_name": "", "fine_tuning": { "actions": [\ ""\ ], "cost_per_second": 123 }, "image_url": "", "pricing": { "cost_per_image": 123, "cost_per_second": 123, "cost_per_second_high_res": 123, "cost_per_second_with_audio": 123, "input_cost_per_token": 123, "output_cost_per_token": 123 }, "released_at": "", "request_schema": {}, "showcase": { "gallery": [\ {\ "alt": "",\ "src": "",\ "category": "",\ "details": "",\ "prompt": "",\ "title": ""\ }\ ], "hero_image": "", "tagline": "" }, "source_model": "", "summary": "" } DELETE / api / ai / models / {id} / favorite Try it Unfavorite a model cURL curl --request DELETE \ --url https://hub.oxen.ai/api/ai/models/{id}/favorite 200 { "created": 123, "id": "", "owned_by": "", "capabilities": { "input": [\ ""\ ], "output": [\ ""\ ] }, "deployments": [\ {}\ ], "description": "", "developer": { "logo": "", "name": "" }, "display_name": "", "fine_tuning": { "actions": [\ ""\ ], "cost_per_second": 123 }, "image_url": "", "pricing": { "cost_per_image": 123, "cost_per_second": 123, "cost_per_second_high_res": 123, "cost_per_second_with_audio": 123, "input_cost_per_token": 123, "output_cost_per_token": 123 }, "released_at": "", "request_schema": {}, "showcase": { "gallery": [\ {\ "alt": "",\ "src": "",\ "category": "",\ "details": "",\ "prompt": "",\ "title": ""\ }\ ], "hero_image": "", "tagline": "" }, "source_model": "", "summary": "" } #### Path Parameters [​](https://docs.oxen.ai/fine-tuning-api/unfavorite-a-model#parameter-id) id string required #### Response 200 - application/json Model unfavorited Represents a model available for inference or fine-tuning. Compatible with the OpenAI model object. [​](https://docs.oxen.ai/fine-tuning-api/unfavorite-a-model#response-created) created integer required Unix timestamp when the model was registered [​](https://docs.oxen.ai/fine-tuning-api/unfavorite-a-model#response-id) id string required Model identifier used in API calls [​](https://docs.oxen.ai/fine-tuning-api/unfavorite-a-model#response-object) object enum required Available options: `model` [​](https://docs.oxen.ai/fine-tuning-api/unfavorite-a-model#response-owned-by) owned\_by string required "oxen" for base models, owner namespace for custom models [​](https://docs.oxen.ai/fine-tuning-api/unfavorite-a-model#response-capabilities) capabilities object Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/unfavorite-a-model#response-deployments) deployments object\[\] Active deployments. Empty for base models. Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/unfavorite-a-model#response-description-one-of-0) description string | null [​](https://docs.oxen.ai/fine-tuning-api/unfavorite-a-model#response-developer-one-of-0) developer object Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/unfavorite-a-model#response-display-name) display\_name string [​](https://docs.oxen.ai/fine-tuning-api/unfavorite-a-model#response-endpoint) endpoint enum API endpoint to call this model Available options: `/chat/completions`, `/images/generate`, `/videos/generate` [​](https://docs.oxen.ai/fine-tuning-api/unfavorite-a-model#response-fine-tuning-one-of-0) fine\_tuning object Fine-tuning info, or null if model is not fine-tuneable Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/unfavorite-a-model#response-image-url-one-of-0) image\_url string | null [​](https://docs.oxen.ai/fine-tuning-api/unfavorite-a-model#response-model-type) model\_type enum Available options: `base`, `custom` [​](https://docs.oxen.ai/fine-tuning-api/unfavorite-a-model#response-pricing) pricing object Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/unfavorite-a-model#response-released-at-one-of-0) released\_at string | null [​](https://docs.oxen.ai/fine-tuning-api/unfavorite-a-model#response-request-schema-one-of-0) request\_schema object JSON Schema describing model-specific parameters [​](https://docs.oxen.ai/fine-tuning-api/unfavorite-a-model#response-showcase-one-of-0) showcase object Optional marketing content rendered on the public model showcase page Show child attributes [​](https://docs.oxen.ai/fine-tuning-api/unfavorite-a-model#response-source-model-one-of-0) source\_model string | null Base model this was fine-tuned from [​](https://docs.oxen.ai/fine-tuning-api/unfavorite-a-model#response-summary-one-of-0) summary string | null [Favorite a model](https://docs.oxen.ai/fine-tuning-api/favorite-a-model) [List in-flight queue items](https://docs.oxen.ai/fine-tuning-api/list-in-flight-queue-items) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Introduction - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/python-api#content-area) [​](https://docs.oxen.ai/python-api#install) Install ------------------------------------------------------- pip install oxenai [​](https://docs.oxen.ai/python-api#clone-repository) Clone Repository ------------------------------------------------------------------------- Clone a repository from the [Oxen Hub](https://oxen.ai/) or your own [oxen-server](https://docs.oxen.ai/getting-started/oxen-server) . Detailed documentation for the [clone](https://docs.oxen.ai/python-api/clone) method can be found in the [Module Reference](https://docs.oxen.ai/python-api#module-reference) below. import oxen oxen.clone("ox/SpanishToEnglish") This will create a directory called `SpanishToEnglish` in your current working directory and download the latest version of the repository. If you have not setup your API Key locally, you will get an error cloning data. View our [Authentication & Authorization documentation](https://docs.oxen.ai/getting-started/auth) to learn more. [​](https://docs.oxen.ai/python-api#initialize-local-repository) Initialize Local Repository ----------------------------------------------------------------------------------------------- If you are creating a new repository from scratch, you can initialize it with the [init](https://docs.oxen.ai/python-api/init) method. We will be using a fictional repository called `CatsVsDogs` for this example. import oxen import os # Create an empty directory named CatsVsDogs directory = "CatsVsDogs" os.makedirs(directory) # Initialize the Oxen Repository repo = oxen.init(directory) This will create a `.oxen` directory to keep track of changes as you make them. [​](https://docs.oxen.ai/python-api#load-existing-repository) Load Existing Repository ----------------------------------------------------------------------------------------- Use the [repo](https://docs.oxen.ai/python-api/repo) class to interact with a repository that has already been initialized. from oxen import Repo # Load the repository from the CatsVsDogs directory repo = Repo("CatsVsDogs") # Check the status of the repository print(repo.status()) [​](https://docs.oxen.ai/python-api#add-files) Add Files ----------------------------------------------------------- Now let’s create a README.md file and [add](https://docs.oxen.ai/python-api/repo#add) it to the local staging area. This will not commit the changes to the repository, but it will prepare them to be committed. # ... continue from previous example # Create a README.md file filename = os.path.join(repo.path, "README.md") with open(filename, "w") as f: f.write("# Cats vs. Dogs\n\nWhich is it? We will be using machine learning to find out!") # Add the README.md file to the staging area repo.add(filename) # Confirm that the file has been staged print(repo.status()) [​](https://docs.oxen.ai/python-api#commit-changes) Commit Changes --------------------------------------------------------------------- Now that we have added the README.md file to the staging area, we can commit the changes to the repository. # ... continue from previous example # Commit the changes to the repository repo.commit("Adding README.md") [​](https://docs.oxen.ai/python-api#diff-changes) Diff Changes ----------------------------------------------------------------- Oxen.ai has powerful diff tools built in that allow you to see the changes to files between commits, branches, and more. result = oxen.diff("README.md") print(result.get()) To learn more about diffs checkout the [diff](https://docs.oxen.ai/concepts/diffs) documentation or the [Python API Documentation](https://docs.oxen.ai/python-api/diff/diff) . [​](https://docs.oxen.ai/python-api#push-to-remote) Push To Remote --------------------------------------------------------------------- It’s one thing to version your data locally, but where the real power comes in is when you can share your data with others. Oxen repositories can be pushed to a remote repository hosted on [Oxen Hub](https://oxen.ai/) or your own [oxen-server](https://docs.oxen.ai/getting-started/oxen-server) . There are a few steps when pushing to a remote for the first time. 1. [Create Remote](https://docs.oxen.ai/python-api/remote_repo#create_repo) 2. [Point Local to Remote](https://docs.oxen.ai/python-api/repo#set_remote) 3. [Push Changes](https://docs.oxen.ai/python-api/repo#push) ### [​](https://docs.oxen.ai/python-api#create-remote) Create Remote Before you can push to a remote repository, you must create it. This can be done with the [create\_repo](https://docs.oxen.ai/python-api/remote_repo#create_repo) method. from oxen.remote_repo import create_repo # Create a remote repository remote_name = "MyNamespace/CatsVsDogs" remote_repo = create_repo(remote_name) ### [​](https://docs.oxen.ai/python-api#point-local-to-remote) Point Local to Remote Now that we have created the remote repository, we need to point our local repository to sync to it. This can be done with the [set\_remote](https://docs.oxen.ai/python-api/repo#set_remote) method. from oxen import Repo # Load the local repository repo = Repo("CatsVsDogs") # Point the local repository to the remote repo.set_remote("origin", remote_repo.url()) ### [​](https://docs.oxen.ai/python-api#push-changes) Push Changes Now that we have created the remote repository and pointed our local repository to it, we can [push](https://docs.oxen.ai/python-api/repo#push) our changes to the remote repository. # Push the changes to the remote repository repo.push() ### [​](https://docs.oxen.ai/python-api#full-push-example) Full Push Example The end to end workflow from scratch looks like this: from oxen import Repo from oxen.remote_repo import create_repo from oxen.auth import config_auth # 0. Load the local repository repo = Repo("CatsVsDogs") # 1. Configure Authentication config_auth("YOUR_AUTH_TOKEN") # 2. Create a remote repository remote_name = "MyNamespace/CatsVsDogs" repo = create_repo(remote_name) # 3. Point the local repository to the remote repo.set_remote("origin", repo.url) # 4. Push the changes to the remote repository repo.push() [​](https://docs.oxen.ai/python-api#pull-data) Pull Data ----------------------------------------------------------- Now that we have pushed our changes to the remote repository, we can [pull](https://docs.oxen.ai/python-api/repo#pull) them down to another machine. import oxen import os repo_path = "CatsVsDogs" if os.path.exists(repo_path): # if you already have a local copy of the repository, you can load it repo = oxen.Repo(repo_path) else: # if you don't have a local copy of the repository, you can clone it repo = oxen.clone("ox/CatsVsDogs") # Pull the latest changes from the remote repository repo.pull() [​](https://docs.oxen.ai/python-api#oxenfs-fsspec-integration) OxenFS (fsspec Integration) --------------------------------------------------------------------------------------------- OxenFS allows you to conveniently read and write files through a Pythonic file interface. import oxen fs = oxen.OxenFS("openai", "gsm8k") with fs.open("gsm8k_test.parquet") as f: content = f.read() It also integrates directly with third-party libraries like Pandas like this: df = pd.read_parquet("oxen://openai:gsm8k@main/gsm8k_test.parquet") See the full documentation for [OxenFS](https://docs.oxen.ai/python-api/oxen_fs) . [​](https://docs.oxen.ai/python-api#branching) Branching ----------------------------------------------------------- Branching is a powerful feature of Oxen that allows you to create a named version of your data without affecting the original version. This is useful when you want to experiment with your changes affecting the original version. ### [​](https://docs.oxen.ai/python-api#create-branch) Create Branch To create a new branch, use the [Repo.checkout](https://docs.oxen.ai/python-api/repo#checkout) method. from oxen import Repo repo = Repo("CatsVsDogs") repo.checkout("add-dogs", create=True) This both creates the branch and checks it out (the command line equivalent of `oxen checkout -b add-dogs`). ### [​](https://docs.oxen.ai/python-api#list-branches) List Branches To list all of the branches in a repository, use the [Repo.branches](https://docs.oxen.ai/python-api/repo#branches) method. from oxen import Repo repo = Repo("CatsVsDogs") print(repo.branches()) Output: [Branch(name=add-dogs, commit_id=3168391af834ac18), Branch(name=main, commit_id=3168391af834ac18)] As you can see there should be a `main` branch and a `add-dogs` branch, each tied to a commit id. The commit ids will be the same at this point, because the branches have not diverged in content. [​](https://docs.oxen.ai/python-api#module-reference) Module Reference ------------------------------------------------------------------------- Detailed documentation for each Python module. ### [​](https://docs.oxen.ai/python-api#clone) Clone [clone](https://docs.oxen.ai/python-api/clone) is used to download a repository to your local machine. ### [​](https://docs.oxen.ai/python-api#initialize-repository) Initialize Repository [init](https://docs.oxen.ai/python-api/init) is used to initialize a new local repository. ### [​](https://docs.oxen.ai/python-api#configure-user) Configure User [user](https://docs.oxen.ai/python-api/user) is used to configure the user for a local repository. ### [​](https://docs.oxen.ai/python-api#setup-auth) Setup Auth [auth](https://docs.oxen.ai/python-api/auth) is used to configure authentication for remote repositories. ### [​](https://docs.oxen.ai/python-api#repositories) Repositories The [Repositories](https://docs.oxen.ai/python-api/repositories) page has an overview of the two repository classes, and detailed documentation for each class can be found on their respective pages below. * [Repo](https://docs.oxen.ai/python-api/repo) is used to interact with data locally. * [RemoteRepo](https://docs.oxen.ai/python-api/remote_repo) is used to interact with a remote data without downloading all of it locally. ### [​](https://docs.oxen.ai/python-api#oxenfs) OxenFS [OxenFS](https://docs.oxen.ai/python-api/oxen_fs) is an [fsspec](https://filesystem-spec.readthedocs.io/en/latest/) backend that allows you to read and write files in your Oxen repo through a Pythonic file interface. It also provides a convenient integration point with third-party libraries. [πŸ”§ Debugging & Performance](https://docs.oxen.ai/getting-started/command-line/debugging) [Clone](https://docs.oxen.ai/python-api/clone) ⌘I Assistant Responses are generated using AI and may contain mistakes. --- # Parameter Guide - Oxen.ai > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.oxen.ai/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.oxen.ai/fine-tuning-api/parameters#content-area) [​](https://docs.oxen.ai/fine-tuning-api/parameters#overview) Overview ------------------------------------------------------------------------- This guide explains common training parameters across all fine-tuning operations. Use this reference to understand what each parameter does and how to adjust them for your use case. [​](https://docs.oxen.ai/fine-tuning-api/parameters#lora-low-rank-adaptation) LoRA (Low-Rank Adaptation) ----------------------------------------------------------------------------------------------------------- LoRA is a technique for efficient fine-tuning that drastically reduces memory requirements and training time. ### [​](https://docs.oxen.ai/fine-tuning-api/parameters#use_lora) `use_lora` **Type:** `boolean` **Default:** `true` **Applies to:** All models Whether to use LoRA for fine-tuning. Almost always recommended. * `true` - Use LoRA (faster, less memory, recommended) * `false` - Full fine-tuning (slower, more memory, rarely needed) { "training_params": { "use_lora": true } } ### [​](https://docs.oxen.ai/fine-tuning-api/parameters#lora_rank) `lora_rank` **Type:** `integer` **Default:** `16` **Range:** `1-128` (typical: `8-64`) **Applies to:** All models when `use_lora: true` The rank of LoRA matrices. Lower rank = faster training and less memory, but potentially less expressive. **When to adjust:** * **Reduce to 8** if you’re out of memory or want faster training * **Increase to 32-64** if you have a large, complex dataset and need more capacity { "training_params": { "use_lora": true, "lora_rank": 16 } } ### [​](https://docs.oxen.ai/fine-tuning-api/parameters#lora_alpha) `lora_alpha` **Type:** `integer` **Default:** `16` **Typical:** Same as `lora_rank` **Applies to:** All models when `use_lora: true` Scaling factor for LoRA updates. Typically set equal to `lora_rank`. **When to adjust:** * Keep equal to `lora_rank` in most cases * Increase to make LoRA updates stronger (rare) * Decrease to make updates more subtle (rare) { "training_params": { "use_lora": true, "lora_rank": 16, "lora_alpha": 16 } } [​](https://docs.oxen.ai/fine-tuning-api/parameters#learning-rate-and-optimization) Learning Rate and Optimization --------------------------------------------------------------------------------------------------------------------- ### [​](https://docs.oxen.ai/fine-tuning-api/parameters#learning_rate) `learning_rate` **Type:** `number` **Default:** `0.0001` (text), `0.0002` (image) **Typical range:** `0.00001-0.001` **Applies to:** All models The step size for parameter updates. Too high = unstable training, too low = slow convergence. **When to adjust:** * **Decrease by 10x** if training is unstable or loss is spiking * **Increase by 2-3x** if training is too slow or plateau early * **Text models**: Start with `0.0001` * **Image models**: Start with `0.0002` { "training_params": { "learning_rate": 0.0001 } } If you’re unsure, stick with the defaults. Learning rate is the most sensitive parameter. [​](https://docs.oxen.ai/fine-tuning-api/parameters#batch-size-and-memory) Batch Size and Memory --------------------------------------------------------------------------------------------------- ### [​](https://docs.oxen.ai/fine-tuning-api/parameters#batch_size) `batch_size` **Type:** `integer` **Default:** `1` **Typical range:** `1-8` **Applies to:** All models Number of samples processed together in one training step. **Trade-offs:** * **Larger batch size** = faster training, more stable, but more memory * **Smaller batch size** = slower training, less stable, but less memory **When to adjust:** * **Reduce to 1** if you get out-of-memory errors * **Increase to 2-4** if you have GPU memory to spare and want faster training { "training_params": { "batch_size": 1 } } ### [​](https://docs.oxen.ai/fine-tuning-api/parameters#gradient_accumulation-/-grad_accum) `gradient_accumulation` / `grad_accum` **Type:** `integer` **Default:** `1` **Typical range:** `1-16` **Applies to:** All models Accumulate gradients over multiple steps before updating parameters. This simulates a larger batch size without using more memory. **When to use:** * Set to 4-8 if you want the stability of larger batches but don’t have the memory * Effective batch size = `batch_size Γ— gradient_accumulation` { "training_params": { "batch_size": 1, "gradient_accumulation": 4 // Effective batch size = 4 } } [​](https://docs.oxen.ai/fine-tuning-api/parameters#training-duration) Training Duration ------------------------------------------------------------------------------------------- ### [​](https://docs.oxen.ai/fine-tuning-api/parameters#epochs-text-models) `epochs` (Text Models) **Type:** `integer` **Default:** `1` **Typical range:** `1-5` **Applies to:** Text generation models Number of complete passes through the training dataset. **Guidelines:** * **1 epoch** - Good starting point, often sufficient * **2-3 epochs** - For better learning on small datasets * **\>5 epochs** - Risk of overfitting { "training_params": { "epochs": 1 } } ### [​](https://docs.oxen.ai/fine-tuning-api/parameters#steps-image/video-models) `steps` (Image/Video Models) **Type:** `integer` **Default:** `2000` (image), `3000` (editing) **Typical range:** `1000-5000` **Applies to:** Image and video generation models Total number of training steps (optimizer updates). **Guidelines:** * **1000 steps** - Quick test runs * **2000-3000 steps** - Standard training * **4000-5000 steps** - Complex styles or large datasets { "training_params": { "steps": 2000 } } [​](https://docs.oxen.ai/fine-tuning-api/parameters#logging-and-checkpointing) Logging and Checkpointing ----------------------------------------------------------------------------------------------------------- ### [​](https://docs.oxen.ai/fine-tuning-api/parameters#logging_steps) `logging_steps` **Type:** `integer` **Default:** `10` **Applies to:** Text models How often to log training metrics (loss, learning rate, etc.). { "training_params": { "logging_steps": 10 } } ### [​](https://docs.oxen.ai/fine-tuning-api/parameters#save_steps_ratio) `save_steps_ratio` **Type:** `number` **Default:** `0.25` **Range:** `0.0-1.0` **Applies to:** Text models Save checkpoints at this fraction of total training. For example, `0.25` with 4 epochs saves after each epoch. { "training_params": { "save_steps_ratio": 0.25 } } ### [​](https://docs.oxen.ai/fine-tuning-api/parameters#save_strategy) `save_strategy` **Type:** `string` **Default:** `"epoch"` **Options:** `"epoch"`, `"steps"` **Applies to:** Text models When to save checkpoints: * `"epoch"` - Save at the end of each epoch * `"steps"` - Save based on `save_steps_ratio` { "training_params": { "save_strategy": "epoch" } } ### [​](https://docs.oxen.ai/fine-tuning-api/parameters#sample_every-image/video-models) `sample_every` (Image/Video Models) **Type:** `integer` **Default:** `200` **Applies to:** Image and video models Generate sample outputs every N steps to monitor progress visually. { "training_params": { "sample_every": 200 } } [​](https://docs.oxen.ai/fine-tuning-api/parameters#model-specific-parameters) Model-Specific Parameters ----------------------------------------------------------------------------------------------------------- ### [​](https://docs.oxen.ai/fine-tuning-api/parameters#text-generation) Text Generation #### [​](https://docs.oxen.ai/fine-tuning-api/parameters#seq_length) `seq_length` **Type:** `integer` **Default:** `1024` **Range:** `128-4096` Maximum sequence length for text. Longer = more context, but more memory. { "training_params": { "seq_length": 1024 } } #### [​](https://docs.oxen.ai/fine-tuning-api/parameters#neftune_noise_alpha) `neftune_noise_alpha` **Type:** `number` **Default:** `0` **Range:** `0-15` Add noise during training for better generalization (NEFTune). Set to 5-15 to enable. { "training_params": { "neftune_noise_alpha": 0 } } ### [​](https://docs.oxen.ai/fine-tuning-api/parameters#image-generation/editing) Image Generation/Editing #### [​](https://docs.oxen.ai/fine-tuning-api/parameters#timestep_type) `timestep_type` **Type:** `string` **Default:** `"sigmoid"` (generation), `"weighted"` (editing) **Options:** `"weighted"`, `"sigmoid"`, `"linear"` How to sample timesteps during diffusion training. * `"sigmoid"` - Focus on mid-range timesteps (balanced) * `"weighted"` - Focus on difficult timesteps * `"linear"` - Uniform sampling (simple) { "training_params": { "timestep_type": "sigmoid" } } #### [​](https://docs.oxen.ai/fine-tuning-api/parameters#sample_width-/-sample_height) `sample_width` / `sample_height` **Type:** `integer` **Default:** `1024` **Applies to:** Image editing Resolution for sample generation during training. { "training_params": { "sample_width": 1024, "sample_height": 1024 } } #### [​](https://docs.oxen.ai/fine-tuning-api/parameters#cache_text_embeddings) `cache_text_embeddings` **Type:** `boolean` **Default:** `false` **Applies to:** Image models Pre-compute and cache text embeddings for faster training. { "training_params": { "cache_text_embeddings": false } } [​](https://docs.oxen.ai/fine-tuning-api/parameters#quick-reference-tables) Quick Reference Tables ----------------------------------------------------------------------------------------------------- ### [​](https://docs.oxen.ai/fine-tuning-api/parameters#common-parameter-sets) Common Parameter Sets **Fast Iteration (Test Runs):** { "batch_size": 1, "learning_rate": 0.0001, "epochs": 1, // or steps: 1000 "lora_rank": 8 } **Standard Training:** { "batch_size": 1, "learning_rate": 0.0001, "epochs": 2, // or steps: 2000 "lora_rank": 16 } **High Quality (Large Dataset):** { "batch_size": 2, "learning_rate": 0.0001, "gradient_accumulation": 4, "epochs": 3, // or steps: 4000 "lora_rank": 32 } [​](https://docs.oxen.ai/fine-tuning-api/parameters#troubleshooting) Troubleshooting --------------------------------------------------------------------------------------- Out of memory errors 1. Reduce `batch_size` to 1 2. Reduce `lora_rank` to 8 3. Reduce `seq_length` (text) or `sample_width`/`sample_height` (image) 4. Enable `cache_text_embeddings` (image models) Training loss not decreasing 1. Increase `learning_rate` by 2-3x 2. Check your data quality and column mappings 3. Increase training duration (`epochs` or `steps`) Loss spiking or unstable 1. Decrease `learning_rate` by 10x 2. Increase `gradient_accumulation` to smooth updates 3. Reduce `batch_size` to 1 Results not matching my style 1. Increase training duration (more `epochs` or `steps`) 2. Increase `lora_rank` to 32 or 64 3. Ensure your captions clearly describe the unique aspects 4. Add more training data [​](https://docs.oxen.ai/fine-tuning-api/parameters#next-steps) Next Steps ----------------------------------------------------------------------------- * [Quick Start Guides](https://docs.oxen.ai/fine-tuning-api/overview#quick-start-guides) - Apply these parameters * [API Reference](https://docs.oxen.ai/fine-tuning-api/overview#detailed-api-reference) - Complete parameter lists * [Examples](https://docs.oxen.ai/getting-started/fine-tuning) - See parameters in action [Fine-Tune: Text To Video](https://docs.oxen.ai/fine-tuning-api/reference/text_to_video) [Create chat completion](https://docs.oxen.ai/fine-tuning-api/create-chat-completion) ⌘I Assistant Responses are generated using AI and may contain mistakes. ---