Generate images, video, speech, music, 3D and LLM output with Wiro AI models through the Wiro MCP server or REST API, including finding a model, checking its price, running it and collecting the result. Use when the user wants generative media or LLM calls through an API, or mentions Wiro, wiro.ai or a Wiro API key.
Wiro AI
Wiro runs AI models for images, video, audio and speech, LLMs, 3D and more through one API. Each run creates a task. A task is billed to the project's prepaid wallet only if it succeeds.
Choose a route
- You are making something for the user now and Wiro MCP tools are available (
search_models,get_model_schema,run_modeland others): use them, they call the API below for you. Callget_accountfirst to check the connection and the balance, and readget_playbook(topics such asmodels,workflows,agents,billing) before a multi-step job. - You are writing application code, or there are no MCP tools: use the REST API at
https://api.wiro.ai/v1. The HTTP endpoints in steps 1 to 4 are all POST. - Chat or LLM calls from code that uses an OpenAI or Anthropic SDK: use the LLM gateway (see LLMs).
Connecting the MCP server, if the user wants it:
- Hosted:
https://mcp.wiro.ai/v1(Streamable HTTP). The user signs in with the browser, or the client sendsAuthorization: Bearer YOUR_API_KEY(API Key Only project) orBearer YOUR_API_KEY:YOUR_API_SECRET(Signature project). Claude Code:claude mcp add --transport http wiro https://mcp.wiro.ai/v1, then/mcpto sign in. If the Wiro plugin (wiroai/Wiro-Plugin) is installed, the server is already there: open/mcp, pick it and choose Authenticate. - Local:
npx -y @wiro-ai/wiro-mcp(stdio, Node.js 20+) withWIRO_API_KEY, plusWIRO_API_SECRETfor a Signature project, in the server's environment. - MCP names models
owner/modelin lowercase.run_modeltakesmodelandparams(the fields fromget_model_schema).
Credentials
- Read them from environment variables:
WIRO_API_KEY, plusWIRO_API_SECRETfor a Signature project. Never print, log or echo them. Never hard-code or commit them (keep.envfiles out of git). Never put them in browser or mobile app code: call Wiro from a server. - If they are missing, ask the user to create a project at https://wiro.ai/panel/project/new and set the variables themselves. Do not ask them to paste a key into the chat.
- The project's auth method decides the headers:
- API Key Only:
x-api-key. - Signature:
x-api-key,x-nonce(a Unix timestamp or random integer) andx-signature, the hex HMAC-SHA256 ofAPI_SECRET + NONCEkeyed withAPI_KEY. Sign every request: compute the pair right before each call.
- API Key Only:
NONCE=$(date +%s)
SIGNATURE=$(printf '%s' "${WIRO_API_SECRET}${NONCE}" \
| openssl dgst -sha256 -hmac "${WIRO_API_KEY}" | awk '{print $NF}')
# add to the curl call: -H "x-nonce: ${NONCE}" -H "x-signature: ${SIGNATURE}"
- The LLM gateway and the hosted MCP server do not take the nonce and signature. They take
Authorization: Bearer YOUR_API_KEY, orBearer YOUR_API_KEY:YOUR_API_SECRETfor a Signature project. - An auth error means the signature headers are missing, or the key and secret do not belong to the same project.
The examples below use API Key Only. For a Signature project, add the two headers.
1. Find a model
curl -s -X POST "https://api.wiro.ai/v1/Tool/List" \
-H "Content-Type: application/json" -H "x-api-key: ${WIRO_API_KEY}" \
-d '{"search": "flux", "limit": "20", "summary": true, "hideworkflows": true}'
- Other filters:
categories(such as["text-to-video"]),slugowner, andstartfor paging. Or browse https://wiro.ai/models. cleanslugownerandcleanslugprojectin each result are the{owner-slug}/{model-slug}you run.- Read the model before running it:
curl -s -X POST "https://api.wiro.ai/v1/Tool/Detail" \
-H "Content-Type: application/json" -H "x-api-key: ${WIRO_API_KEY}" \
-d '{"slugowner": "OWNER_SLUG", "slugproject": "MODEL_SLUG"}'
tool[0].parameters[].items[]lists the inputs:id(the field name to send),typeandrequired, plus allowed options and defaults where the model sets them. Build the request from these ids.
2. Work out the cost
dynamicprice(in Tool/List and Tool/Detail) is an array of{inputs, price, priceMethod}, withpricein USD. Use the entry whoseinputsmatch the settings you will send;{}means one price for every setting. Parse it first if it arrives as a string.priceMethod:cprper run,cpoper output file,cpsper second of run time,cptper token,cp-pixelper 1024x1024 tier of output,cp-audiosecondslengthper second of input audio,cp-promptlengthper prompt character,cp-outputVideoLengthper second of output video,cp-realtimeturnper realtime turn,cp-readoutputreported by the model when it ends.- No
dynamicprice: the model bills per second, andapproximatelycost(from its average run time) is a rough estimate. - Only successful runs (
pexit: "0") are billed. Failed runs, server errors, queue time and tasks cancelled before processing completes are not. - Prices are also listed at https://wiro.ai/product/pricing.
3. Run the model
curl -s -X POST "https://api.wiro.ai/v1/Run/{owner-slug}/{model-slug}" \
-H "Content-Type: application/json" -H "x-api-key: ${WIRO_API_KEY}" \
-d '{"prompt": "A futuristic city at sunset"}'
# {"result": true, "errors": [], "taskid": "...", "socketaccesstoken": "..."}
- Keep
taskidandsocketaccesstoken(the task token) right away. They are how you find the task again. - Models without file inputs take JSON. Models with file inputs take
multipart/form-data, for example-F "inputImage=@photo.jpg" -F "scale=4". - Files by URL: a
fileinputtakes it in{id}Url(inputImageUrl), and in multipart you send both fields with one left empty. Amultifileinputtakes comma-separated URLs in the field withUrlbeforeMultiple(inputDocumentUrlMultiple). Acombinefileinputtakes URLs in the field itself. URLs must be public http(s), redirects included. - To reuse a local file across runs, upload it once with
POST /File/Upload(multipart fieldfile, up to 100 MB) and pass the returnedurl. - An optional
callbackUrlgets a webhook when the task ends (see below).
4. Get the result
Poll Task/Detail with the task token or the task id:
curl -s -X POST "https://api.wiro.ai/v1/Task/Detail" \
-H "Content-Type: application/json" -H "x-api-key: ${WIRO_API_KEY}" \
-d '{"tasktoken": "TASK_TOKEN"}' # or -d '{"taskid": "TASK_ID"}'
- Read
tasklist[0]. Check every 3 seconds or so, less often for long jobs, untilstatusistask_postprocess_endortask_cancel. Nothing else ends a task. - Statuses run
task_queue,task_accept,task_preprocess_start,task_preprocess_end,task_assign,task_start,task_output(repeats),task_output_full,task_end,task_postprocess_start,task_postprocess_end.task_erroris not terminal, andtask_endcomes before the outputs are ready. - Failed runs also reach
task_postprocess_end:pexit: "0"means success, anything else is a failure (and not billed). - Files are in
outputs[].url(withnameandcontenttype). LLM text is indebugoutput, or ordered inoutputs[0].content.segments. The charge istotalcost, in USD.
WebSocket: connect to wss://socket.wiro.ai/v1, send {"type": "task_info", "tasktoken": "TASK_TOKEN"} and read events until task_postprocess_end. Its success and exitCode (0 = success) give the outcome, and message holds the outputs. Realtime voice, text-to-speech and speech-to-text models also work over this socket: see https://wiro.ai/docs/websocket.
Webhook: with callbackUrl, Wiro POSTs the task as JSON when it ends, success or failure, so check pexit. Answer with a 2xx at once. It tries up to 3 times, 2 seconds apart, and does not follow redirects. Match the task id against your own records before you act on the payload. Webhooks go to public URLs; on a local machine, poll instead.
Sync: POST /Run/{owner-slug}/{model-slug}/sync starts the same billed task and holds the request for up to 40 minutes, then returns Task Detail JSON (check tasklist[0].pexit). Add ?stream=true for SSE events. A timeout returns HTTP 504 with taskid and socketaccesstoken, and the task keeps running. Training and realtime models use the other routes, not /sync.
Money rules
- Before any paid run, tell the user the model, the settings and the expected cost in one line.
- Ask first for large, batch or open-ended jobs (many outputs, long videos, loops), and for any paid run the user did not ask for, retries included.
- After a timeout, a 504 or a dropped connection, never send the same Run again on your own. The task may still be running, and a second Run is a second billed job. Look it up first with Task/Detail (MCP:
wait_for_task,get_task,list_tasks). With no task id at all, check MCPlist_tasksorget_accountwithrecent_transactions, or ask the user to check their usage at https://wiro.ai/panel/billing, before you resend. - MCP:
run_modelwaits up to 45 seconds by default, then returns the running task with anextAction(usuallywait_for_task). Call that. Never callrun_modelagain for the same job. - Stop a task only when the user asks:
POST /Task/Cancelwith{"taskid": "TASK_ID"}while it is queued,POST /Task/Killwith{"taskid": "TASK_ID"}or{"socketaccesstoken": "TASK_TOKEN"}once it is running. It ends astask_cancel. MCP:cancel_task,kill_task. - The project behind the key decides which wallet pays, personal or team. Only the user adds funds, in the dashboard at https://wiro.ai/panel/billing; no MCP tool adds funds.
LLMs
- LLMs in the catalog run through Run like other models, with the reply in
debugoutputandoutputs[0].content. A chat model keeps context when you send the samesession_idon every turn, if its parameters listsession_id. - For OpenAI-style code, use the gateway at base URL
https://llm.wiro.ai/v1:POST /chat/completionsandPOST /responses. Anthropic SDKs use the originhttps://llm.wiro.ai(/v1/messages). - Auth:
Authorization: Bearer YOUR_API_KEYfor API Key Only,Bearer YOUR_API_KEY:YOUR_API_SECRETfor Signature. - Model ids are lowercase
owner/model.GET /v1/modelslists the gateway models; checkcapabilities.endpointsandsupported_parametersbefore you rely on a feature. LLMs missing from that list still run through Run. - Send the conversation history in
messageson every request. Output is text only; make images, video and audio through Run. max_completion_tokensalso covers reasoning tokens, so keep it at 512 or more.- The billed amount is in
usage.cost.
curl -s -X POST "https://llm.wiro.ai/v1/chat/completions" \
-H "Authorization: Bearer ${WIRO_API_KEY}" -H "Content-Type: application/json" \
-d '{"model": "owner/model", "max_completion_tokens": 512,
"messages": [{"role": "user", "content": "What is SSE?"}]}'
import OpenAI from "openai";
const { WIRO_API_KEY, WIRO_API_SECRET } = process.env;
const client = new OpenAI({
baseURL: "https://llm.wiro.ai/v1",
apiKey: WIRO_API_SECRET ? `${WIRO_API_KEY}:${WIRO_API_SECRET}` : WIRO_API_KEY,
});
const completion = await client.chat.completions.create({
model: "owner/model", // an id from GET /v1/models
max_completion_tokens: 512,
messages: [{ role: "user", content: "Hello" }],
});
console.log(completion.choices[0].message.content);
Workflows
A workflow is a saved chain of model steps and built-in utility steps, with its own inputs and outputs. Start one with POST /Workflow/Run (slug is its full slug, input the input values); it returns a workflowtoken. Poll POST /Workflow/RunDetail with that token until status is completed, failed, stopped or cancelled. Each model step is billed like a normal run when it succeeds, and utility steps are not billed. The wallet must hold 0.50 USD per model step to start, and the expected cost is the sum of the step models' prices. A failed run can be resumed without paying again for finished steps. MCP: list_workflows, run_workflow, wait_for_workflow_run, resume_workflow_run. See https://wiro.ai/docs/workflows.
Hosted agents
Wiro Agents are assistants that keep running on Wiro: they keep conversation memory, connect to outside services and use tools. You deploy one from a template (browse https://wiro.ai/agents) or build one from skills. Each agent runs on one of three monthly plans (Starter, Pro or Max) with a pool of credits, and every turn uses credits by the tokens its model consumes. Deploying through the API takes the plan price from the wallet at once, so quote it and get a clear yes first. MCP: list_agent_templates, deploy_agent (quotes first, and charges only when called again with confirm: true), send_agent_message. See https://wiro.ai/docs/agent-overview.
Errors and limits
Check result first, then errors[].code. Do not rely on the HTTP status alone.
| Code | Meaning | What to do |
|---|---|---|
0 | Validation, missing parameter or server error | Fix the request; retry a server error with backoff |
1 | Model or task not found or not accessible | Check the slug, task id or token |
96 | Concurrency limit reached | No task was created and nothing was charged; retry after 2, 4, 8 s (up to 60 s, at most 8 tries) or queue |
97 | Insufficient balance | The user adds funds; a run needs at least 0.50 USD (10 USD for training models) |
98 | The model needs a signed-in account | Use authenticated credentials |
99 | Bearer token missing, invalid or expired | Check the credentials |
- How many tasks can run at once depends on the wallet balance: see https://wiro.ai/docs/concurrency-limits. A task counts from
task_queueuntiltask_postprocess_endortask_cancel, and tasks started on the website, by agents or by workflows count too. - On HTTP 429, back off and retry. The LLM gateway sends
retry-after.
Links
- Docs: https://wiro.ai/docs/introduction
- Authentication: https://wiro.ai/docs/authentication
- Run a model: https://wiro.ai/docs/run-a-model
- Tasks: https://wiro.ai/docs/tasks
- Model parameters: https://wiro.ai/docs/model-parameters
- Pricing docs: https://wiro.ai/docs/pricing
- Errors: https://wiro.ai/docs/error-reference
- LLM gateway: https://wiro.ai/docs/completions-api
- MCP server: https://wiro.ai/docs/wiro-mcp-server
- Models catalog: https://wiro.ai/models
- Pricing page: https://wiro.ai/product/pricing
- New project and API key: https://wiro.ai/panel/project/new
- Balance, credits and usage: https://wiro.ai/panel/billing
- Downloads
- 183All time
- Security audit
- Review
- Last updated
- 1w ago
- Current version
- v1.0.2
- License
- MIT-0
