SDK Reference

pip install wayforth-sdk

from wayforth import Wayforth

client = Wayforth(api_key="wf_live_...")

results = client.search("translate to spanish")
print(results[0]["name"])  # DeepL Translation

result = client.execute("deepl", text="Hello", target_lang="ES")
print(result["translation"])  # Hola

result = client.run("translate Hello to Spanish")
print(result["output"])  # Hola

results = client.search(
    "image classification",
    tier=2,
    max_price_usd=0.01,
    region="eu-west",
    limit=5
)
for svc in results:
    print(svc["slug"], svc["wri_score"])

results = client.query(
    "category:vision AND tier:>=3 SORT BY wri_score DESC LIMIT 5"
)

# Translation
result = client.execute("deepl", text="Bonjour", target_lang="EN")

# Embeddings
result = client.execute(
    "openai-embeddings",
    input="The quick brown fox",
    model="text-embedding-3-large"
)
print(len(result["embedding"]))  # 3072

# Transcription
result = client.execute(
    "whisper-large",
    audio_url="https://example.com/recording.mp3",
    language="en"
)

result = client.run(
    "transcribe this audio to English",
    audio_url="https://example.com/clip.mp3"
)
print(result["output"])   # "Hello, this is a test recording"
print(result["service"])  # "whisper-large"

info = client.balance()
print(info["credits_remaining"])  # 847
print(info["tier"])               # "builder"
print(info["forecast"]["will_exhaust_before_reset"])  # False

all_services = client.services()
audio_services = client.services(category="audio")
for svc in audio_services:
    print(f"{svc['slug']:20} WRI {svc['wri_score']}")

with Wayforth(api_key="wf_live_...") as client:
    results = client.search("translate to french")
    # Connection pool closed automatically on exit

import asyncio
from wayforth import AsyncWayforth

async def main():
    async with AsyncWayforth(api_key="wf_live_...") as client:
        # Run searches concurrently
        search, balance = await asyncio.gather(
            client.search("translate to spanish"),
            client.balance(),
        )
        print(search[0]["name"])
        print(balance["credits_remaining"])

        # Execute
        result = await client.execute("deepl", text="Hello", target_lang="ES")
        print(result["translation"])

asyncio.run(main())

import asyncio
from wayforth import AsyncWayforth

async def batch_translate(texts: list[str], target_lang: str) -> list[str]:
    async with AsyncWayforth(api_key="wf_live_...") as client:
        tasks = [
            client.execute("deepl", text=t, target_lang=target_lang)
            for t in texts
        ]
        results = await asyncio.gather(*tasks)
        return [r["translation"] for r in results]

translated = asyncio.run(batch_translate(
    ["Hello", "Good morning", "Goodbye"],
    target_lang="ES"
))
# ["Hola", "Buenos días", "Adiós"]

from wayforth import (
    WayforthError,
    AuthenticationError,        # 401
    InsufficientCreditsError,   # 402
    ServiceUnavailableError,    # 5xx after 3 retries
)

try:
    result = client.execute("deepl", text="Hello", target_lang="ES")
except AuthenticationError:
    print("Invalid API key — check WAYFORTH_API_KEY")
except InsufficientCreditsError:
    print("Out of credits — top up at https://wayforth.io/billing")
except ServiceUnavailableError as e:
    print(f"Service down after retries: {e}")
except WayforthError as e:
    print(f"API error {e.status_code}: {e}")

npm install @wayforth/sdk

import { Wayforth } from '@wayforth/sdk';

const wayforth = new Wayforth({ apiKey: 'wf_live_...' });

const results = await wayforth.search('translate to spanish');
console.log(results[0].name);  // DeepL Translation

const result = await wayforth.execute('deepl', { text: 'Hello', target_lang: 'ES' });
console.log(result.translation);  // Hola

const run = await wayforth.run('translate Hello to Spanish');
console.log(run.output);  // Hola

const results = await wayforth.search('image classification', {
  max_price_usd: 0.01,
  tier: 2,
  region: 'us-east',
  limit: 5,
});
results.forEach(r => console.log(r.slug, r.wri_score));

const results = await wayforth.query(
  'category:nlp AND tier:>=3 SORT BY wri_score DESC'
);

const result = await wayforth.execute('deepl', {
  text: 'Hello, world!',
  target_lang: 'FR',
});
console.log(result.translation);  // Bonjour, le monde!

const result = await wayforth.run('transcribe this audio', {
  audio_url: 'https://example.com/clip.mp3',
});
console.log(result.output);   // "Hello, this is a test..."
console.log(result.service);  // "whisper-large"

const bal = await wayforth.balance();
console.log(bal.credits_remaining);  // 847
console.log(bal.tier);               // "builder"

const all = await wayforth.services();
const audio = await wayforth.services('audio');

import { createWayforth } from '@wayforth/sdk';

const wayforth = createWayforth({
  apiKey: process.env.WAYFORTH_API_KEY!,
  baseUrl: 'https://gateway.wayforth.io',  // optional override
});

interface WayforthConfig {
  apiKey: string;
  baseUrl?: string;
}

interface SearchOptions {
  max_price_usd?: number;
  tier?: number;
  payment_rail?: string;
  region?: string;
  limit?: number;
}

interface SearchResult {
  slug: string;
  name: string;
  description: string;
  wri_score: number;
  tier: number;
  payment_rails: string[];
  category: string;
}

interface ExecuteResult {
  [key: string]: unknown;
}

interface RunResult {
  output: unknown;
  service: string;
}

interface BalanceResult {
  credits_remaining: number;
  tier: string;
  usage: unknown;
}

import {
  Wayforth,
  WayforthError,
  AuthenticationError,
  InsufficientCreditsError,
  ServiceUnavailableError,
} from '@wayforth/sdk';

const wayforth = new Wayforth({ apiKey: process.env.WAYFORTH_API_KEY! });

try {
  const result = await wayforth.execute('deepl', {
    text: 'Hello',
    target_lang: 'ES',
  });
} catch (err) {
  if (err instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (err instanceof InsufficientCreditsError) {
    console.error('Out of credits — visit https://wayforth.io/billing');
  } else if (err instanceof ServiceUnavailableError) {
    console.error(`Service down after retries: ${err.message}`);
  } else if (err instanceof WayforthError) {
    console.error(`API error ${err.statusCode}: ${err.message}`);
  }
}