What is ?

Wiro is an AI model marketplace and API platform that lets you run AI models through a single, unified API. Instead of managing infrastructure for each model provider, you make one API call to Wiro and we handle the rest.

• Unified API — one interface for all models (image generation, LLMs, audio, video, and more)
• Pay-per-use pricing — only pay for what you consume, no upfront commitments
• Real-time WebSocket updates — stream task progress and outputs live
• 9 SDK languages — curl, Python, Node.js, PHP, C#, Swift, Dart, Kotlin, Go

Base URL

All API requests are made to:

https://api.wiro.ai/v1

WebSocket connections use:

wss://socket.wiro.ai/v1

Quick Start

1. Sign up Create an account at wiro.ai
2. Create a project Go to the Dashboard to get your API key
3. Pick a model Browse the marketplace and choose a model
4. Make your first API call See Code Examples for full end-to-end samples

Response Format

Every API response returns JSON with a consistent structure:

{
  "result": true,
  "errors": [],
  "data": { ... }
}

When result is false, the errors array contains human-readable messages describing what went wrong.

Rate Limits & Error Handling

API requests are rate-limited per project. If you exceed the limit, the API returns a 429 Too Many Requests status. Implement exponential backoff in your retry logic.

Common HTTP status codes:

• 200 — Success
• 400 — Bad request (check parameters)
• 401 — Unauthorized (invalid or missing API key)
• 403 — Forbidden (signature mismatch or insufficient permissions)
• 429 — Rate limit exceeded
• 500 — Internal server error

Overview

Wiro supports two authentication methods. You choose the method when creating a project — it cannot be changed afterward.

Comparison

How to Choose

• Building a client-side or mobile app? Use Signature-Based.
• Running a server-side backend with controlled access? API Key Only is simpler.
• Unsure? Default to Signature-Based — it's always the safer option.

What is a Project?

A project is a container that holds your API keys, billing settings, and usage tracking. Each project gets its own API key and secret, letting you separate environments (development, staging, production) or different applications.

• Each project has its own API key and (optionally) API secret
• Usage and billing are tracked per project
• You can create multiple projects under one account

Creating a Project

1. Go to the Dashboard Navigate to wiro.ai/panel
2. Open Projects Go to Projects and click New Project
3. Name your project Enter a descriptive project name
4. Select authentication method Signature-Based — generates API key + secret  |  API Key Only — generates only an API key
5. Create Click Create and copy your credentials immediately

API Credentials

After creating a project, your API key (and secret, if signature-based) are displayed once. Copy and store them securely — you won't be able to view the secret again.

Managing Projects

From the Projects page in your Dashboard, you can:

• Update name — rename your project at any time
• Regenerate keys — invalidates existing keys and generates new ones
• View usage — see API calls, costs, and task history
• Delete project — permanently removes the project and revokes all keys

Regenerating keys immediately invalidates the old ones. Update your application with the new credentials before the old ones stop working.

POST /Tool/List

Returns a paginated list of available models. Filter by categories, search by name, and sort results.

Response

{
  "result": true,
  "errors": [],
  "total": 2,
  "tool": [
    {
      "id": "1611",
      "title": "Virtual Try-on",
      "slugowner": "wiro",
      "slugproject": "Virtual Try-On",
      "cleanslugowner": "wiro",
      "cleanslugproject": "virtual-try-on",
      "description": "Integrate the Wiro Virtual Try-On API...",
      "image": "https://cdn.wiro.ai/uploads/models/...",
      "computingtime": "10 seconds",
      "categories": ["tool", "image-to-image", "image-editing"],
      "tags": [],
      "marketplace": 1,
      "onlymembers": "1",
      "averagepoint": "5.00",
      "commentcount": "1",
      "dynamicprice": "[{\"inputs\":{},\"price\":0.09,\"priceMethod\":\"cpr\"}]",
      "taskstat": {
        "runcount": 672,
        "successcount": "254",
        "errorcount": "198",
        "lastruntime": "1774007585"
      }
    }
  ]
}

POST /Tool/Detail

Returns full details for a specific model, including its input parameters, pricing, categories, and configuration.

Response

{
  "result": true,
  "errors": [],
  "tool": [{
    "id": "1611",
    "title": "Virtual Try-on",
    "slugowner": "wiro",
    "slugproject": "Virtual Try-On",
    "cleanslugowner": "wiro",
    "cleanslugproject": "virtual-try-on",
    "description": "Integrate the Wiro Virtual Try-On API...",
    "image": "https://cdn.wiro.ai/uploads/models/...",
    "computingtime": "10 seconds",
    "readme": "<p>The Wiro Virtual Try-On AI model...</p>",
    "categories": ["tool", "image-to-image", "image-editing"],
    "parameters": null,
    "inspire": [
      {
        "inputImageHuman": "https://cdn.wiro.ai/uploads/sampleinputs/...",
        "inputImageClothes": ["https://cdn.wiro.ai/..."]
      }
    ],
    "samples": ["https://cdn.wiro.ai/uploads/models/..."],
    "tags": [],
    "marketplace": 1,
    "onlymembers": "1",
    "dynamicprice": "[{\"inputs\":{},\"price\":0.09,\"priceMethod\":\"cpr\"}]",
    "averagepoint": "5.00",
    "commentcount": "1",
    "ratedusercount": "3",
    "taskstat": {
      "runcount": 672,
      "successcount": "254",
      "errorcount": "198",
      "lastruntime": "1774007585"
    },
    "seotitle": "AI Virtual Try-On: Integrate Realistic Apparel Fitting",
    "seodescription": "Integrate the Wiro Virtual Try-On API..."
  }]
}

Model Browser

Browse available models interactively. Click on a model to see its details on the model page.

POST /Run/{owner-slug}/{model-slug}

Starts an AI model run. The endpoint accepts model-specific parameters and returns a task ID you can use to track progress via polling, WebSocket, or webhook by providing a callbackUrl parameter — Wiro will POST the result to your URL when the task completes.

Content Types

JSON (application/json)

Use JSON for text-based inputs — prompts, configuration, numeric parameters. This is the default and most common format.

Multipart (multipart/form-data)

Use multipart when the model requires file inputs (images, audio, documents). Include files as form fields and other parameters as text fields.

Request Parameters

Parameters vary by model. Use the /Tool/Detail endpoint to discover which parameters a model accepts. The following optional parameters apply to all runs:

Response

A successful run returns a task ID and a WebSocket access token:

{
  "result": true,
  "errors": [],
  "taskid": "2221",
  "socketaccesstoken": "eDcCm5yyUfIvMFspTwww49OUfgXkQt"
}

Full Flow

The typical workflow after calling the Run endpoint:

1. Run — call POST /Run/{owner-slug}/{model-slug} and receive a task ID
2. Track — connect via WebSocket or poll POST /Task/Detail
3. Receive — get outputs as the model produces them (streaming or final)
4. Complete — task reaches end status with full results

For real-time streaming, use the WebSocket connection with the socketaccesstoken returned in the run response. For simpler integrations, poll the Task Detail endpoint every few seconds.

Discovering Parameters

Every model has its own set of input parameters. Use the /Tool/Detail endpoint to retrieve a model's parameter definitions. The response includes a parameters array where each item describes a parameter group with its items:

{
  "parameters": [
    {
      "title": "Input",
      "items": [
        {
          "id": "prompt",
          "type": "textarea",
          "label": "Prompt",
          "required": true,
          "placeholder": "Describe what you want...",
          "note": "Text description of the desired output"
        },
        {
          "id": "inputImage",
          "type": "fileinput",
          "label": "Input Image",
          "required": true,
          "note": "Upload an image or provide a URL"
        }
      ]
    }
  ]
}

Parameter Types

JSON vs Multipart

The content type of your request depends on whether the model requires file inputs:

File Upload Patterns

Single File (fileinput)

For parameters like inputImage, send either a file or a URL. When using multipart, always include both the {id} and {id}Url fields — leave one empty:

# Option 1: Upload file — send file in {id}, empty {id}Url
curl -X POST "https://api.wiro.ai/v1/Run/{owner-slug}/{model-slug}" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "inputImage=@/path/to/photo.jpg" \
  -F "inputImageUrl="

# Option 2: Send URL via {id}Url — send empty {id}, URL in {id}Url
curl -X POST "https://api.wiro.ai/v1/Run/{owner-slug}/{model-slug}" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "inputImage=" \
  -F "inputImageUrl=https://example.com/photo.jpg"

# Option 3: Pass URL directly in {id} (no {id}Url needed)
curl -X POST "https://api.wiro.ai/v1/Run/{owner-slug}/{model-slug}" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "inputImage=https://example.com/photo.jpg"

Multiple Files (multifileinput)

For parameters like inputDocumentMultiple, upload up to N files, send comma-separated URLs, or mix both:

# Option 1: Upload multiple files — add empty {id}Url
curl -X POST "https://api.wiro.ai/v1/Run/{owner-slug}/{model-slug}" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "inputDocumentMultipleUrl="

# Option 2: Send URLs (comma-separated in {id}Url) — add empty {id}
curl -X POST "https://api.wiro.ai/v1/Run/{owner-slug}/{model-slug}" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "inputDocumentMultiple=" \
  -F "inputDocumentMultipleUrl=https://example.com/doc1.pdf,https://example.com/doc2.pdf"

# Option 3: Mixed — files in {id}, URLs in {id}Url
curl -X POST "https://api.wiro.ai/v1/Run/{owner-slug}/{model-slug}" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "[email protected]" \
  -F "inputDocumentMultipleUrl=https://example.com/doc2.pdf,https://example.com/doc3.pdf"

Combined (combinefileinput)

For parameters like inputImageClothes, files and URLs go directly in the same {id} field — no {id}Url suffix:

# Option 1: Upload files — each as a separate {id} entry
curl -X POST "https://api.wiro.ai/v1/Run/{owner-slug}/{model-slug}" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "[email protected]" \
  -F "[email protected]"

# Option 2: Send URLs — each directly in {id}
curl -X POST "https://api.wiro.ai/v1/Run/{owner-slug}/{model-slug}" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "inputImageClothes=https://example.com/shirt.jpg" \
  -F "inputImageClothes=https://example.com/pants.jpg"

# Option 3: Mixed — files and URLs in the same {id} field
curl -X POST "https://api.wiro.ai/v1/Run/{owner-slug}/{model-slug}" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "[email protected]" \
  -F "inputImageClothes=https://example.com/pants.jpg"

Common Model Patterns

Image Generation (text-to-image)

Models like Stable Diffusion, Flux — JSON body, no file uploads:

{
  "prompt": "A futuristic city at sunset",
  "negative_prompt": "blurry, low quality",
  "width": 1024,
  "height": 1024
}

Image-to-Image (upscaler, style transfer)

Models that take an input image — multipart with file upload:

curl -X POST "https://api.wiro.ai/v1/Run/{owner-slug}/{model-slug}" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "[email protected]" \
  -F "scale=4"

Virtual Try-On

Multiple image inputs — multipart with multiple files:

curl -X POST "https://api.wiro.ai/v1/Run/{owner-slug}/{model-slug}" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "[email protected]" \
  -F "[email protected]"

LLM / Document Processing

Text prompt with optional document uploads:

curl -X POST "https://api.wiro.ai/v1/Run/{owner-slug}/{model-slug}" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "[email protected]" \
  -F "prompt=Extract the candidate name and skills" \
  -F "outputType=json" \
  -F "language=en"

Realtime Voice Conversation

Realtime voice models accept configuration parameters (voice, system instructions, audio format, etc.) as JSON. Parameters vary per model — use /Tool/Detail to discover them. The actual audio interaction happens over Realtime Voice WebSocket after the task starts:

// Example: OpenAI GPT Realtime
{
  "voice": "marin",
  "system_instructions": "You are a helpful voice assistant.",
  "input_audio_format": "audio/pcm",
  "output_audio_format": "audio/pcm",
  "input_audio_rate": "24000",
  "output_audio_rate": "24000"
}

Webhook Callback

All models support an optional callbackUrl parameter. When provided, Wiro will POST the task result to your URL when the task completes — no polling required:

{
  "prompt": "A sunset over mountains",
  "callbackUrl": "https://your-server.com/webhook/wiro"
}

Task Lifecycle

Every model run creates a task that progresses through a defined set of stages:

Task Statuses

Realtime Conversation Only

The following statuses are exclusive to realtime conversation models (e.g. voice AI). They are not emitted for standard model runs.

Determining Success or Failure

Both successful and failed tasks reach task_postprocess_end. The status alone does not tell you whether the task succeeded. Wait for task_postprocess_end and then check pexit or outputs (or both) to determine the actual result:

• pexit — the process exit code. "0" means success, any other value means the model encountered an error. This is the most reliable indicator.
• outputs — the output files array. For non-LLM models, a successful run populates this with CDN URLs. If it's empty or missing, the task likely failed.

// Success (image/audio model): pexit "0", outputs present
{
  "pexit": "0",
  "outputs": [{ "name": "0.png", "url": "https://cdn1.wiro.ai/..." }]
}

// Success (LLM model): pexit "0", outputs empty, response in debugoutput
{
  "pexit": "0",
  "outputs": [],
  "debugoutput": "Hello! How can I help you today?"
}

// Failure: pexit non-zero
{
  "pexit": "1",
  "outputs": []
}

Billing & Cost

The totalcost field in the Task Detail response shows the actual cost charged for the run. Only successful tasks are billed — if pexit is non-zero (failure), the task is not charged and totalcost will be "0".

// Successful run — billed
{
  "status": "task_postprocess_end",
  "pexit": "0",
  "totalcost": "0.003510000000",
  "elapsedseconds": "6.0000"
}

// Failed run — not billed
{
  "status": "task_postprocess_end",
  "pexit": "1",
  "totalcost": "0",
  "elapsedseconds": "4.0000"
}

Use the totalcost field to track spending per task. For more details on how costs are calculated, see Pricing.

LLM Models

For LLM (Large Language Model) requests, the model's response is written to debugoutput rather than the outputs file array. When polling with Task Detail, read the debugoutput field to get the LLM's text response.

For real-time streaming of LLM responses, use WebSocket instead of polling. Each task_output event delivers a chunk of the response as it's generated, giving your users an instant, token-by-token experience.

POST /Task/Detail

Retrieves the current status and output of a task. You can query by either tasktoken or taskid.

Response

{
  "result": true,
  "errors": [],
  "total": "1",
  "tasklist": [{
    "id": "534574",
    "socketaccesstoken": "eDcCm5yyUfIvMFspTwww49OUfgXkQt",
    "parameters": { "prompt": "Hello, world!" },
    "status": "task_postprocess_end",
    "pexit": "0",
    "debugoutput": "",
    "starttime": "1734513809",
    "endtime": "1734513813",
    "elapsedseconds": "6.0000",
    "totalcost": "0.003510000000",
    "outputs": [{
      "name": "0.png",
      "contenttype": "image/png",
      "size": "202472",
      "url": "https://cdn1.wiro.ai/.../0.png"
    }]
  }]
}

POST /Task/Cancel

Cancels a task that is still in the queue stage. Tasks that have already been assigned to a worker cannot be cancelled — use Kill instead.

POST /Task/Kill

Terminates a task that is currently running (any status after assign). The worker will stop processing and the task will move to cancel status.

Overview

LLM (Large Language Model) requests on Wiro work differently from standard model runs:

• Responses are delivered via debugoutput, not the outputs file array
• Streaming task_output messages contain structured thinking and answer arrays — not plain strings
• Multi-turn conversations are supported via session_id and user_id parameters
• pexit is the primary success indicator (outputs will be empty)

Available LLM models include:

• openai/gpt-5-2 — GPT-5-2
• openai/gpt-oss-20b — GPT OSS 20B
• qwen/qwen3-5-27b — Qwen 3.5 27B

Session & Chat History

Wiro maintains conversation history per session. By sending a session_id, the model remembers previous messages and can build on the context of the conversation. Combined with user_id, this enables fully stateful chat experiences:

// First message — start a new session
{
  "prompt": "What is quantum computing?",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}

// Follow-up — reuse the same session_id
{
  "prompt": "Can you explain qubits in more detail?",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}

Thinking & Answer Phases

Many LLM models separate their output into two phases:

• Thinking — the model's internal reasoning process (chain-of-thought)
• Answer — the final response to the user

When streaming via WebSocket, task_output messages for LLM models contain a structured object (not a plain string):

// LLM task_output message format
{
  "type": "task_output",
  "id": "534574",
  "tasktoken": "eDcCm5yy...",
  "message": {
    "thinking": ["Let me analyze this step by step...", "The key factors are..."],
    "answer": ["Quantum computing uses qubits that can exist in superposition..."]
  }
}

Both thinking and answer are arrays of strings. Each element represents a chunk — they grow as the model streams its response. A model may alternate between thinking and answering multiple times.

Streaming Flow

The complete flow for streaming an LLM response:

1. Run the model with prompt, session_id, and user_id
2. Connect to WebSocket and send task_info
3. Receive task_output messages — each contains the growing thinking and answer arrays
4. Display the latest answer array content to the user (optionally show thinking in a collapsible section)
5. Complete — on task_postprocess_end, check pexit for success

Each task_output event contains the full accumulated thinking and answer arrays up to that point — not just the new chunk. Simply replace your displayed content with the latest arrays.

Polling Alternative

If you don't need real-time streaming, you can poll POST /Task/Detail instead. The final response will be in the debugoutput field as a merged plain text string (thinking + answer combined):

{
  "result": true,
  "tasklist": [{
    "status": "task_postprocess_end",
    "pexit": "0",
    "debugoutput": "Quantum computing uses qubits that can exist in superposition...",
    "outputs": []
  }]
}

Connection URL

wss://socket.wiro.ai/v1

Connect to this URL after calling the Run endpoint. Use the socketaccesstoken from the run response to register your session.

Connection Flow

1. Connect — open a WebSocket connection to wss://socket.wiro.ai/v1
2. Register — send a task_info message with your tasktoken
3. Receive — listen for messages as the task progresses through its lifecycle
4. Close — disconnect after the task_postprocess_end event (this is the final event with results)

Registration message format:

{
  "type": "task_info",
  "tasktoken": "your-socket-access-token"
}

Message Types

Binary Frames

For realtime voice models, the WebSocket may send binary frames containing raw audio data. Check if the received message is a Blob (browser) or Buffer (Node.js) before parsing as JSON.

Ending a Session

For realtime/streaming models that maintain a persistent session, send a task_session_end message to gracefully terminate:

{
  "type": "task_session_end",
  "tasktoken": "your-socket-access-token"
}

After sending this, wait for the task_end event before closing the connection.

Overview

Realtime voice models enable two-way audio conversations with AI. Unlike standard model runs that process a single input and return a result, realtime sessions maintain a persistent WebSocket connection where you stream microphone audio and receive AI speech in real time.

The flow is:

1. Run the realtime model via POST /Run to get a socketaccesstoken
2. Connect to the WebSocket and send task_info with your token
3. Wait for task_stream_ready — the model is ready to receive audio
4. Stream microphone audio as binary frames
5. Receive AI audio as binary frames and play them
6. End the session with task_session_end

Run Parameters

Each realtime model has its own set of parameters. Use POST /Tool/Detail to discover the exact parameters for a specific model. See Model Parameters for details on parameter types.

Available realtime conversation models include:

• openai/gpt-realtime-mini — GPT Mini Realtime Voice Assistant
• openai/gpt-realtime — GPT Realtime Voice Assistant
• elevenlabs/realtime-conversational-ai — ElevenLabs Conversational AI

Common parameters across realtime models typically include voice selection, system instructions, and audio format settings. Example run for an OpenAI realtime model:

curl -X POST "https://api.wiro.ai/v1/Run/openai/gpt-realtime-mini" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "voice": "marin",
    "system_instructions": "You are a friendly assistant.",
    "input_audio_format": "audio/pcm",
    "output_audio_format": "audio/pcm",
    "input_audio_rate": "24000",
    "output_audio_rate": "24000"
  }'

Connection & Registration

After running the task, connect to the WebSocket and register with task_info:

var ws = new WebSocket("wss://socket.wiro.ai/v1");

ws.onopen = function() {
  ws.send(JSON.stringify({
    type: "task_info",
    tasktoken: "YOUR_SOCKET_ACCESS_TOKEN"
  }));
};

Realtime Events

During a realtime session, you'll receive these WebSocket events:

Audio Format

Both directions (microphone → server, server → client) use the same format:

Binary Frame Format

Every binary WebSocket frame (in both directions) is structured as:

[tasktoken]|[PCM audio data]

The pipe character | (0x7C) separates the token from the raw audio bytes.

Sending Microphone Audio

Capture microphone at 24 kHz using the Web Audio API with an AudioWorklet. Convert Float32 samples to Int16, prepend your task token, and send as a binary frame.

Key steps:

1. Request microphone with getUserMedia (enable echo cancellation and noise suppression)
2. Create an AudioContext at 24,000 Hz sample rate
3. Use an AudioWorklet to buffer and convert samples to Int16
4. Send each chunk as tasktoken|pcm_data binary frame

Receiving AI Audio

AI responses arrive as binary WebSocket frames in the same PCM Int16 24 kHz format. To play them:

1. Check if the message is a Blob (binary) before parsing as JSON
2. Find the pipe | separator and extract audio data after it
3. Convert Int16 → Float32 and create an AudioBuffer
4. Schedule gapless playback using AudioBufferSourceNode

Transcripts

Both user and AI speech are transcribed automatically. Transcripts arrive as task_output messages with a string prefix:

• TRANSCRIPT_USER: — what the user said
• TRANSCRIPT_AI: — what the AI said

// Example task_output message
{
  "type": "task_output",
  "message": "TRANSCRIPT_USER:What's the weather like today?"
}

{
  "type": "task_output",
  "message": "TRANSCRIPT_AI:I'd be happy to help, but I don't have access to real-time weather data."
}

Ending a Session

To gracefully end a realtime session, send task_session_end:

{
  "type": "task_session_end",
  "tasktoken": "YOUR_SOCKET_ACCESS_TOKEN"
}

After sending this, the server will process any remaining audio, send final cost/transcript events, and then emit task_end. Wait for task_end before closing the WebSocket.

Overview

The Files API lets you organize and upload data that can be referenced in model runs. Common use cases include:

• Training data — upload datasets for fine-tuning models
• File inputs — provide images, audio, or documents as model inputs
• Batch processing — store files for repeated use across multiple runs

POST /File/FolderCreate

Creates a new folder to organize your uploaded files.

Response

{
  "result": true,
  "errors": [],
  "data": {
    "id": "folder-abc123",
    "name": "training-data",
    "parentId": null,
    "createdAt": "2025-01-15T10:00:00Z"
  }
}

POST /File/Upload

Uploads a file using multipart/form-data. You can optionally assign it to a folder.

File size limit: 100 MB per file.

Supported file types: Images (jpg, png, gif, jpeg, webp, heic), video (mp4, webm, mov), audio (mp3, wav, m4a), documents (pdf, csv, docx, xlsx, pptx, txt, md, epub), and ZIP archives (automatically extracted).

Response

{
  "result": true,
  "errors": [],
  "list": [{
    "id": "file-id",
    "name": "dataset.csv",
    "contenttype": "text/csv",
    "size": "1048576",
    "parentid": "folder-id",
    "url": "https://cdn1.wiro.ai/...",
    "addedtime": "1716276727",
    "accesskey": "..."
  }]
}

Using Files in Runs

Once uploaded, reference a file by its URL or ID in your model run parameters. For example, an image upscaler model might accept a imageUrl parameter — pass the URL returned from the upload response.

{
  "imageUrl": "https://files.wiro.ai/...",
  "scale": 4
}

Overview

When you run an AI model through Wiro, you are billed based on the type of work performed. Each model has its own pricing, visible on the model's page in the marketplace and on the pricing page. You pay only for successful runs — server errors are never billed.

Wiro uses a prepaid credit model. You add credits to your account and they are drawn down as you use models. Credits also determine your concurrency limit.

Billing Methods

Every model on Wiro uses one of the following billing methods. The method is set per model and determines how the cost is calculated.

Fixed-Rate Methods

Usage-Based Methods

Special Methods

Dynamic Pricing

Many models have dynamic pricing — the cost varies based on the input parameters you choose. For example, a video generation model might charge different rates depending on the resolution and duration you select.

The pricing is returned in the dynamicprice field of the Tool/List and Tool/Detail API responses as a JSON array:

[
  {
    "inputs": { "resolution": "720p", "duration": "5" },
    "price": 0.13,
    "priceMethod": "cpr"
  },
  {
    "inputs": { "resolution": "1080p", "duration": "5" },
    "price": 0.29,
    "priceMethod": "cpr"
  }
]

How Dynamic Pricing Works

Each entry in the dynamicprice array represents a pricing tier:

When inputs contains specific parameter values (e.g. "resolution": "720p"), that price only applies when you run the model with those exact parameters. When inputs is empty ({}), it's a flat rate that applies regardless of input parameters.

Input matching also supports QUANTITY values (e.g. "QUANTITY:1", "QUANTITY:3") for models where the number of input files affects pricing.

Example: Video Generation Pricing

A video model might have pricing tiers based on resolution and duration:

Example: Simple Flat Pricing

An image generation model with a flat rate:

[{ "inputs": {}, "price": 0.03, "priceMethod": "cpr" }]

This means every run costs $0.03, regardless of parameters.

Fallback Pricing (Per-Second)

When a model does not have dynamicprice set, billing falls back to per-second pricing:

totalcost = elapsed_seconds × cps

Where cps (cost per second) is either the model's own rate or the queue group's default rate. The API also returns an approximatelycost field — an estimate based on the model's average run time:

approximatelycost = average_elapsed_seconds × cps

This gives you a rough idea of the expected cost before running the model.

Checking Prices

Via the API

Pricing information is included in both the Tool/List and Tool/Detail responses in the dynamicprice field. Use POST /Tool/Detail with the model's slugowner and slugproject to get full pricing details.

Via MCP

When using the MCP server, both search_models and get_model_schema tools return pricing information in their responses. Your AI assistant can check the cost before running a model.

Pricing Page

Browse and compare model prices interactively on the pricing page. Select a budget to see how many runs each model can perform.

What You Pay For

You are billed for successfully completed model runs. A run is successful when the task reaches task_postprocess_end status with pexit of "0". The actual cost is recorded in the task's totalcost field, which you can retrieve via Task/Detail.

What You Are Not Charged For

• Server errors — if a run fails due to a server-side error, no charge is incurred.
• Queue time — time spent waiting in the queue before processing starts is free.
• Cancelled tasks — tasks cancelled before processing completes are not billed.

Monitoring Your Spending

• Check the totalcost field in Task/Detail responses to see the cost of individual runs.
• View your overall balance, usage history, and billing details in the Dashboard.
• When using MCP, the get_task tool returns the cost of completed runs.

Overview

Concurrency limits control how many tasks your account can process at the same time. When you reach your limit, the API returns an error response with code 96. You should wait for a running task to complete before submitting a new one, or add funds to increase your limit.

How It Works

Your concurrency limit is determined by your current account balance:

• When your balance is $250 or below, you can run concurrent tasks equal to 10% of your current USD balance (minimum 1).
• When your balance is above $250, there is no concurrency limit.

Examples

The formula: max(1, floor(balance_usd * 0.10)). Once your balance exceeds $250, all limits are removed.

What Counts as Active

Only tasks that are actively being processed count toward your concurrency limit. A task is considered active from task_queue until it reaches a terminal status:

• task_postprocess_end — task completed (success or failure)
• task_cancel — task was cancelled or killed

Once a task reaches either of these statuses, it no longer counts toward your limit.

API Response

When you hit the concurrency limit, the POST /Run endpoint returns an error with code 96:

{
  "result": false,
  "errors": [
    {
      "code": 96,
      "message": "You have reached your concurrent task limit. With your current balance of $50.00, you can run up to 5 tasks at the same time. Add funds to increase your limit."
    }
  ]
}

The error message includes your current balance and the calculated limit, so you know exactly how many concurrent tasks you can run.

Error Codes

Increasing Your Limit

To increase your concurrency limit, simply add credits to your account. Your limit is recalculated automatically based on your current balance at the time of each run request.

For enterprise needs or custom concurrency arrangements, contact support.

Best Practices

• Check error code 96 — if you get this error, wait for a running task to complete before submitting new ones.
• Use WebSocket for monitoring — instead of polling /Task/Detail repeatedly, connect via WebSocket to get real-time updates without extra API calls.
• Use wait=false in MCP — for long-running models (video, 3D), submit with wait=false and check with get_task to avoid holding connections.
• Implement exponential backoff — if polling task status, start at 3 seconds and increase the interval for longer tasks.

Response Format

When an API request fails, the response includes result: false and an errors array:

{
  "result": false,
  "errors": [
    {
      "code": 97,
      "message": "Insufficient balance"
    }
  ]
}

All API responses return HTTP 200 — use the result field and error code to determine success or failure.

Error Codes

Error codes indicate the category of the problem. Use these for conditional logic in your application.

Authentication Errors

Returned when API key or bearer token authentication fails. All return HTTP 401.

Run Errors

Returned by POST /Run/{owner}/{model}.

Balance & Limits

Validation Errors

Model Access Errors

Task Errors

Returned by POST /Task/Detail, POST /Task/Cancel, and POST /Task/Kill.

Error Handling

Always check result first, then inspect the code in the errors array:

const data = await response.json();

if (!data.result) {
  const error = data.errors[0];
  switch (error.code) {
    case 96:
      console.log('Concurrent limit — wait for a task to finish');
      break;
    case 97:
      console.log('Insufficient balance — add funds');
      break;
    case 98:
      console.log('Sign in required');
      break;
    default:
      console.log('Error:', error.message);
  }
}

Retry Strategy

Overview

Each example below demonstrates the full Wiro workflow: authenticate, run a model, poll for task completion, and retrieve the result. Choose your preferred language from the tabs.

• curl — Shell scripting with bash
• Python — Using the requests library
• Node.js — Using axios
• PHP — Using cURL functions
• C# — Using HttpClient (.NET 6+)
• Swift — Using async/await URLSession
• Dart — Using the http package
• Kotlin — Using java.net.http
• Go — Using the standard library net/http

Full Examples

Select a language tab to see the complete example. All examples perform the same steps:

1. Set up authentication headers
2. Run a model (POST /Run/{owner-slug}/{model-slug})
3. Poll the task status (POST /Task/Detail)
4. Print the final output

What is MCP?

Model Context Protocol (MCP) is an open standard that lets AI assistants use external tools directly. With the Wiro MCP server, your AI assistant can search models, run inference, track tasks, and upload files — all without leaving your editor.

The hosted MCP server is available at mcp.wiro.ai/v1 and works with any MCP-compatible client, including Cursor, Claude Code, Claude Desktop, and Windsurf. Every request uses your own API key — nothing is stored on the server.

You need a Wiro API key to use the MCP server. If you don't have one yet, create a project here.

Links

• Model Context Protocol (MCP) — open standard specification
• GitHub: wiroai/Wiro-MCP — source code & self-hosting instructions
• npm: @wiro-ai/wiro-mcp — npm package
• Wiro Model Catalog — browse all available models
• Create API Key — get started in seconds

Setup

Connect your AI assistant to Wiro's MCP server. Pick your client:

Cursor MCP settings JSON config Claude Code One command setup Claude Desktop JSON config setup Windsurf MCP settings config Other Clients Any MCP-compatible tool

Cursor

1. Open MCP Settings — Use Cmd+Shift+P (Ctrl+Shift+P on Windows) and search for "Open MCP settings".
2. Add the Wiro server — Add the following to your mcp.json file:

   Signature Auth (if your project uses signature-based authentication):

   {
     "mcpServers": {
       "wiro": {
         "url": "https://mcp.wiro.ai/v1",
         "headers": {
           "Authorization": "Bearer YOUR_API_KEY:YOUR_API_SECRET"
         }
       }
     }
   }

   API Key Only Auth (if your project uses API Key Only authentication):

   {
     "mcpServers": {
       "wiro": {
         "url": "https://mcp.wiro.ai/v1",
         "headers": {
           "Authorization": "Bearer YOUR_API_KEY"
         }
       }
     }
   }

3. Restart Cursor — Save the file and restart Cursor to activate the connection.

Claude Code

Run this command in your terminal:

claude mcp add --transport http wiro \
  https://mcp.wiro.ai/v1 \
  --header "Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET"

That's it. Claude Code will now have access to all Wiro tools.

Claude Desktop

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "wiro": {
      "url": "https://mcp.wiro.ai/v1",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY:YOUR_API_SECRET"
      }
    }
  }
}

Windsurf

Open Settings → MCP and add a new server:

{
  "mcpServers": {
    "wiro": {
      "serverUrl": "https://mcp.wiro.ai/v1",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY:YOUR_API_SECRET"
      }
    }
  }
}

Other MCP Clients

The Wiro MCP server uses the Streamable HTTP transport at:

https://mcp.wiro.ai/v1

Authentication is via the Authorization header:

Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET

Or for API Key Only auth: Bearer YOUR_API_KEY

Credentials are sent as plain text — no base64 encoding needed. Any MCP client that supports Streamable HTTP transport can connect.

Authentication

The MCP server supports both Wiro authentication types. Your project's auth type determines what credentials you provide.

Signature-Based (Recommended)

More secure. Requires both API key and API secret. Pass them as plain text separated by a colon:

Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET

API Key Only

Simpler. Only requires the API key:

Authorization: Bearer YOUR_API_KEY

No base64 encoding needed. Credentials are sent per-request and are never stored. The server is fully stateless.

Available Tools

The MCP server exposes 11 tools organized in four categories. Your AI assistant picks the right tool automatically.

Model slugs: Use the clean/lowercase format owner/model (e.g. openai/sora-2, wiro/virtual-try-on). These correspond to the cleanslugowner/cleanslugproject values returned by search_models.

Discovery

Execution

Task Management

Utility

Examples

Generate an image

"Generate a photorealistic image of a mountain lake at golden hour"

The assistant will use search_models → get_model_schema → run_model and return the image URL.

Generate a video

"Create a 5-second cinematic video of a drone shot over mountains using Kling V3"

The assistant will use get_model_schema → run_model (wait=false) → get_task to poll for the result.

Find models

"What models are available for text-to-video?"

The assistant will call search_models with categories filter.

How It Works

The MCP server is stateless. Each request is fully isolated:

1. Your AI assistant sends a request to mcp.wiro.ai/v1 with your credentials
2. The server calls the Wiro API on your behalf
3. Results are returned to your assistant

All tools are dynamic — they fetch model data at runtime. New models are instantly available via MCP.

Tool Reference

search_models

Search Wiro's model catalog by keyword, category, owner, or any combination. Calls POST /Tool/List on the Wiro API.

Returns a list of models with their cleanslugowner/cleanslugproject (the slug you pass to other tools), title, description, categories, and pricing.

get_model_schema

Get the full parameter schema for a specific model. Calls POST /Tool/Detail on the Wiro API.

Returns the model's parameter groups, each containing items with id, type (text, textarea, select, range, fileinput, etc.), label, required, options, default, and note. Also includes pricing information. Use these to construct the params object for run_model.

recommend_model

Describe what you want to create and get model recommendations ranked by relevance. Calls POST /Tool/List on the Wiro API with relevance sorting.

Returns a list of recommended models with slugs, descriptions, categories, and pricing — sorted by relevance to your task.

explore

Browse curated AI models on Wiro, organized by category. Calls POST /Tool/Explore on the Wiro API. No parameters required.

Returns models grouped into curated sections like "Recently Added", "Image Generation", "Video", etc. Each model includes its slug, description, categories, and rating. Use this to discover what's available without searching.

run_model

Run any AI model on Wiro. Calls POST /Run/{owner}/{model} on the Wiro API.

When wait=true, returns the final task result including pexit (exit code, "0" = success), outputs (CDN URLs for generated files), and debugoutput (LLM text responses).

When wait=false, returns taskid and tasktoken — use get_task to check progress.

get_task

Check task status and get results. Calls POST /Task/Detail on the Wiro API.

Returns the task's current status, pexit (process exit code), outputs (file URLs), debugoutput (LLM responses), elapsedseconds, and totalcost.

Determining success: Check pexit — "0" means success, any other value means failure. For LLM models, the response text is in debugoutput, not outputs. See Tasks for the full task lifecycle.

get_task_price

Get the cost of a completed task. Calls POST /Task/Detail on the Wiro API and returns billing information.

Returns the task's billing status, total cost, and duration. Only successful tasks (pexit: "0") are billed — failed tasks show $0 with a clear explanation that they were not charged.

cancel_task

Cancel a task that is still queued (before worker assignment). Calls POST /Task/Cancel on the Wiro API.

Tasks that have already been assigned to a worker cannot be cancelled — use kill_task instead.

kill_task

Kill a task that is currently running (after worker assignment). Calls POST /Task/Kill on the Wiro API.

The worker will stop processing and the task will move to task_cancel status.

upload_file

Upload a file from a URL to Wiro for use as model input. Downloads the file and uploads it via POST /File/Upload.

Returns the uploaded file's Wiro URL, which can be passed to any model parameter that accepts a file.

search_docs

Search the Wiro documentation for guides, API references, and code examples.

Returns relevant documentation sections matching your query.

FAQ

What models can I use?

All models in the Wiro catalog.

Is my API key stored?

No. The server is fully stateless. Credentials are sent per-request and never stored.

Does it cost extra?

No. The MCP server is free. You pay for model runs at standard pricing.

Can I self-host?

Yes. See Self-Hosted MCP for instructions.

Quick Start

Add to your AI assistant's MCP config:

{
  "mcpServers": {
    "wiro": {
      "command": "npx",
      "args": ["-y", "@wiro-ai/wiro-mcp"],
      "env": {
        "WIRO_API_KEY": "your-api-key",
        "WIRO_API_SECRET": "your-api-secret"
      }
    }
  }
}

That's it. Your assistant now has access to all 70+ Wiro AI models.

Setup

Add the self-hosted MCP server to your AI assistant:

Cursor MCP settings JSON config Claude Code One command setup Claude Desktop JSON config setup Windsurf MCP settings config Other Clients Any MCP-compatible tool

Cursor

Open MCP settings (Cmd+Shift+P → "Open MCP settings") and add the config above.

Claude Code

claude mcp add wiro -- npx -y @wiro-ai/wiro-mcp

Then set WIRO_API_KEY and WIRO_API_SECRET environment variables.

Claude Desktop

Add to claude_desktop_config.json using the Quick Start config above.

Windsurf

Add to your MCP settings using the Quick Start config above.

Other Clients

Any MCP client that supports the stdio transport can run the self-hosted server. Use the Quick Start config with your client's MCP configuration format. The command is npx -y @wiro-ai/wiro-mcp with WIRO_API_KEY and WIRO_API_SECRET as environment variables.

Authentication

Signature-Based (Recommended)

Provide both API key and secret:

WIRO_API_KEY=your-api-key
WIRO_API_SECRET=your-api-secret

API Key Only

Omit WIRO_API_SECRET:

WIRO_API_KEY=your-api-key

Available Tools

The self-hosted server provides the same 11 tools as the hosted MCP server. Your AI assistant picks the right tool automatically.

Model slugs: Use the clean/lowercase format owner/model (e.g. openai/sora-2, wiro/virtual-try-on). These correspond to cleanslugowner/cleanslugproject values returned by search_models.

Discovery

Execution

Task Management

Utility

See the Wiro MCP Server page for detailed parameter tables and examples.

Environment Variables

GitHub & npm

• GitHub: github.com/wiroai/Wiro-MCP
• npm: @wiro-ai/wiro-mcp

Using as a Library

import { createMcpServer, WiroClient } from '@wiro-ai/wiro-mcp';

const client = new WiroClient('your-api-key', 'your-api-secret');
const server = createMcpServer(client);

Self-Hosting on Your Server

git clone https://github.com/wiroai/Wiro-MCP.git
cd Wiro-MCP
npm install
npm run build
export WIRO_API_KEY="your-api-key"
export WIRO_API_SECRET="your-api-secret"
node dist/index.js

Requires Node.js 18 or later. Create a project to get API keys.

Overview

n8n is a powerful workflow automation platform. The Wiro AI community node gives you access to all Wiro AI models as individual nodes you can drag and drop into any workflow.

Each model is a separate node — so you get dedicated parameters, descriptions, and output handling for every model without any configuration hassle.

Links

• npm: @wiro-ai/n8n-nodes-wiroai
• GitHub: wiroai/n8n-nodes-wiroai
• n8n Community Nodes Installation Guide
• Wiro Model Catalog — browse all available models

Available Model Categories

Installation

Install the community node package in your n8n instance:

Via n8n UI (Recommended)

1. Open your n8n instance Navigate to your self-hosted or cloud n8n dashboard
2. Go to Settings Open Settings → Community Nodes
3. Install the node Click Install a community node and enter: @wiro-ai/n8n-nodes-wiroai
4. Confirm Click Install and wait for completion

Via Command Line

npm install @wiro-ai/n8n-nodes-wiroai

Restart n8n after installation.

Authentication

The node supports both Wiro authentication methods:

1. Add credentials Go to Credentials → Add new → Wiro API in n8n
2. Select auth method Signature-Based — enter API key + secret (recommended)  |  API Key Only — enter API key only
3. Save Click Save to store your credentials

Get your credentials at wiro.ai/panel/project.

Usage

Each Wiro model appears as a separate node in the n8n node picker. Search for "Wiro" or the model name to find it.

Example: Generate a Video with Sora 2

1. Add the Wiro - Sora 2 Pro node to your workflow
2. Connect your Wiro credentials
3. Set the parameters:
   • Prompt: A cat astronaut floating in space
   • Seconds: 8
   • Resolution: 1080p
4. Run the workflow

The node returns the task result with output URLs:

{
  "taskid": "abc123",
  "status": "completed",
  "url": "https://cdn1.wiro.ai/xyz/0.mp4"
}

Example: Transcribe Audio with Whisper

1. Add the Wiro - Whisper Large 3 node
2. Connect an audio file from a previous node or provide a URL
3. Select language and output format
4. Run — get the transcribed text

Example: LLM Chat with GPT-5

1. Add the Wiro - GPT-5 node
2. Set your prompt and system instructions
3. Run — get the AI response

Compatibility