# 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 <support@w.ai> 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!' }]
});
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.w.ai/w.ai-api/api-features.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.