German Text-to-Speech API: de_DE Voice to MP3

You need to turn German text into an MP3 you can stream or download, and you want a dependable API you can ship today. This guide shows how to call Woord’s German Text-to-Speech API with language=de_DE, read the response, handle errors and limits, and move from a quick cURL to production code that saves the returned MP3 URL.

What you’ll build

By the end, you will:

• Authenticate with Woord and call POST https://www.getwoord.com/api/convert using Bearer auth.
• Send form fields for German (Germany) with language=de_DE.
• Parse the JSON response to get the MP3 URL and download it.
• Handle character limits (10k characters per file), retries, and simple caching.

Plan, limits, and when to use the API

Woord’s API converts text into an MP3 URL. The Starter plan is $9.99/mo. The per-file cap is 10,000 characters. There’s an 8-day trial with 20,000 characters. The Free plan cannot call the API, so if you plan to integrate programmatically, start a trial or paid plan first.

For docs on fields and supported parameters, see the official Documentation. Register here to get an API key: Register.

Quickstart: de_DE request (cURL)

The following request shows the official form fields for a German (Germany) conversion. Use your Bearer key and set language=de_DE.

curl "https://www.getwoord.com/api/convert" -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ACCESS_KEY" \
  --data "text=Hallo+Welt&gender_voice=male&language=de_DE&speakingRate=1.00"

Understanding the response

Below is the official sample response you can expect from a conversion request.

{
  "message": "Your audio has been created!",
  "audio_src": "https://getwoord.s3.amazonaws.com/4273352455515882618255eaaf3c1cbdbe0.55443890.mp3",
  "error": false
}

How to use it in your app:

• success: Boolean indicator that the conversion was accepted and processed. Always check this before trying to use any media links.
• audio_src: A direct or shareable URL to the generated MP3. This is the field you’ll fetch to play or download audio.
• Other fields: The sample may include additional metadata or identifiers. You can log them for observability or correlate them with your own job records. If a field is not documented for stability, do not hard-depend on it for business logic.

Error handling:

• If success is false, read any accompanying message or error description and do not assume audio_src is present.
• Missing or empty fields: Treat them as absent. Check for audio_src explicitly before you attempt to download. If it is missing when success is true, retry the request after a brief delay or consult the Documentation.

Time and units: When timestamps are present in any response fields, handle them as UTC unless the docs specify a timezone. URLs are plain HTTPS strings; durations, if returned, are typically seconds, but confirm in the official docs.

Step-by-step: from trial to live

1) Register and get your key

Start your 8-day / 20k-character trial here: Register. After sign-up, copy your Bearer key from your dashboard.

2) Send the conversion request

POST to https://www.getwoord.com/api/convert with Bearer authentication and the official form fields. For German (Germany), include language=de_DE.

3) Get and store the MP3 URL

Read audio_src from the JSON response. Save it in your database alongside your source text, locale (de_DE), and any application-specific identifiers you need.

4) Download or stream

Issue a GET to audio_src to download the MP3 file, or stream it directly in your app or web page.

JavaScript example (same request, de_DE to MP3)

The snippet below demonstrates how to call the same endpoint from Node.js with fetch and form-data, extract audio_src, and download the MP3.

import fetch from "node-fetch";
import FormData from "form-data";
import fs from "fs";

async function convertGermanTextToMp3({ apiKey, text }) {
  const form = new FormData();
  // Use the official convert fields. language must be "de_DE" for German (Germany).
  form.append("language", "de_DE");
  form.append("text", text);
  // If the docs expose voice or other fields in the official sample, include them like:
  // form.append("voice", "YOUR_SELECTED_VOICE");

  const res = await fetch("https://www.getwoord.com/api/convert", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`
    },
    body: form
  });

  if (!res.ok) {
    throw new Error(`HTTP ${res.status} calling convert`);
  }
  const json = await res.json();

  // Validate the response shape and success flag
  if (!json || json.success !== true) {
    const msg = json && (json.message || json.error || JSON.stringify(json));
    throw new Error(`Conversion failed: ${msg}`);
  }
  if (!json.audio_src) {
    throw new Error("No audio_src in successful response");
  }
  return json.audio_src;
}

async function download(url, outPath) {
  const res = await fetch(url);
  if (!res.ok) throw new Error(`HTTP ${res.status} downloading MP3`);
  const fileStream = fs.createWriteStream(outPath);
  await new Promise((resolve, reject) => {
    res.body.pipe(fileStream);
    res.body.on("error", reject);
    fileStream.on("finish", resolve);
  });
}

(async () => {
  try {
    const apiKey = "YOUR_API_KEY";
    const text = "Guten Tag! Dies ist eine deutsche Sprachsynthese mit Woord.";
    const audioUrl = await convertGermanTextToMp3({ apiKey, text });
    console.log("MP3 URL:", audioUrl);

    // Optionally save the MP3 locally
    await download(audioUrl, "woord-de_DE.mp3");
    console.log("Saved to woord-de_DE.mp3");
  } catch (err) {
    console.error(err);
    process.exit(1);
  }
})();

Locale and voice selection

Use the official language code de_DE to synthesize German (Germany). If you need Austrian German (when available in the voice picker), use de_AT. If a particular named voice is available in the convert form fields, select it per the official sample. When listing voices in your UI, be explicit about the locale (de_DE vs de_AT) so users know what they are choosing.

Production concerns: limits, chunking, retries, and caching

Character limits and batching

• Per-file cap: 10,000 characters. If your content exceeds this, split it cleanly between sentences or paragraphs so you don’t cut phonemes mid-word.
• Stitching: If you batch multiple segments, generate one MP3 per segment and assemble on the client side as a playlist, or concatenate offline with your own tooling if you need a single file. Track segment order with a sequence index.

Retries and idempotency

• If success is false, inspect any error message. Transient server or network errors can be retried with exponential backoff.
• Avoid re-submitting the same large text repeatedly; store your source text hash and the returned audio_src to prevent duplicate work.

Caching and storage

• Cache the audio_src you receive. Store it along with the source text, language=de_DE, and any selected voice.
• If you need offline playback, download the MP3 immediately and keep it in your storage bucket. Respect any cache-related headers on the audio URL if present; when in doubt, treat the URL as stable for the life of the content unless you rotate it by policy.
• For CDN delivery, copy the MP3 into your own bucket and serve via your CDN. Keep a mapping from your asset ID to the latest audio_src or stored object URL.

End-to-end “Go live” checklist

1. Register for the 8-day / 20k trial: Register.
2. Copy your Bearer key from your account.
3. POST the official convert form fields with language=de_DE.
4. Download the audio_src URL and serve or store the MP3.

To create your first German MP3 now, start here: Register.

Troubleshooting

• HTTP 401/403: Confirm your Authorization header is set to Bearer YOUR_API_KEY and that your plan allows API access.
• success is false: Read the error/message field if present. Check you’re within the 10k character cap and that required fields match the official convert parameters.
• Empty or missing audio_src: Treat as a failed job. Retry once after a short delay; if it persists, log the full JSON and consult the Documentation.
• Locale mismatch: If the voice doesn’t sound like German (Germany), verify language=de_DE and that a German-appropriate voice is selected when applicable. For Austrian German, use de_AT where available.

FAQ

Which language code do I send for German (Germany)?
Use language=de_DE in the convert form fields.

Can I call the API on the Free plan?
No. The Free plan cannot call the API. Use the 8-day trial (20k characters) or a paid plan.

What’s the maximum text size per conversion?
10,000 characters per file. Split longer inputs into multiple requests and join results in your app.

Where do I find the MP3 URL?
In the JSON response, read the audio_src field from your own request. That’s the URL you can stream or download.

How do I select Austrian German?
When listed in the voice picker, Austrian German uses the de_AT code. For German (Germany) use de_DE.

Ready to generate your first German MP3? Start your trial, copy your Bearer key, and ship your de_DE integration today: Register. For parameters and response details, keep the official Documentation open as you build.