WebVoice API Documentation

Overview — API forward

WebVoice is an API forward (bridge): your application talks to WebVoice with your account API key; we authenticate you, pick the managed model, call the upstream provider (Groq, DeepSeek, OpenRouter, Gemini, Moonshot, Z.AI, MiniMax, DeepInfra), and debit credits on your profile — same wallet as the web app.

For AI chat you can use the OpenAI-compatible surface: set base_url to the value below and pass your WebVoice key as api_key. Streaming (SSE) and non-streaming completions are supported.

https://webvoice.easytaskflow.app/api/v1/

Integration guide (App & tools) · Sign in to create API keys

Free chat models (0 credits)

These models are routed via OpenRouter with verified :free slugs. Via API they cost 0 credits per request — you can call them even with zero balance. Model ids: openrouter:openrouter/free, openrouter:openai/gpt-oss-20b:free, openrouter:openai/gpt-oss-120b:free, openrouter:google/gemma-4-31b-it:free. Groq-hosted similar models are billed normally.

Rate limits (OpenRouter-aligned, per account): 20 requests/minute; 50/day without credit purchases, 1000/day after at least one purchase. HTTP 429 with Retry-After when exceeded.

All public chat models

Models available for integration (subject to your account tier after sign-in). Use the model id in POST chat/completions/.

Authentication

TTS, STT, Translation, AI Chat, Image generation and Voices endpoints require an API key. You can create API keys from the API Dashboard.

Login with email code (no API key)

For web/mobile login without password: send email to receive a code, then verify the code. Rate limited per IP (no CAPTCHA).

• POST https://webvoice.easytaskflow.app/api/v1/auth/send-code/ — JSON: email, accept_privacy, accept_terms. Response includes is_new_user.
• POST https://webvoice.easytaskflow.app/api/v1/auth/verify-code/ — JSON: email, code, optional create_api_key, api_key_name. Stateless (no session cookie required). Returns api_key, onboarding (Solana memo + wallet).
• GET https://webvoice.easytaskflow.app/api/v1/onboarding/ — Requires API key. Credits, can_use_api, optional Solana memo, PayPal URLs.
• POST https://webvoice.easytaskflow.app/api/v1/keys/ — Requires API key. JSON {"name": "my-agent"} → new wv_… key.

Limits: 5 send-code and 20 verify-code requests per IP per 15 minutes.

# 1 — send code
curl -X POST "https://webvoice.easytaskflow.app/api/v1/auth/send-code/" \\
  -H "Content-Type: application/json" \\
  -d '{"email":"agent@example.com","accept_privacy":true,"accept_terms":true}'

# 2 — verify + get API key (stateless; email in JSON, no session cookie)
curl -X POST "https://webvoice.easytaskflow.app/api/v1/auth/verify-code/" \\
  -H "Content-Type: application/json" \\
  -d '{"email":"agent@example.com","code":"123456","create_api_key":true,"api_key_name":"cursor-agent"}'

# Example onboarding fields in verify response:
# {
#   "api_key": "wv_…",
#   "onboarding": {
#     "credits": 20.0,
#     "can_use_api": true,
#     "billing": { "topup_required": false, "note": "…" },
#     "solana": { "available": true, "wallet": "…", "memo_code": "WV…" }
#   }
# }

Using API Key

Include your API key in one of the following ways:

Header (Recommended)

X-API-Key: wv_your_api_key_here

Or use Authorization: Bearer wv_your_api_key_here. API keys in query strings (?api_key=) are not accepted — they would appear in server logs and browser history.

API Endpoints

Base URL: https://webvoice.easytaskflow.app/api/v1/

Production API endpoint: webvoice.easytaskflow.app

Send Email

Endpoint: POST /api/v1/send-email/

Sends an email from the site to the specified address. Text only, no attachments. Requires API key.

Rate limit: 10 emails per account per 1 hour(s). HTTP 429 with Retry-After when exceeded.

Request Body

{
  "to": "destinatario@example.com",
  "subject": "Oggetto (optional)",
  "body": "Testo dell'email"
}

Parameters

Response

{
  "success": true,
  "message": "Email sent successfully",
  "to": "destinatario@example.com",
  "subject": "Oggetto"
}

Text-to-Speech (TTS)

Endpoint: POST /api/v1/tts/

Request Body

{
  "text": "Hello, world!",
  "voice": "af_sarah",
  "language": "en",
  "speed": 0.90
}

Parameters

Response

{
  "success": true,
  "audio": "base64_encoded_mp3_data",
  "format": "mp3",
  "duration": 2.5,
  "credits_used": 0.5,
  "credits_remaining": 99.5
}

Speech-to-Text (STT)

Endpoint: POST /api/v1/stt/

Request

Send as multipart/form-data:

• audio: Audio file (MP3, WAV, M4A, FLAC)
• language: Optional. Omit or use empty/auto for automatic language detection (Whisper). Or specify code (it, en, es, fr, de, pt, ru, zh, ja, ko, etc.)
• provider: Optional. whisper_small (default from account), whisper_fast (DeepInfra Turbo), whisper_groq (alias), whisper_max_local (Modal). Requires DEEPINFRA_API_KEY for whisper_fast.

Response

The 'language' field returns the auto-detected or specified language code.

{
  "success": true,
  "text": "Transcribed text here",
  "language": "it",
  "duration": 10.5,
  "credits_used": 0.3,
  "credits_remaining": 99.2
}

Translation

Endpoint: POST /api/v1/translation/

Request Body

{
  "text": "Hello, world!",
  "source_language": "en",
  "target_language": "it"
}

Parameters

Supported Languages

The following language codes are supported:

• en - English
• it - Italian
• es - Spanish
• fr - French
• de - German
• pt - Portuguese
• ru - Russian
• zh - Chinese
• ja - Japanese
• ko - Korean
• ar - Arabic
• nl - Dutch
• pl - Polish
• tr - Turkish
• cs - Czech

Response

{
  "success": true,
  "translated_text": "Ciao, mondo!",
  "source_language": "en",
  "target_language": "it",
  "text_length": 13,
  "credits_used": 0.1,
  "credits_remaining": 99.9
}

AI Chat (OpenAI-compatible bridge)

Use WebVoice as a drop-in OpenAI API base URL: authenticate with your WebVoice API key (X-API-Key or Authorization: Bearer), choose a managed model, and credits are billed on your profile. Responses follow the OpenAI chat.completions schema; credit info is in the optional webvoice field.

OpenAI base URL

https://webvoice.easytaskflow.app/api/v1/

Example: POST chat/completions/, GET models/, compatible with OpenAI SDK when you set base_url and api_key.

List models

WebVoice extended: GET /api/v1/chat/models/ — includes credits_per_request and display_name.

OpenAI-compatible: GET /api/v1/models/

{
  "object": "list",
  "data": [
    {
      "id": "deepseek-v4-flash",
      "object": "model",
      "created": 1700000000,
      "owned_by": "deepseek"
    }
  ]
}

Chat completion

Endpoint: POST /api/v1/chat/completions/

Same request body as OpenAI: model, messages, max_tokens, temperature, stream. Set stream: true for Server-Sent Events (text/event-stream).

DeepSeek routes: deepseek-v4-flash (default, fast), deepseek-v4-pro (frontier), deepseek-reasoner (V4 thinking mode). Legacy deepseek-chat still works and maps to V4 Flash.

Request body (JSON)

{
  "model": "deepseek-v4-flash",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Summarize WebVoice in one sentence."}
  ],
  "max_tokens": 2000,
  "temperature": 0.7,
  "stream": false,
  "web_search": false
}

Parameters

Response (non-streaming)

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "deepseek-v4-flash",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "WebVoice is a voice and AI platform for TTS, STT, chat and memos."
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 42,
    "completion_tokens": 18,
    "total_tokens": 60
  },
  "webvoice": {
    "credits_used": 2.0,
    "credits_remaining": 98.0,
    "provider": "deepseek"
  }
}

Response (streaming SSE)

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"total_tokens":60},"webvoice":{"credits_used":2.0,"credits_remaining":98.0}}

data: [DONE]

Example (curl)

# Non-streaming
curl -X POST "https://webvoice.easytaskflow.app/api/v1/chat/completions/" \
  -H "Authorization: Bearer wv_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-flash","messages":[{"role":"user","content":"Hello"}]}'

# Streaming
curl -N -X POST "https://webvoice.easytaskflow.app/api/v1/chat/completions/" \
  -H "X-API-Key: wv_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-flash","stream":true,"messages":[{"role":"user","content":"Hello"}]}'

Example (OpenAI Python SDK)

from openai import OpenAI

client = OpenAI(
    api_key="wv_your_api_key_here",
    base_url="https://webvoice.easytaskflow.app/api/v1",
)

# Non-streaming
r = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "Hello"}],
)
print(r.choices[0].message.content)

# Streaming
stream = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "Hello"}],
    stream=True,
)
for event in stream:
    if event.choices[0].delta.content:
        print(event.choices[0].delta.content, end="")

{
  "model": "deepseek-v4-flash",
  "tool_choice": "auto",
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Get current weather for a city",
      "parameters": {
        "type": "object",
        "properties": {
          "city": {"type": "string", "description": "City name"}
        },
        "required": ["city"]
      }
    }
  }],
  "messages": [
    {"role": "user", "content": "What is the weather in Rome?"}
  ]
}

{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "call_abc123",
        "type": "function",
        "function": {
          "name": "get_weather",
          "arguments": "{\"city\":\"Rome\"}"
        }
      }]
    },
    "finish_reason": "tool_calls"
  }],
  "webvoice": {"credits_used": 2.0, "credits_remaining": 98.0}
}

{
  "model": "deepseek-v4-flash",
  "tools": [ ... same tools ... ],
  "messages": [
    {"role": "user", "content": "What is the weather in Rome?"},
    {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "call_abc123",
        "type": "function",
        "function": {"name": "get_weather", "arguments": "{\"city\":\"Rome\"}"}
      }]
    },
    {
      "role": "tool",
      "tool_call_id": "call_abc123",
      "content": "{\"temp_c\": 22, \"condition\": \"sunny\"}"
    }
  ]
}

messages = [{"role": "user", "content": user_prompt}]
while True:
    resp = client.chat.completions.create(
        model="deepseek-v4-flash",
        messages=messages,
        tools=TOOLS,
        tool_choice="auto",
    )
    msg = resp.choices[0].message
    if resp.choices[0].finish_reason == "tool_calls":
        messages.append(msg.model_dump())
        for tc in msg.tool_calls:
            result = run_function(tc.function.name, json.loads(tc.function.arguments))
            messages.append({
                "role": "tool",
                "tool_call_id": tc.id,
                "content": json.dumps(result),
            })
        continue
    return msg.content

pip install webvoice-mcp
# or from source:
pip install -r requirements-mcp.txt
pip install -e .

{
  "mcpServers": {
    "webvoice": {
      "command": "webvoice-mcp",
      "env": {
        "WEBVOICE_API_KEY": "wv_your_api_key_here"
      }
    }
  }
}

Image generation (text-to-image)

Default provider is MiniMax (MINIMAX_API_KEY). WaveSpeed providers (WAVESPEED_API_KEY): wan, nucleus, gen4, gen4-turbo, sd3, sdxl, flux-klein-lora. DeepInfra (DEEPINFRA_API_KEY): qwen-image-max. Missing key → HTTP 503.

Endpoint: POST /api/v1/image/

Upstream docs: MiniMax · WAN 2.7 · Nucleus · Gen4 · SDXL · FLUX Klein LoRA · Qwen-Image-Max (DeepInfra)

Request body (JSON)

{
  "prompt": "A red bicycle on a sunny street",
  "provider": "minimax",
  "width": 1024,
  "height": 1024,
  "seed": 42,
  "model": "image-01",
  "aspect_ratio": "16:9",
  "response_format": "base64",
  "provider": "nucleus",
  "negative_prompt": "blurry, low quality",
  "num_images": 1,
  "num_inference_steps": 50,
  "guidance_scale": 8,
  "output_format": "png",
  "provider": "gen4",
  "resolution": "1080p",
  "reference_images": ["https://example.com/ref1.jpg"],
  "seed": 42
}

Runway Gen4 Image Turbo example (faster, ~$0.03 upstream):

{
  "provider": "gen4-turbo",
  "prompt": "Character wearing a leather jacket in a cyberpunk city",
  "aspect_ratio": "9:16",
  "resolution": "1080p",
  "reference_images": ["https://example.com/character-ref.jpg"]
}

Stable Diffusion 3 example (~$0.03 upstream, optional img2img):

{
  "provider": "sd3",
  "prompt": "Marina Bay at sunset, vivid purple and orange afterglow, long exposure",
  "aspect_ratio": "16:9",
  "image_url": "https://example.com/style-ref.jpg",
  "seed": -1
}

Stability AI SDXL example (~$0.0026 upstream):

{
  "provider": "sdxl",
  "prompt": "Close-up food photography of a gourmet cheeseburger, shallow depth of field",
  "aspect_ratio": "1:1",
  "size": "1024*1024",
  "seed": -1
}

Qwen-Image-Max via DeepInfra example (~$0.075/image upstream, photorealistic):

{
  "provider": "qwen-image-max",
  "prompt": "Portrait of a woman in natural light, lifelike skin texture, shallow depth of field",
  "aspect_ratio": "3:4",
  "size": "1024x1536"
}

FLUX.2 Klein 9B LoRA example (~$0.02 upstream):

{
  "provider": "flux-klein-lora",
  "prompt": "Cinematic romantic drama still, rooftop at sunset, film photography",
  "aspect_ratio": "16:9",
  "size": "1024*1024",
  "loras": [
    {"path": "https://example.com/my-style-lora.safetensors", "scale": 1.0}
  ],
  "seed": -1
}

Parameters

Response

Binary images are returned as Base64 strings (typically PNG or JPEG depending on the provider).

{
  "success": true,
  "provider": "wan",
  "image": "base64_encoded_image_bytes",
  "images": ["base64_1", "base64_2"],
  "count": 1,
  "credits_used": 1.0,
  "credits_remaining": 99.0
}

Credits per image: MiniMax 7, WAN 8, Nucleus 4 (× num_images), Gen4 2/3, Gen4 Turbo 1, SD3 1, SDXL 1, FLUX Klein LoRA 1.

Image to video

Generates video from a reference image. Default provider is Seedance 2.0 Turbo (720p/1080p, optional audio); use provider gen4 for Runway Gen4 Turbo (WAVESPEED_API_KEY).

Endpoint: POST /api/v1/image-to-video/

Upstream docs: Seedance 2.0 I2V Turbo · Runway Gen4 Turbo

Request body (JSON or multipart)

{
  "provider": "seedance",
  "prompt": "Slow camera pan, golden hour light, gentle wind in the trees",
  "image_url": "https://example.com/reference.jpg",
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "adaptive",
  "generate_audio": true
}

Runway Gen4 Turbo example:

{
  "provider": "gen4",
  "prompt": "The subject turns slowly toward the camera, soft wind in their hair",
  "image_url": "https://example.com/reference.jpg",
  "duration": 5,
  "aspect_ratio": "16:9"
}

Alternatively send multipart/form-data with fields prompt, duration, resolution, aspect_ratio, generate_audio and file field image.

Or pass reference image as base64 in JSON field image (instead of image_url).

Parameters

Response

{
  "success": true,
  "provider": "seedance-2.0-turbo",
  "video": "base64_encoded_mp4_bytes",
  "duration": 5,
  "resolution": "720p",
  "credits_used": 15.0,
  "credits_remaining": 85.0,
  "video_size_bytes": 1234567
}

Credits: Seedance — 15/16 per 5s @ 720p/1080p (× duration). Gen4 Turbo — 2 per 5s (~$0.05 upstream).

Image to image

Edits 1–4 input images with FLUX.2 Flash Edit — restyle scenes, replace backgrounds, inpaint/outpaint, and retouch with plain-English prompts (WAVESPEED_API_KEY).

Endpoint: POST /api/v1/image-to-image/

Upstream docs: FLUX.2 Flash Edit

Request body (JSON or multipart)

{
  "provider": "flux-flash-edit",
  "prompt": "Replace the background with a modern office, keep the product centered",
  "images": [
    "https://example.com/product.jpg"
  ],
  "aspect_ratio": "1:1",
  "seed": 42
}

Multiple input images (up to 4):

{
  "prompt": "Merge styles: subject from first image, lighting from second",
  "image_urls": "https://example.com/a.jpg,https://example.com/b.jpg"
}

Alternatively send multipart/form-data with fields prompt, aspect_ratio, size, seed and file field images (1–4 files) or single image.

Or pass input images as base64 in JSON field image or array images.

Parameters

Response

{
  "success": true,
  "provider": "flux-2-flash-edit",
  "image": "base64_encoded_png_or_jpeg_bytes",
  "input_count": 1,
  "credits_used": 1.0,
  "credits_remaining": 99.0,
  "image_size_bytes": 456789
}

Credits: FLUX.2 Flash Edit — 1 credit per edit (~$0.013 upstream).

Text to video

Generates cinematic 720p/1080p video from a text prompt. Default provider is Seedance 2.0 Fast Turbo (WAVESPEED_API_KEY); use provider veo for Google Veo 3.1 Lite (WaveSpeed) or veo-fast for Google Veo 3.1 Fast (DEEPINFRA_API_KEY, $0.15/s upstream).

Endpoint: POST /api/v1/text-to-video/

Upstream docs: Seedance 2.0 Fast T2V Turbo · Google Veo 3.1 Lite · Google Veo 3.1 Fast (DeepInfra)

Request body (JSON)

{
  "provider": "veo",
  "prompt": "Tracking shot through a neon-lit alley at night, rain reflections",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "duration": 6,
  "generate_audio": true,
  "negative_prompt": "blurry, low quality",
  "seed": 42
}

Parameters

Response

{
  "success": true,
  "provider": "seedance-2.0-fast-turbo",
  "video": "base64_encoded_mp4_bytes",
  "duration": 5,
  "resolution": "720p",
  "credits_used": 13.0,
  "credits_remaining": 87.0,
  "video_size_bytes": 1234567
}

Credits: Seedance — 13/14 per 5s @ 720p/1080p (×2 with references). Veo 3.1 Lite — 7/11 per 6s @ 720p/1080p. Veo 3.1 Fast — 3.5 credits/s ($0.15/s upstream).

Voice memo (text only)

Create a voice memo from text only (no audio). The text is stored as a voice memo in your account and appears in the Voice notes list. Free — no credits charged.

Endpoint: POST /api/v1/voice-memo/text/

Request Body

{
  "text": "Your note text here",
  "title": "Optional title (default: first 50 chars of text)"
}

Parameters

Response

{
  "success": true,
  "voice_note_id": 123,
  "title": "Your note text here",
  "detail_url": "https://.../audio/voice-notes/123/",
  "created_at": "2026-02-04T12:00:00Z"
}

Get Available Voices

Endpoint: GET /api/v1/voices/

Query Parameters

• language: Filter voices by language code (optional)

Response

{
  "success": true,
  "voices": {
    "en": [
      {"id": "af_sarah", "name": "Sarah (Female, English)"},
      {"id": "am_adam", "name": "Adam (Male, English)"}
    ],
    "it": [
      {"id": "if_sara", "name": "Sara (Female, Italian)"}
    ]
  }
}

Check Status

Endpoint: GET /api/v1/status/

Response

{
  "success": true,
  "user": "username",
  "credits": 100.0,
  "api_key": {
    "name": "My API Key",
    "created_at": "2024-01-01T00:00:00Z",
    "last_used": "2024-01-15T12:00:00Z",
    "usage_count": 42
  }
}

Code Examples

cURL - TTS

curl -X POST https://webvoice.easytaskflow.app/api/v1/tts/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello, world!",
    "voice": "af_sarah",
    "language": "en",
    "speed": 0.90
  }'

Python - TTS

import requests
import base64

api_key = "YOUR_API_KEY"
url = "https://webvoice.easytaskflow.app/api/v1/tts/"

response = requests.post(
    url,
    headers={"X-API-Key": api_key},
    json={
        "text": "Hello, world!",
        "voice": "af_sarah",
        "language": "en",
        "speed": 0.90
    }
)

data = response.json()
audio_data = base64.b64decode(data["audio"])

with open("output.mp3", "wb") as f:
    f.write(audio_data)

Python - STT

import requests

api_key = "YOUR_API_KEY"
url = "https://webvoice.easytaskflow.app/api/v1/stt/"

with open("audio.mp3", "rb") as f:
    response = requests.post(
        url,
        headers={"X-API-Key": api_key},
        files={"audio": f},
        data={"language": "it"}
    )

data = response.json()
print(data["text"])

Python - Translation

import requests

api_key = "YOUR_API_KEY"
url = "https://webvoice.easytaskflow.app/api/v1/translation/"

response = requests.post(
    url,
    headers={
        "X-API-Key": api_key,
        "Content-Type": "application/json"
    },
    json={
        "text": "Hello, world!",
        "source_language": "en",
        "target_language": "it"
    }
)

data = response.json()
print(data["translated_text"])

cURL - Translation

curl -X POST https://webvoice.easytaskflow.app/api/v1/translation/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello, world!",
    "source_language": "en",
    "target_language": "it"
  }'

cURL - Image generation

curl -X POST https://webvoice.easytaskflow.app/api/v1/image/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A watercolor landscape with mountains",
    "width": 1024,
    "height": 1024
  }'

Python - Image generation

import requests
import base64

api_key = "YOUR_API_KEY"
url = "https://webvoice.easytaskflow.app/api/v1/image/"

response = requests.post(
    url,
    headers={"X-API-Key": api_key, "Content-Type": "application/json"},
    json={
        "prompt": "A red bicycle on a sunny street",
        "width": 1024,
        "height": 1024,
    },
)
data = response.json()
raw = base64.b64decode(data["image"])
with open("out.png", "wb") as f:
    f.write(raw)

Error Codes

Error Response Format

{
  "error": "Error type",
  "message": "Detailed error message"
}

Credits

• TTS: 0.5 credits per minute
• STT: 0.3 credits per minute
• Translation: 0.1 credit per 1000 characters (minimum 0.1)
• Image generation: credits per image as configured on the server (IMAGE_GENERATION_CREDITS; default 7 credits per image)