Hey everyone! I've been deep in the weeds of a content migration project lately (moving a mountain of old documentation from a legacy CMS to a new platform), and part of the cleanup involved making the tone more consistent and modern. Doing this manually through the Wordtune UI was, as you can imagine, not scalable. 😅
So, I naturally turned to their API. While it's straightforward for single sentences, I needed to process entire directories of `.txt` files. I ended up writing a Python script to handle batch processing, and I thought I'd share my approach and a few hiccups I ran into for anyone thinking of doing something similar.
Here's the core script I put together. It's pretty simple but saved me countless hours. You'll need your API key handy and the `requests` library.
```python
import os
import requests
import time
from pathlib import Path
WORDS_PER_REQUEST = 150 # Staying well under the API's max to be safe
API_KEY = "YOUR_API_KEY_HERE"
API_URL = "https://api.wordtune.com/rewrite"
INPUT_DIR = Path("./raw_docs")
OUTPUT_DIR = Path("./processed_docs")
OUTPUT_DIR.mkdir(exist_ok=True)
headers = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}
def chunk_text(text, chunk_size):
words = text.split()
for i in range(0, len(words), chunk_size):
yield ' '.join(words[i:i + chunk_size])
for txt_file in INPUT_DIR.glob("*.txt"):
print(f"Processing {txt_file.name}...")
with open(txt_file, 'r', encoding='utf-8') as f:
full_text = f.read()
rewritten_chunks = []
for chunk in chunk_text(full_text, WORDS_PER_REQUEST):
payload = {
"text": chunk,
"intent": "general",
"tone": "professional", # You can change this to 'casual', 'formal', etc.
"focus": "none"
}
try:
response = requests.post(API_URL, json=payload, headers=headers)
response.raise_for_status()
data = response.json()
# The API returns multiple choices; I'm taking the first one.
rewritten_chunks.append(data.get("choices", [{}])[0].get("text", chunk))
except requests.exceptions.RequestException as e:
print(f" Error on chunk: {e}. Using original.")
rewritten_chunks.append(chunk)
time.sleep(0.5) # Polite delay to avoid rate limiting
final_text = ' '.join(rewritten_chunks)
output_file = OUTPUT_DIR / txt_file.name
with open(output_file, 'w', encoding='utf-8') as f:
f.write(final_text)
print("Batch processing complete!")
```
A few things I learned the hard way:
* **Chunking is crucial:** The API has a token limit per request. Sending whole documents will fail. My initial naive attempt got me a swift 413 error.
* **Error handling is a must:** Network blips happen. The script now defaults to the original chunk if an API call fails, so you don't lose entire files.
* **Tone consistency:** If you're processing a batch, set your `tone` and `focus` parameters carefully. I had to re-run one batch because I accidentally left it on "casual" for very technical docs. 🙃
* **Cost awareness:** This uses your API quota *fast*. Monitor your usage in the dashboard, especially with large batches. It's not expensive, but it's easy to burn through credits if you're iterating on a script.
* **The output is not always a 1:1 length:** The rewritten text can be longer or shorter. For my use case (tone, not strict length), this was fine, but be warned if you have tight layout constraints.
Overall, I'm really happy with the results. It gave a uniform voice to a very heterogeneous set of documents. The API is reliable, though I wish the documentation had more examples for batch scenarios like this.
Has anyone else tried automating Wordtune for larger tasks? I'm curious if you used a different strategy, especially for handling more complex file formats like Markdown or HTML where you'd want to preserve structure.
—B
Backup first.
Your approach of batching by word count is pragmatic, but I'm concerned about the statistical implications of your chunking method. Splitting solely by a fixed word count could sever semantic context, and the API's rewrite quality might degrade at those artificial boundaries. Have you considered measuring the variance in output quality between chunks split at sentence boundaries versus your current method?
Also, you're exposing a potential point of failure by not implementing retry logic with exponential backoff for the API calls. The script will fail on a single 429 or 5xx error. A more robust version would log the failed file and continue, then allow for a resume. Something like:
```python
def rewrite_with_retry(text_chunk, max_retries=3):
for attempt in range(max_retries):
try:
response = requests.post(...)
response.raise_for_status()
return response.json()
except requests.exceptions.RequestException as e:
if attempt == max_retries - 1:
raise
time.sleep(2 ** attempt)
```
Without this, your batch process isn't truly production-ready for a "mountain" of documentation.
p-value < 0.05 or bust
You're totally right about the chunking method, that's a fair point. I was so focused on the word count limits of the API that I didn't fully weigh the semantic breaks. In my docs, a lot of it was short procedural steps, so it kind of worked, but I can see how for narrative content it would butcher the flow.
The retry logic is a must, I agree. I actually did have a basic version, but I stripped it out for the post to keep the snippet simple - a classic case of over-simplifying! Your structure with the exponential backoff is spot on. In my actual run, I hit a couple 429s and had to manually restart, which was a pain. For anyone trying this, definitely build that in from the start. It turns a fragile script into something you can actually leave running overnight.
Have you tried the sentence-boundary approach on a similar project? I'm curious if the API handles longer, multi-sentence paragraphs well or if it starts to ignore the later sentences.
Cool hack! I always hit the same wall with these AI writing APIs - they're built for one-off tasks, not bulk jobs. Have you checked how the per-request word limit compares to other tools? Grammarly's API lets you send way more per call, which might change your chunking strategy.
Did you track the cost per 1k files? I ran something similar and the bills got weird once I passed their free tier. The output was great, but I'm still hunting for a bulk discount.
Demo or it didn't happen
Oh, nice! I've hit that same wall with the single-task UI bottleneck before. Your script structure is almost exactly what I set up for a similar project last month, but I ran into a different snag: some of my .txt files had weird encoding (thanks, Windows Notepad from 2005!), and the script choked on them. Adding a quick encoding fallback like `open(file, 'r', encoding='utf-8', errors='ignore')` saved me from a real headache later.
The WORDS_PER_REQUEST = 150 is smart. I started at 200 and got a few "exceeds limit" errors before scaling back. Ever experiment with sending slightly under the limit but with the "formal" or "casual" tone parameter set globally? I found it gave me even more consistency across the whole batch.
Nice! That's a clever workaround for the API's limits. I've run into a similar pattern when streaming logs through transformation services.
One thing I'd watch out for: chunking by raw word count can sometimes split a logical unit of thought, like a key instruction or a list item. For documentation, it might be fine, but if you ever move to more narrative content, you'll want to split on sentence or paragraph boundaries first.
Ever consider adding a simple progress tracker? When I let scripts like this run for hours, I get paranoid they've frozen. A quick `print(f"Processed {i}/{total_files}")` after each file gives peace of mind.
Great point about comparing per-request limits. It really does force a different architectural approach. I've looked at Grammarly's offering, and you're right, the larger payload would simplify the chunking logic. The trade-off for me, honestly, came down to the specific tone adjustment Wordtune offers, which fit my use case better. The chunking became an annoying but necessary tax for that.
On the cost question, yes, the billing gets interesting at scale. I didn't get a clean "per 1k files" because my files varied so much in size, but tracking cost per 100,000 words processed was an eye-opener. I also never found a true bulk discount, but I did negotiate a slightly better rate as part of a larger annual enterprise contract that included other services. It wasn't a discount on the API per se, but more of an overall deal. Have you had any luck asking your account manager? Sometimes they can structure something if you have predictable, high volume.
buyer beware, but buy smart
Oh this is super helpful to see! I've been wanting to try the Wordtune API for a similar cleanup task but the idea of writing the script from scratch felt overwhelming. Seeing the basic structure makes it seem way more approachable.
A quick question, though: when you set `WORDS_PER_REQUEST = 150`, does that count include the words you're sending *and* the words it generates in the rewritten version? Or is it just a limit on the input text? I'd be worried about accidentally going over if the response is long.
> Have you tried the sentence-boundary approach on a similar project?
I tried exactly that on a batch of help articles! The results were mixed. For paragraphs with a clear topic sentence and a few supporting points, the API handled it beautifully and kept the flow intact. But longer, dense paragraphs - think a technical specification - sometimes got "rewritten" in a way that felt like only the first or last sentence was truly altered. It seems to have a practical limit on how much contextual awareness it applies within a single request, even if you're under the word count.
For purely procedural docs, your word-count method is probably fine. For anything with a narrative thread, I'd pre-process to split on double newlines (paragraphs) first, then fall back to sentences if a paragraph is too long. It adds a step but saves a ton of post-edit cleanup.
Test, measure, repeat
Oh, the "practical limit on contextual awareness" you mentioned is such a good point! It explains a weird result I got where a key technical term got rephrased in the first sentence but was left untouched later in the same chunk, making it inconsistent.
Your pre-process suggestion is gold. I think I'll try splitting on paragraphs first for my next batch of email copy. That should keep the core message of each paragraph intact while still batching for the API.
Did you find the output quality dropped noticeably on those longer, dense paragraphs, or was it just inconsistent?
Oh, that's a great point about the word count limit! I was wondering the same thing. I'm about to try my first batch script for cleaning up some old blog drafts, and I would've totally assumed the limit was just for input. If it includes the output, I'd be worried about hitting the cap, especially if the AI decides to get really verbose with the rewrite. Did you find a way to check the total word count of the response within the script, or did you just play it extra safe with a lower input limit?
Just my two cents.
Great question about the word count! From my tests, the limit applies to the combined input+output tokens in their system. I started with a safe 120 input words to give the rewrite room to breathe, and it's worked well.
If you're worried about verbosity, you could experiment with the "shorten" option as your base rewrite style. That tends to keep the output tighter and more predictable for blog drafts.
measure twice, ship once
Ah, the "shorten" gambit. Sure, it keeps things tidy, but have you checked if it's just chopping out nuance instead of verbosity? I've seen it turn a carefully qualified statement into a blunt, oversimplified one, which isn't always an improvement. Sometimes the AI's idea of concise is just incomplete.
cg
Agreed on both counts, but the retry logic is more critical from a cost perspective than a reliability one. An unhandled 429 can stall the entire batch, leaving you with partial results and still on the hook for the successful calls, which is a pure waste of budget. Exponential backoff directly manages that spend by gracefully handling provider-side throttling.
The semantic boundary point is valid, but it introduces a new variable: cost per processed unit becomes harder to predict. If you switch to splitting by paragraphs, your chunks become irregular in size, and you'll likely end up consuming your API quota less efficiently due to rounding. You might find yourself paying for 150-word capacity while sending only a 40-word paragraph, which changes the economic model of your script.
Always check the data transfer costs.
Interesting to see another automation script for Wordtune. But everyone seems to be glossing over the long-term cost and lock-in you're signing up for.
That script is a textbook example of how you become structurally dependent on a vendor. You're building a custom pipeline around their specific API limits, chunking logic, and error codes. Once you've processed your "mountain of old documentation," you'll have thousands of files now optimized for their platform. The next time you need a tweak, you're going right back to their API.
Have you priced out what it would cost to re-run this script in six months after a tone guideline update? Or if you need to process a second, larger batch? The unit cost seems manageable until you realize your only off-ramp is to throw away all the processed work and start over with a different tool.
Trust but verify.