# Introduction w\.ai - The Global AI Supercomputer ### Introducing w\.ai w\.ai is building the **Global AI Supercomputer** – a worldwide network that uses the spare power from everyday devices (PCs, laptops, phones) to create a massive, shared resource for Artificial Intelligence. ### Why does the world need w\.ai? Artificial Superintelligence (ASI) is coming, and it will have the power to reshape our world. Right now, the development of this incredible technology is mostly happening in a few big, closed-off labs. This is risky. If only a handful of people control AI this powerful, it might not be used for everyone's benefit. We believe humanity needs a different path – an open path. ### What is w\.ai's solution? Instead of relying on a few giant datacenters, w\.ai creates a **peer-to-peer network** that connects billions of existing devices. Think about it: your computer, and millions like it, have a lot of power that sits unused most of the time. w\.ai provides a simple application that lets you easily and safely contribute this idle power. This collective power, once unified, creates a planetary-scale supercomputer. This "Global AI Supercomputer" becomes the open foundation needed to build **Decentralized Superintelligence (DSI)** – AI that is transparent, globally accessible, and ultimately co-owned by its contributors, ensuring it serves humanity's collective potential. ### What does this mean for you? By running w\.ai, you're not just contributing spare processing power; you're: 1. Helping to power real-world AI applications today as we build and prove the network. 2. Actively participating in building the essential infrastructure for a safer, more open AI future. 3. Becoming a **co-owner** of this critical global resource and the intelligence it enables. w\.ai is our answer to ensuring that the immense power of future AI serves all of humanity, not just a select few. We are moving intelligence from hidden silos into a shared, open mesh. Stay up to date with the project on [X](https://x.com/wai_protocol) and [Discord](https://discord.gg/w-ai). # Quick Start ### **Desktop App** **macOS, Windows, Linux** The quickest way to start contributing is through our official desktop client: 1. [Download](https://download.w.ai) the latest w\.ai client. 2. Launch the application and follow the onboarding steps. 3. Begin contributing immediately once setup is complete. ### **CLI** **Linux (Ubuntu 24.04)** To get started with the CLI, run our installer shell script: ```bash curl -fsSL https://app.w.ai/install.sh | bash ``` **Windows (Powershell)** ```powershell iwr -useb https://app.w.ai/install.ps1 | iex ``` **macOS (Terminal)** ```bash curl -fsSL https://app.w.ai/install.sh | bash ``` After that, you can run ```bash wai help ``` To get an overview of the commands. Review [w.ai CLI Guide](/w.ai-cli-guide) for more details. You can view and generate auth keys (for the CLI) or developer keys (for our OpenAI compatible endpoints) from ### Docker **Linux with Docker/Podman** For containerized environments, we provide optimized Docker images: ```bash docker pull wdotai/wai:latest # Example with CUDA docker run --gpus all \ -v ~/.wombo:/root/.wombo \ -e W_AI_API_KEY=your_key_here \ wdotai/wai:latest run ``` See [w.ai CLI Guide](/w.ai-cli-guide#docker) for detailed instructions # FAQ ### What is w\.ai? w\.ai a simple application that lets you contribute your device's extra computing power to a global network. In the background, you’re helping run AI applications and do cutting edge AI research, earning rewards for your contribution. w\.ai is a collaborative effort involving the team behind the popular WOMBO apps (200M+ Downloads & backed by NVIDIA), using their expertise to help build a more open and accessible AI future. ### Is it safe? Is my data and privacy protected? Yes, w\.ai is built with security and privacy as top priorities. The application only utilizes your device's extra processing power for approved AI tasks and does not access your personal files or private data. All communication with our servers is encrypted. w\.ai records basic device information and IP address for security and fraud prevention, similar to any other app you may download. ### How do I earn rewards? Your contributions to the w\.ai network are tracked through w Points, which are shown in your dashboard. Points are awarded based on the computing power you contribute to AI tasks. The more you contribute, the more w Points you'll receive. You can also earn bonus w Points by inviting friends through our referral program! ### What are w Points & how much are they worth? w Points track your participation and will determine the tokens/rewards you receive when they're distributed. Think of them as points that reflect your participation in building this open AI infrastructure. While w Points don't have a direct cash value right now, they will be a factor in determining future rewards as the w\.ai ecosystem and network mature. ### Is w\.ai stable? w\.ai is currently live in beta and rapidly evolving. You may encounter occasional bugs or experience downtime during this phase. Our team closely monitors the network’s health and actively updates our Discord community whenever issues arise. We appreciate your patience and feedback as we evolve. ### Can I use multiple devices? Yes. You can run the w\.ai client on multiple devices using a single account. Your contributions across devices will accumulate collectively into your total w Points balance. ### Where can I see device & total points for my account? View your points by device and total points here: # Introduction **Introduction to w\.ai Compute Rentals** w\.ai offers an innovative solution for accessing rental Jupyter Notebook and SSH containerized environments, allowing users to leverage powerful AI and machine learning frameworks using w\.ai points. With options like Apple's MLX for Python and NVIDIA's Torch with CUDA for transformers and other advanced computations, these environments provide flexible compute capabilities. Workers on the network can seamlessly make their resources available for rent around the globe, earning w\.ai points upon successful rental completions. This approach enables distributed compute resources to drive AI research and development, optimizing both resource utilization and user engagement.
* [Rent Compute](https://app.w.ai/compute) * [Contribute as a w.ai worker](https://download.w.ai) * [w.ai Compute Rental Service Terms](https://app.w.ai/compute/terms) * [Learn about Jupyter Notebooks](https://docs.jupyter.org/en/latest) * [Learn about SSH](https://docs.w.ai/compute-rentals/ssh) \
# How it works ## Renting Compute on w\.ai Renting compute on w\.ai provides a dedicated Jupyter Notebook or SSH environment backed by real GPU hardware from our distributed compute network. You gain full access to a sandboxed container, choosing between CUDA for NVIDIA GPUs, ROCm for AMD GPUs, or MLX for Apple Silicon, billed by the minute using w\.ai points. *** ### Step-by-Step Guide #### Browse Available GPUs Visit the **Compute** page at to see live GPU inventory. Each card displays: * **GPU Model** — e.g., NVIDIA RTX 5090, Apple M4 Pro * **VRAM** — Total GPU memory available * **Backend** — CUDA, ROCm, Metal, or Vulkan * **Price** — Cost in w\.ai points per hour * **Availability** — Number of workers offering this hardware Use the search bar and category filters (NVIDIA, Apple, AMD, Intel) to find the right GPU for your workload. #### Select Duration & Rent Choose your rental duration from available options: | Duration | Use Case | | ------------ | ----------------------------------- | | 5–30 minutes | Quick experiments, testing code | | 1 hour | Standard development sessions | | 2 hours | Training runs, larger experiments | | 4–12 hours | Extended compute jobs | | 24 hours | Long-running training or processing | The UI shows your **total cost** before confirmation. Ensure you have sufficient w\.ai points to cover the duration. Click **Rent** to confirm. #### Wait for Provisioning Upon confirmation, your rental enters a **Pending** state as: 1. The network matches a worker with your requested hardware. 2. The worker provisions an isolated container environment. 3. The Jupyter Notebook and SSH server starts and becomes accessible, typically taking under \~1 minute. #### Access Your Jupyter Notebook or SSH terminal Once active, your rental card shows: * **Session URL** — Your unique Jupyter Notebook endpoint * **Access Token** — Authentication token * **Time Remaining** — Live countdown For SSH, you will see your SSH credentials (username, host, etc.) Click **Details** on My Rentals for full access credentials, then **Open Jupyter Notebook** or Open Web Terminal to launch your environment in a new tab. *** ### Your Environment Each rental provides a fully configured Jupyter Notebook or SSH environment with Python 3.11, pip, and a comprehensive set of pre-installed packages. > **Note:** The environment is ephemeral. All files are deleted when the session ends. Download any results before your rental expires. #### Pre-Installed Python Packages **Linux / Windows (CUDA & ROCm)** | Category | Packages | | ---------------------- | ---------------------------------------------------------------------------- | | **Notebooks** | JupyterLab, ipywidgets, tqdm | | **Data Science** | NumPy, Pandas, SciPy, scikit-learn | | **Visualization** | Matplotlib, Seaborn, Pillow | | **ML / Deep Learning** | PyTorch (CUDA/ROCm/CPU), TorchVision, TorchAudio, MLX-CUDA, Unsloth | | **Hugging Face** | Transformers, Datasets, Hugging Face Hub, Accelerate, Diffusers, Safetensors | **macOS (Apple Silicon)** | Category | Packages | | ---------------------- | ------------------------------------------------- | | **Notebooks** | JupyterLab, ipywidgets | | **Data Science** | NumPy, Pandas, SciPy, scikit-learn | | **Visualization** | Matplotlib | | **ML / Deep Learning** | PyTorch (MPS), TorchVision | | **Hugging Face** | Transformers, Diffusers, Accelerate, Safetensors | | **Apple MLX** | MLX, mlx-lm, mlx-vlm, mlx-audio, mlx-video, MFlux | #### Base Container Images Each environment is built on a minimal, production-grade base image depending on the backend: | Backend | Base Image | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **CUDA (NVIDIA)** | [nvidia/cuda:12.1.1-devel-ubuntu22.04](https://hub.docker.com/layers/nvidia/cuda/12.1.1-devel-ubuntu22.04/images/sha256-327c9e046fbf662275be0934742f7e5412f9b24402ee90bf4d649c1a21707912) | | **ROCm (AMD)** | [rocm/dev-ubuntu-22.04:7.1.1](https://hub.docker.com/layers/rocm/dev-ubuntu-22.04/7.1.1/images/sha256-2d390c574e5e7e49e40e3bb376a88608c750d3f6c64b29d6adbc5834bee6c9be) | | **Vulkan** | [ubuntu:22.04](https://hub.docker.com/layers/library/ubuntu/22.04/images/sha256-965fbcae990b0467ed5657caceaec165018ef44a4d2d46c7cdea80a9dff0d1ea?context=explore) | All images also include: `curl`, `git`, `ca-certificates`, `glib`, **Python 3.11.14**, and **uv** (fast Python package installer). > **Need an additional system package?** [Contact us](https://w.ai/support) to request additions to the base image. *** ### Managing Your Rentals Visit **My Rentals** in the sidebar to manage all sessions. #### Extending a Session Need more time? Click **Extend** to add minutes or hours. Extensions charge the same per-minute rate and require a sufficient point balance. #### Stopping Early Click **Stop Rental** to end a session early. Billing is **pro-rated by the minute** — you are charged only for the minutes used and remaining reserved points are refunded. *** ### Pricing Rental pricing depends on: * **GPU Performance** — Higher-tier GPUs cost more points per hour * **VRAM** — More memory increases the base price * **Network Earnings** — Prices reflect actual GPU earning rates on the network A minimum charge of **1 point per minute** applies to all sessions. Pro-rated billing refunds unused reserved points if a session ends early. Prices are displayed on each GPU card in the Compute marketplace. *** ### Networking Restrictions For security, outbound network access from rental environments is restricted to an allowlist of trusted domains required for ML development: | Category | Domain | | ------------------------------ | ------------------------------ | | **Package Registries** | `pypi.org` | | | `files.pythonhosted.org` | | **ML / Dataset Platforms** | `huggingface.co` | | | `hf.co` | | | `kaggle.com` | | | `openml.org` | | | `archive.ics.uci.edu` | | **ML Frameworks** | `download.pytorch.org` | | | `tensorflow.org` | | **Research Data Repositories** | `zenodo.org` | | | `figshare.com` | | | `osf.io` | | | `dataverse.harvard.edu` | | | `datadryad.org` | | | `archive.org` | | **Source Code Hosting** | `github.com` | | | `githubusercontent.com` | | | `gitlab.com` | | | `bitbucket.org` | | | `sourceforge.net` | | **Cloud / CDN Storage** | `dl.fbaipublicfiles.com` | | | `storage.googleapis.com` | | | `storage.cloud.google.com` | | | `s3.amazonaws.com` | | | `blob.core.windows.net` | | | `cloudfront.net` | | | `r2.cloudflarestorage.com` | | | `download.microsoft.com` | | **File Sharing Services** | `drive.google.com` | | | `drive.usercontent.google.com` | | | `dropbox.com` | | | `dl.dropboxusercontent.com` | | **Government / Research Labs** | `nersc.gov` | | | `nasa.gov` | | | `cern.ch` | | | `noaa.gov` | | | `nist.gov` | | **Web-Scale Datasets** | `commoncrawl.org` | | | `dumps.wikimedia.org` | | **Computer Vision Datasets** | `image-net.org` | | | `cocodataset.org` | | | `cs.toronto.edu` | | **Biomedical Data** | `ncbi.nlm.nih.gov` | | | `ebi.ac.uk` | | | `physionet.org` | | **Speech / Audio Data** | `openslr.org` | **All other outbound network traffic is strictly blocked.** This includes general web browsing, SSH connections, and access to arbitrary external services. > **Need access to an additional domain?** Contact us on Discord to request additions to the network allowlist. *** ### Security w\.ai compute sessions are designed with defense-in-depth isolation to protect both renters and workers. #### Linux / Windows * All Linux capabilities dropped — containers run with the minimal possible privilege set * **Non-root user** — system package installation is disabled inside the container * **Network isolation** — outbound traffic restricted to the allowlist above; all other traffic denied * **Resource limits** — CPU, memory, and ulimits are enforced to prevent resource abuse * Container filesystem is ephemeral and fully destroyed on session termination #### macOS (Apple Silicon) * **Network isolation** — very limited networking restricted to the allowlist above * **Locked-down sandbox** — all system access is blocked outside the sandbox directory * **Restricted shell** — only a very limited set of shell commands are enabled; all others are blocked * **Minimal kernel access** — only essential kernel services are available to the sandbox environment *** ### Worker Requirements To contribute your machine as a compute rental worker, you must meet these minimum requirements: #### All Platforms * **20 GB available storage** — required for container images, models, and session data #### Linux * System packages: `uidmap`, `iptables` * NVIDIA GPUs additionally require: `nvidia-container-toolkit` #### Windows * NVIDIA GPU required * WSL (Windows Subsystem for Linux) must be installed * The w\.ai worker will attempt to install WSL automatically if missing — a system reboot is required to complete setup #### macOS * Apple Silicon (M1 or later) required * No additional system packages needed #### Running the Worker Start the worker in the foreground: ```bash wai run w.ai ``` Or run in the background (detached mode): ```bash wai run w.ai -d ``` Manage background workers with: ```bash wai list # List running instances wai logs -f # Follow live logs wai stop # Stop a worker (or "wai stop all") wai restart # Restart a worker ``` Workers earn **w\.ai points** for every minute a rental session is active on their hardware. # Jupyter Notebooks ### What is a Jupyter Notebook? A Jupyter Notebook is an open-source web application for creating and sharing documents containing: * Live code * Equations * Visualizations * Narrative text It is a standard tool for data science, machine learning, and AI research. *** ### Getting Started with Your Notebook When you open your rented Jupyter environment, you'll see the Jupyter file browser. From here, you can: * **Create a new notebook:** * Click `New → Python 3 Kernel` to start a fresh notebook. * **Upload files:** * Use the `Upload` button to bring in datasets or existing notebooks. *** ### Using GPU in Your Notebook #### NVIDIA CUDA Environment Your CUDA environment comes with PyTorch pre-installed. * **Verify GPU access:** ```python import torch print(f"CUDA available: {torch.cuda.is_available()}") print(f"GPU: {torch.cuda.get_device_name(0)}") print(f"VRAM: {torch.cuda.get_device_properties(0).total_mem / 1e9:.1f} GB") ``` * **Load and run a model on GPU:** ```python from transformers import AutoModelForCausalLM, AutoTokenizer model_name = "meta-llama/Llama-3.2-1B" tokenizer = AutoTokenizer.from_pretrained(model_name) model = AutoModelForCausalLM.from_pretrained( model_name, torch_dtype=torch.float16, device_map="auto" ) inputs = tokenizer("Hello, world!", return_tensors="pt").to("cuda") outputs = model.generate(**inputs, max_new_tokens=50) print(tokenizer.decode(outputs[0])) ``` *** #### Apple MLX Environment Your MLX environment comes with Apple's ML framework pre-installed. * **Check the MLX backend:** ```python import mlx.core as mx print(f"MLX backend: {mx.default_device()}") ``` * **Create arrays on the GPU:** ```python a = mx.random.normal((1000, 1000)) b = mx.random.normal((1000, 1000)) c = a @ b # Matrix multiplication on Metal GPU mx.eval(c) print(f"Result shape: {c.shape}") ``` * **Run language models with mlx-lm:** ```python from mlx_lm import load, generate model, tokenizer = load("mlx-community/Llama-3.2-1B-Instruct-4bit") response = generate( model, tokenizer, prompt="Explain quantum computing in simple terms:", max_tokens=200 ) print(response) ``` *** ### Installing Additional Packages * Use pip directly in a notebook cell, e.g. ```python !pip install datasets scikit-learn matplotlib seaborn ``` Remember: Installed packages are ephemeral and do not persist after your session ends. Include your pip install commands at the top of your notebook for future sessions. Learn more about Jupyter Notebooks at the official docs: ### Tips for Productive Sessions * Save your work frequently. Download notebooks and outputs before your session expires. * Monitor VRAM usage. Use `!nvidia-smi` (CUDA) or check memory in your code to avoid out-of-memory errors. * Use efficient data types. Load models in `float16` or `int4` to maximize VRAM usage. * Plan for ephemeral storage. Upload datasets at the start of each session and download results before ending. * Extend if needed. If your training job requires more time, extend your rental before it expires to avoid interruptions. ### Common Workflows | Workflow | Recommended GPU | Duration | | ---------------------------- | -------------------------------------- | --------------- | | Prototyping & Testing | Any available GPU | 30 min – 1 hour | | Fine-tuning small models | RTX 4070+ (12+ GB VRAM) | 2 – 4 hours | | Fine-tuning large models | RTX 4090 / Multi-GPU (24+ GB VRAM) | 4 – 8 hours | | Inference & Evaluation | Any GPU matching model requirements | 30 min – 1 hour | | Data Processing | Any GPU with sufficient VRAM | 1 – 2 hours | | MLX Fine-tuning or Inference | Apple M-series (16+ GB unified memory) | 1 – 2 hours | # SSH SSH access is available for compute rentals. This feature supports all backends (CUDA, Metal, ROCM, and Vulkan), providing direct SSH connectivity to GPU machines. **Activating SSH Access** 1. **Select SSH Options:** * Upon initiating your rental, choose the SSH tab. 2. **Receive Login Details:** * Post provisioning, the following details are available: * **SSH Host**: Address to connect. * **Username & Private Key**: Credentials for access. (Download this key as it will not be shown again after the initial display of it). 3. **Connecting via SSH:** * Use the provided host address and credentials to establish the SSH connection.\ You can also use it in the Web Terminal by clicking the button "Open in Web Terminal" **Key Features** * **Direct Machine Access**: Provides real-time command line access. * **Secure Tunnel**: SSH sessions are secure and encrypted. * **Operational Flexibility**: Allows operational adjustments and in-depth system control. #### Note Ensure SSH access adheres to the network restrictions and use cases permitted by the w\.ai environment. # Vision ### Liberating Intelligence from Centralized Control At w\.ai, we’re creating a decentralized future where artificial general intelligence (AGI) belongs to everyone—not centralized gatekeepers. Imagine hundreds of millions of idle devices—consumer laptops, gaming PCs, and smartphones—awakened and united into a single decentralized AI supercomputer. This global network, owned and operated by its contributors, will democratize access to intelligence, preventing centralized entities from monopolizing humanity’s most transformative technology.
Our mission is clear: liberate intelligence, make superintelligence universally accessible, and empower creators, researchers, and builders worldwide to freely innovate, collaborate, and thrive outside the constraints of proprietary control. # Supported Hardware **Compatible Hardware**: 1. **Any M-Series (Apple Silicon) chip** 1. eg. Macbook/Mac Mini M1, M2, M3, M4, M5, etc. 2. **NVIDIA GPUs**: Compute capability of 5.0+ 1. *e.g. GTX 1050, RTX 2060, RTX 3070, RTX 4080, RTX 5080, etc.* **Experimental Hardware**: 1. **AMD GPUs** 1. If your AMD GPU supports the latest version of Vulkan and has video output and the latest AMD drivers, it should work, AMD support is experimental. 2. To download the latest AMD drivers and test compatibility, [visit this link](https://www.amd.com/en/support/download/drivers.html). *Compatible devices are constantly updated. If your device is not supported, keep an eye out for updates and be the first to find out when your device is compatible.* # w\.ai CLI Guide To get started with the CLI, install it as mentioned in [Quick Start](/get-started/quick-start) ## On a desktop environment If on a device with a desktop environment/a browser, start by logging in: ```bash wai login ``` And then run using ```bash wai run ``` ## On a headless environment 1. Visit the [w.ai dashboard](https://app.w.ai/dashboard). 2. Login or create a w\.ai account. 3. Select `Auth API Keys` and create a new key. You now have a key that you can set on the headless environment using ```bash export W_AI_API_KEY=your key here ``` And then run normally (in the headless environment) as follows: ```bash wai run ``` ### Headless environment key management You can list generated API keys using ```bash wai key list ``` And revoke any using ```bash wai revoke ``` For more info, run ```bash wai key help ``` ## Specifying GPUs (NVIDIA only) If you want to run with a subset of your GPUs, add a `-g` flag to the run command followed by a list of the GPU IDs. For example, to run on GPUs 0 and 1, the command would be: ```bash wai run -g 0 1 ``` If no GPU is provided, it will be ran on GPU 0 ### Docker For Docker/Podman linux containers, we provide [optimized CLI images](https://hub.docker.com/r/wdotai/wai/tags): **NVIDIA GPUs with CUDA (Recommended)** For optimal performance on NVIDIA GPUs: ```bash docker run --gpus all \ -v ~/.wombo:/root/.wombo \ -e W_AI_API_KEY=your_key_here \ wdotai/wai:latest run ``` NVIDIA drivers must be installed on the host machine to use CUDA. w\.ai will fallback to Vulkan otherwise. See [nvidia-container-toolkit](https://github.com/NVIDIA/nvidia-container-toolkit?tab=readme-ov-file#getting-started) for more info. **AMD GPUs with Vulkan** For AMD GPUs: ```bash docker run --device=/dev/dri:/dev/dri \ -v ~/.wombo:/root/.wombo \ -e W_AI_API_KEY=your_key_here \ wdotai/wai:latest run ``` #### **Using environment files** Instead of passing the API key inline, you can use an environment file for better security: 1. Create a `.env` file:
```bash echo "W_AI_API_KEY=your_key_here" > .env ``` And specify the `.env` file in the docker command ```bash docker run \ -v ~/.wombo:/root/.wombo \ --env-file .env \ wdotai/wai:latest run ``` #### MacOS M-Series MacOS computers do not support GPU passthrough in containers. As such w\.ai on MacOS is unsupported through containers and must run on the root machine. #### Volume mounts Volume mounting \`\~/.wombo:/root/.wombo\` is highly recommended to avoid redownloading dependencies/models each time the container is restarted. # Support Our goal is to make your experience with w\.ai as smooth as possible. If you’re just getting started, please follow these steps to minimize common issues: 1. Ensure your device meets system requirements. View the [supported hardware](/w.ai-guide/supported-hardware) page for more information. 2. Verify your internet connection is stable. 3. Confirm you have the latest version of w\.ai installed. Download the most recent build [here](https://download.w.ai). If your device meets the requirements above, please let us know your issue by dropping a message in the [#beta-testing](https://discord.com/channels/1264970635919097999/1378169115650297866) channel in our [Discord](https://discord.gg/w-ai) server, or send us an email at `support@w.ai`. If you are encountering issues within the app, please select the 'Report a Bug' option in the bottom right.\ \ If you are encountering issues within the CLI, please use the `wai report ` command to then submit us a report.
# VPN Compatibility Some users access our app while connected to a VPN. While most VPNs work fine, a few may block or interfere with important connections our app needs to function properly. Here’s what we’ve found to work best. ### ✅ VPNs That **Are Known to Work** These VPNs have been community tested and consistently work with our app: * **ExpressVPN** *** ### ⚠️ VPNs That **May Work** These VPNs can work, but may require specific configuration: * **V2RayN** * **Clash VPN** * **Other VPNs with a “TUN mode”** – enabling TUN mode tends to improve compatibility *** > 💡 **Pro Tip:** If your VPN has a **“TUN mode”** option, turning it on usually makes it more compatible with our app — even on VPNs that already work well. *** ### 👋 Final Note If you use a VPN not listed here and it works, you can contact us by: * Dropping a message in the **#beta-testing** channel on our [Discord](https://discord.gg/w-ai) server * Sending us an email at `support@w.ai` # API Features ## API Features Our decentralized network delivers affordable, on-demand AI inference compute through simple **OpenAI-compatible HTTP APIs**. > *\[NOTE] The keys shown in examples are dummy placeholders (`wsk-examplekey`). To obtain production keys use* [*https://app.w.ai/developers/keys*](https://app.w.ai/developers/keys) *** ### Base API URL ``` https://api.w.ai/v1 ``` *** ### Authorization Include your API key in the `Authorization` header: ``` Authorization: Bearer wsk-examplekey ``` *** ### List Available Models Retrieve metadata for all available models on the network. ```bash curl -X GET 'https://api.w.ai/v1/models' ``` **Response includes:** * Model ID, name, and description * Input/output modalities (`text`, `image`, `video`) * Context length (for LLMs) * Quantization level (`4bit`, `8bit`, `fp16`) * Supported sampling parameters *** ### Text Chat Completions Create text-based chat completions using LLM models like Llama, Mistral, Gemma, DeepSeek, and more. #### Endpoint ``` POST /v1/chat/completions ``` #### Basic Example ```bash curl -X POST 'https://api.w.ai/v1/chat/completions' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer wsk-examplekey' \ --data '{ "model": "llama-3.2-1b-4bit", "messages": [ { "role": "user", "content": "Hello! Who is davinci?" } ], "max_tokens": 150, "stream": false }' ``` #### Request Parameters | Parameter | Type | Required | Description | | ------------------- | ------------- | -------- | ---------------------------------------------------------------------- | | `model` | string | ✅ | Model ID (e.g., `llama-3.2-1b-4bit`) | | `messages` | array | ✅ | Array of message objects | | `max_tokens` | integer | | Maximum tokens to generate (min: 1) | | `temperature` | number | | Sampling temperature (0-2, default: 1.0) | | `top_p` | number | | Nucleus sampling (0-1) | | `frequency_penalty` | number | | Frequency penalty (-2 to 2) | | `presence_penalty` | number | | Presence penalty (-2 to 2) | | `stream` | boolean | | Enable streaming responses | | `response_format` | object | | Output format (e.g., `{"type": "json_object"}`) | | `tools` | array | | Function definitions for tool calling | | `tool_choice` | string/object | | Tool selection mode (`none`, `auto`, `required`, or specific function) | #### Message Roles * `system` — System instructions * `user` — User messages * `assistant` — Assistant responses * `tool` — Tool/function call results *** ### Vision-Language Chat (VLM) Send images along with text prompts for multimodal understanding. #### Example with Image URL ```bash curl -X POST 'https://api.w.ai/v1/chat/completions' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer wsk-examplekey' \ --data '{ "model": "gemma-3-27b-4bit", "messages": [ { "role": "user", "content": [ { "type": "image_url", "image_url": { "url": "http://images.cocodataset.org/val2017/000000039769.jpg" } }, { "type": "text", "text": "Describe the contents of this image." } ] } ], "max_tokens": 150, "stream": false }' ``` #### Image Content Object | Field | Type | Description | | ------------------ | ------ | ----------------------------------------------- | | `type` | string | Must be `image_url` | | `image_url.url` | string | URL or base64-encoded image | | `image_url.detail` | string | Resolution: `low`, `high`, or `auto` (optional) | *** ### Tool Calling (Function Calling) Enable models to call external functions/tools. #### Example with Tools ```bash curl -X POST 'https://api.w.ai/v1/chat/completions' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer wsk-examplekey' \ --data '{ "model": "llama-3.3-70b-4bit", "messages": [ { "role": "user", "content": "What is the weather like in San Francisco?" } ], "tools": [ { "type": "function", "function": { "name": "get_weather", "description": "Get current weather for a location", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "City name" }, "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] } }, "required": ["location"] } } } ], "tool_choice": "auto" }' ``` #### Tool Choice Options | Value | Description | | --------------------------------------------------- | -------------------------------- | | `none` | Disable tool calling | | `auto` | Model decides when to call tools | | `required` | Force the model to call a tool | | `{"type": "function", "function": {"name": "..."}}` | Call a specific function | #### Handling Tool Call Responses When the model calls a tool, respond with the result: ```json { "model": "llama-3.3-70b-4bit", "messages": [ { "role": "user", "content": "What is the weather like in San Francisco?" }, { "role": "assistant", "content": null, "tool_calls": [ { "id": "call_abc123", "type": "function", "function": { "name": "get_weather", "arguments": "{\"location\": \"San Francisco\"}" } } ] }, { "role": "tool", "tool_call_id": "call_abc123", "content": "{\"temperature\": 68, \"condition\": \"sunny\"}" } ] } ``` *** ### Image Generation Generate images from text prompts using models like FLUX and SDXL. #### Endpoint ``` POST /v1/images/generations ``` #### Example ```bash curl -X POST 'https://api.w.ai/v1/images/generations' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer wsk-examplekey' \ --data '{ "model": "flux-1-dev", "prompt": "A green photorealistic hand in the matrix holding a sign that says W.ai, everything should be binary 1s and 0s", "size": "1024x1024" }' ``` #### Request Parameters | Parameter | Type | Required | Default | Description | | ----------------- | ------- | -------- | ------------- | ------------------------------------------------ | | `model` | string | ✅ | | Model ID (e.g., `flux-1-dev`, `sdxl`) | | `prompt` | string | ✅ | | Text description of the image | | `size` | string | | `1024x1024` | Output dimensions (e.g., `512x512`, `1024x1024`) | | `quality` | string | | | Quality level: `low`, `medium`, `high`, `hd` | | `seed` | integer | | Random | Seed for reproducible generation | | `steps` | integer | | Model default | Denoising steps (1-100) | | `guidance_scale` | number | | Model default | Prompt adherence (1-20) | | `negative_prompt` | string | | | What to exclude from the image | | `stream` | boolean | | `false` | Enable streaming for progress updates | *** ### Image Editing Edit existing images using text prompts with FLUX Kontext models. #### Endpoint ``` POST /v1/images/edits ``` #### Example ```bash curl -X POST 'https://api.w.ai/v1/images/edits' \ --header 'Authorization: Bearer wsk-examplekey' \ --header 'Content-Type: multipart/form-data' \ --form 'model=flux-1-kontext-dev' \ --form 'prompt=Convert to pencil sketch with natural graphite lines, cross-hatching, and visible paper texture' \ --form 'image=@/path/to/your/image.jpg' \ --form 'guidance_scale=2.5' ``` #### Request Parameters (multipart/form-data) | Parameter | Type | Required | Default | Description | | ----------------- | ------- | -------- | ------------- | ------------------------------------------------ | | `model` | string | ✅ | | Model ID (e.g., `flux-1-kontext-dev`) | | `prompt` | string | ✅ | | Edit instructions | | `image` | file | ✅ | | Source image file(s). Multiple images supported. | | `size` | string | | `1024x1024` | Output dimensions | | `negative_prompt` | string | | | What to avoid in the edit | | `seed` | integer | | Random | Seed for reproducible results | | `steps` | integer | | Model default | Denoising steps | | `guidance_scale` | number | | | Prompt adherence strength | | `quality` | string | | | Quality level | | `stream` | boolean | | `false` | Enable streaming | *** ### Object Detection & Segmentation Run object detection (YOLO11n) or image/video segmentation (SAM2) on images and videos. #### Endpoint ``` POST /v1/predictions ``` #### YOLO11n Object Detection Example Detect objects in an image with bounding boxes and class labels: ```bash curl -X POST 'https://api.w.ai/v1/predictions' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer wsk-examplekey' \ --data '{ "model": "yolo11n", "input": { "image": "https://images.cocodataset.org/val2017/000000039769.jpg", "conf": 0.25, "iou": 0.45, "imgsz": 640, "return_json": true } }' ``` #### SAM2 Segmentation Example Segment objects using point prompts: ```bash curl -X POST 'https://api.w.ai/v1/predictions' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer wsk-examplekey' \ --data '{ "model": "sam2", "input": { "image": "https://images.cocodataset.org/val2017/000000039769.jpg", "points": [ { "x": 500, "y": 375, "label": 1 } ], "mask_type": "highlighted", "return_json": false } }' ``` #### SAM2 Video Segmentation Example Track and segment objects across video frames: ```bash curl -X POST 'https://api.w.ai/v1/predictions' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer wsk-examplekey' \ --data '{ "model": "sam2", "input": { "video": "https://example.com/video.mp4", "points": [ { "x": 200, "y": 150, "label": 1 } ], "video_fps": 25, "output_frame_interval": 1, "annotation_type": "mask" } }' ``` #### Request Parameters | Parameter | Type | Required | Default | Description | | ------------- | ------ | -------- | ------- | ------------------------------------------------------ | | `model` | string | ✅ | | Model ID (`yolo11n` or `sam2`) | | `input.image` | string | ✅\* | | Image URL or base64. \*Either image or video required. | | `input.video` | string | ✅\* | | Video URL or base64. \*Either image or video required. | **YOLO11n Parameters:** | Parameter | Type | Default | Description | | ------------------- | ------- | ------- | ----------------------------------------- | | `input.conf` | number | `0.25` | Confidence threshold (0-1) | | `input.iou` | number | `0.45` | IOU threshold for NMS (0-1) | | `input.imgsz` | integer | `640` | Input image size (320-1280) | | `input.return_json` | boolean | `true` | Return JSON detections or annotated image | **SAM2 Parameters:** | Parameter | Type | Default | Description | | ------------------------------ | ------- | ------------- | ----------------------------------------------------------------------- | | `input.points` | array | | Point prompts: `[{x, y, label}]` where label 1=foreground, 0=background | | `input.boxes` | array | | Box prompts: `[{x1, y1, x2, y2}]` | | `input.mask_type` | string | `highlighted` | Mask visualization style | | `input.annotation_type` | string | `mask` | Output type: `mask`, `contour`, etc. | | `input.points_per_side` | integer | `32` | Auto-mask grid density (8-128) | | `input.pred_iou_thresh` | number | `0.88` | Predicted IOU threshold (0-1) | | `input.stability_score_thresh` | number | `0.95` | Mask stability threshold (0-1) | | `input.use_m2m` | boolean | `true` | Enable mask-to-mask refinement | | `input.multiview` | boolean | `false` | Multi-view consistency | **Video-specific Parameters:** | Parameter | Type | Default | Description | | ----------------------------- | ------- | ------- | ------------------------------ | | `input.video_fps` | integer | `25` | Output video frame rate (1-60) | | `input.output_frame_interval` | integer | `1` | Process every Nth frame (1-10) | | `input.output_format` | string | `webp` | Output format for frames | | `input.output_quality` | integer | `80` | Output quality (1-100) | *** ### Video Generation (Audio) Generate audio for video clips using video-to-audio models. #### Endpoint ``` POST /v1/videos/generations ``` #### Example ```bash curl -X POST 'https://api.w.ai/v1/videos/generations' \ --header 'Authorization: Bearer wsk-examplekey' \ --header 'Content-Type: multipart/form-data' \ --form 'model=mmaudio' \ --form 'video=@/path/to/video.mp4' \ --form 'prompt=upbeat background music with gentle piano' ``` #### Request Parameters (multipart/form-data) | Parameter | Type | Required | Description | | ----------------- | ------- | -------- | ------------------------ | | `model` | string | ✅ | Model ID | | `video` | file | ✅ | Source video file | | `prompt` | string | | Audio description | | `negative_prompt` | string | | What to avoid | | `seed` | integer | | Seed for reproducibility | | `duration` | number | | Target duration | | `num_steps` | integer | | Generation steps | | `cfg_strength` | number | | Guidance strength | | `stream` | boolean | | Enable streaming | *** ### Responses API (Items-Based) Alternative API format based on the [Open Responses](https://www.openresponses.org/) specification with structured Items. #### Endpoint ``` POST /v1/responses ``` #### Example ```bash curl -X POST 'https://api.w.ai/v1/responses' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer wsk-examplekey' \ --data '{ "model": "llama-3.2-1b-4bit", "input": [ { "type": "message", "role": "user", "content": "Explain quantum computing in simple terms." } ], "max_output_tokens": 500 }' ``` #### Request Parameters | Parameter | Type | Required | Description | | --------------------- | ------------- | -------- | --------------------------------------------------- | | `model` | string | ✅ | Model ID | | `input` | array | ✅ | Array of Item objects | | `instructions` | string | | System-level instructions | | `tools` | array | | Function tool definitions | | `tool_choice` | string/object | | Tool selection mode | | `stream` | boolean | | Enable streaming | | `temperature` | number | | Sampling temperature (0-2) | | `max_output_tokens` | integer | | Maximum output tokens | | `top_p` | number | | Nucleus sampling (0-1) | | `frequency_penalty` | number | | Frequency penalty (-2 to 2) | | `presence_penalty` | number | | Presence penalty (-2 to 2) | | `parallel_tool_calls` | boolean | | Allow parallel tool execution | | `text.format.type` | string | | Output format: `text`, `json_object`, `json_schema` | #### Item Types * **User Message**: `{ "type": "message", "role": "user", "content": "..." }` * **System Message**: `{ "type": "message", "role": "system", "content": "..." }` * **Developer Message**: `{ "type": "message", "role": "developer", "content": "..." }` * **Assistant Message**: `{ "type": "message", "role": "assistant", "content": "..." }` * **Function Call**: `{ "type": "function_call", "call_id": "...", "name": "...", "arguments": "..." }` * **Function Output**: `{ "type": "function_call_output", "call_id": "...", "output": "..." }` #### Content Types For multimodal inputs, use content arrays: ```json { "type": "message", "role": "user", "content": [ { "type": "input_text", "text": "What's in this image?" }, { "type": "input_image", "image_url": "https://example.com/image.jpg" }, { "type": "input_file", "file_data": "base64...", "filename": "doc.pdf" } ] } ``` #### Structured Output (JSON Schema) ```json { "model": "llama-3.3-70b-4bit", "input": [{ "type": "message", "role": "user", "content": "List 3 colors" }], "text": { "format": { "type": "json_schema", "json_schema": { "name": "color_list", "schema": { "type": "object", "properties": { "colors": { "type": "array", "items": { "type": "string" } } } }, "strict": true } } } } ``` *** ### Streaming Responses Enable real-time streaming by setting `stream: true`. Responses are sent as Server-Sent Events (SSE). #### Example ```bash curl -X POST 'https://api.w.ai/v1/chat/completions' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer wsk-examplekey' \ --data '{ "model": "llama-3.2-1b-4bit", "messages": [{ "role": "user", "content": "Write a haiku about AI" }], "stream": true }' ``` #### Response Format ``` data: {"id":"...","object":"chat.completion.chunk","choices":[{"delta":{"content":"token"},"index":0}]} data: [DONE] ``` *** ### Error Handling API errors follow the OpenAI error format: ```json { "error": { "message": "Error description", "type": "error_type", "code": "error_code" } } ``` #### Common Error Codes | Code | Description | | ----- | ------------------------------- | | `401` | Invalid or missing API key | | `400` | Invalid request parameters | | `429` | Rate limit exceeded | | `503` | Service temporarily unavailable | *** ### Rate Limits Rate limits vary by endpoint and account tier. Contact for higher limits. *** ### SDK Compatibility The W\.ai API is **OpenAI SDK compatible**. Use your preferred OpenAI client library: #### Python ```python from openai import OpenAI client = OpenAI( base_url="https://api.w.ai/v1", api_key="wsk-examplekey" ) response = client.chat.completions.create( model="llama-3.2-1b-4bit", messages=[{"role": "user", "content": "Hello!"}] ) ``` #### JavaScript/TypeScript ```typescript import OpenAI from 'openai'; const client = new OpenAI({ baseURL: 'https://api.w.ai/v1', apiKey: 'wsk-examplekey' }); const response = await client.chat.completions.create({ model: 'llama-3.2-1b-4bit', messages: [{ role: 'user', content: 'Hello!' }] }); ``` # Models *If there is a particular model you'd like to see on w\.ai, let us know.* *** ### Models API Overview The `/v1/models` endpoint provides a list of all the currently available models on the w\.ai network, including essential metadata for easy integration into your application. #### Endpoint ``` GET /v1/models ``` #### Description This endpoint returns an array of available model objects, each detailing information such as name, creation time, and capabilities, helping you easily identify suitable models for your tasks. #### Request * **Method:** `GET` * **URL:** `https://api.w.ai/v1/models` **Required Headers:** * `Authorization: Bearer ` * `Content-Type: application/json` #### Example Request ```bash curl -X GET https://api.w.ai/v1/models \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" ``` #### Response **Success (`200 OK`)** Returns a JSON object containing an array of available model objects with their respective metadata. **Example Response** ```json { "data": [ { "id": "qwen3-4b-4bit", "object": "model", "created": 1676235352, "name": "qwen3-4b-4bit" }, { "id": "llama-3.2-1b-4bit", "object": "model", "created": 1680526341, "name": "llama-3.2-1b-4bit" } ] } ``` **Response Fields** * **`data`**: Array containing model objects. * **`id`**: Unique identifier for the model. * **`object`**: Type of the object, typically `model`. * **`created`**: Unix timestamp indicating when the model was created. * **`name`**: The name identifier of the model.