Developer Documentation

Everything you need to integrate AI services into your application.

Full API Reference

Quick Start

1

Create an account

Register for a free account to get your API credentials.

$ curl -X POST https://api.ai.hudsonly.com/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Your Name",
    "email": "you@example.com",
    "password": "your-password",
    "password_confirmation": "your-password"
  }'
2

Get your API token

Create a named API token for your application.

$ curl -X POST https://api.ai.hudsonly.com/api/v1/auth/tokens \
  -H "Authorization: Bearer YOUR_LOGIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "my-app" }'

Save the returned token — it won't be shown again.

3

Make your first API call

Call any AI service with your API token.

$ curl -X POST https://api.ai.hudsonly.com/api/v1/services/tts \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello from Hudsonly AI!",
    "voice": "af_heart",
    "format": "mp3"
  }'
4

Get your result

Sync services return results immediately. Async services return a task ID — poll or use webhooks.

// Sync response (TTS)
{
  "success": true,
  "data": {
    "audio_url": "https://...",
    "duration_seconds": 2.4,
    "voice": "af_heart",
    "format": "mp3"
  }
}

// Async response (Avatar)
{
  "task_id": "9f1a2b3c-...",
  "status": "pending",
  "poll_url": "/api/v1/tasks/9f1a2b3c-..."
}

Authentication

All API requests require a Bearer token in the Authorization header.

Authorization: Bearer YOUR_API_TOKEN

Token management

  • • Create tokens via POST /api/v1/auth/tokens or from the API Keys dashboard
  • • Tokens are shown once on creation — store them securely
  • • Revoke tokens anytime via DELETE /api/v1/auth/tokens/{id}
  • • Unauthenticated requests return 401

Official SDKs

Install an SDK to start building with Hudsonly AI in your preferred language. All SDKs handle authentication, file uploads, error handling, and async task polling.

Python

$ pip install hudsonly-ai
from hudsonly import HudsonlyAI

client = HudsonlyAI(api_key="your-token")

result = client.tts.generate(
    text="Hello, world!",
    voice="af_heart",
)
print(result.audio_url)
PyPI Source

Node.js / TypeScript

$ npm install @hudsonly/ai
import HudsonlyAI from '@hudsonly/ai';

const client = new HudsonlyAI({
  apiKey: 'your-token',
});

const result = await client.tts.generate({
  text: 'Hello, world!',
  voice: 'af_heart',
});
console.log(result.audioUrl);
npm Source

PHP

$ composer require hudsonly/ai
use Hudsonly\HudsonlyAI;

$client = new HudsonlyAI('your-token');

$result = $client->tts()->generate([
    'text' => 'Hello, world!',
    'voice' => 'af_heart',
]);
echo $result->audioUrl;
Packagist Source

Laravel

$ composer require hudsonly/laravel
// .env
HUDSONLY_API_KEY=your-token

// Usage
use Hudsonly\Laravel\Facades\Hudsonly;

$result = Hudsonly::tts()->generate([
    'text' => 'Hello, world!',
    'voice' => 'af_heart',
]);
echo $result->audioUrl;
Packagist Source

Code Examples

Use the SDKs or raw HTTP calls to access any service.

cURL 
curl -X POST https://api.ai.hudsonly.com/api/v1/services/tts \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello, world!",
    "voice": "af_heart",
    "format": "mp3",
    "speed": 1.0
  }'
Python SDK 
from hudsonly import HudsonlyAI

client = HudsonlyAI(api_key="your-token")

# Text to Speech
tts = client.tts.generate(text="Hello, world!", voice="af_heart")
print(tts.audio_url)

# Speech to Text
transcript = client.transcription.generate(audio="recording.mp3")
print(transcript.text)

# Embeddings
embeddings = client.embeddings.generate(texts=["Hello", "World"])

# Avatar (auto-polls until complete)
avatar = client.avatar.generate(image="photo.jpg", audio="speech.mp3")
print(avatar.video_url)
Node.js SDK 
import HudsonlyAI from '@hudsonly/ai';

const client = new HudsonlyAI({ apiKey: 'your-token' });

// Text to Speech
const tts = await client.tts.generate({ text: 'Hello, world!' });
console.log(tts.audioUrl);

// Speech to Text
const transcript = await client.transcription.generate({
  audio: './recording.mp3',
});
console.log(transcript.text);

// Embeddings
const embeddings = await client.embeddings.generate({
  texts: ['Hello', 'World'],
});

// Avatar (auto-polls until complete)
const avatar = await client.avatar.generate({
  image: './photo.jpg',
  audio: './speech.mp3',
});
console.log(avatar.videoUrl);
PHP / Laravel SDK 
// Plain PHP
use Hudsonly\HudsonlyAI;

$client = new HudsonlyAI('your-token');
$result = $client->tts()->generate(['text' => 'Hello!']);

// Laravel (via Facade)
use Hudsonly\Laravel\Facades\Hudsonly;

// Text to Speech
$tts = Hudsonly::tts()->generate(['text' => 'Hello, world!']);
echo $tts->audioUrl;

// Speech to Text
$transcript = Hudsonly::transcription()->generate([
    'audio' => storage_path('app/recording.mp3'),
]);

// Embeddings
$embeddings = Hudsonly::embeddings()->generate([
    'texts' => ['Hello', 'World'],
]);

// Avatar (auto-polls until complete)
$avatar = Hudsonly::avatar()->generate([
    'image' => storage_path('app/photo.jpg'),
    'audio' => storage_path('app/speech.mp3'),
]);

Service Reference

Text to Speech

Sync 1 credit

POST /api/v1/services/tts

Convert text to natural-sounding speech audio.

Parameters

Param Type Required Description
text string Yes Text to convert (max 5000 chars)
voice string No Voice ID (default: af_heart). 54 voices available.
format string No Output format: mp3 or wav (default: mp3)
speed number No Speech speed 0.5–2.0 (default: 1.0)

Speech to Text

Sync 1 credit

POST /api/v1/services/transcription

Transcribe audio to text using Whisper. Supports multiple languages with automatic detection and timestamps.

Parameters

Param Type Required Description
audio file Yes* Audio file upload (MP3, WAV, M4A, OGG, FLAC, WebM, MP4, max 25MB)
audio_url string Yes* URL to audio file
language string No ISO language code hint (e.g. en, fr, es). Auto-detected if omitted.
model string No Model size: tiny, base, small, or medium (default: base)

* Provide either audio (file upload) or audio_url, not both.

Response

{
  "success": true,
  "data": {
    "text": "Hello, this is a transcription test.",
    "language": "en",
    "language_probability": 0.98,
    "duration_seconds": 3.5,
    "segments": [
      { "start": 0.0, "end": 3.5, "text": "Hello, this is a transcription test." }
    ],
    "model": "base",
    "generation_time_seconds": 1.2
  }
}

Text Embeddings

Sync 1 credit

POST /api/v1/services/embeddings

Generate high-quality 1024-dimension vector embeddings for text. Supports up to 100 texts per request across multiple languages.

Parameters

Param Type Required Description
texts array Yes Array of strings to embed (max 100 items, each max 8192 chars)

Avatar Video Generation

Async 10 credits

POST /api/v1/services/avatar

Generate a talking-head video from a portrait image and audio. Returns a task ID for polling.

Parameters

Param Type Required Description
image_url string Yes* URL to portrait image (or upload as file)
audio_url string Yes* URL to audio file (or upload as file)
image file Yes* Portrait image upload (multipart/form-data)
audio file Yes* Audio file upload (multipart/form-data)
webhook_url string No HTTPS URL to receive result when complete

* Provide either URLs (image_url + audio_url) or file uploads (image + audio), not both.

Async flow

  1. Submit request → receive 202 with task_id
  2. Poll GET /api/v1/tasks/{task_id} for status
  3. When status is completed, the output contains the video URL
  4. Or use webhook_url to get notified automatically

Full API Reference

Explore every endpoint, parameter, and response schema in the interactive API documentation.

Open API Reference