New: Batch Endpoint for High-Volume Processing

New: Batch Endpoint for High-Volume Processing

We’ve noticed something about our customers: the teams doing the highest volume of content humanization aren’t sending single requests. They’re processing hundreds of pieces of content per day. Descriptions for 500 e-commerce products. Emails for weekly campaigns. Support articles for a knowledge base refresh.

Our original API was optimized for individual requests. One piece of content, one response. That works fine for lower-volume use cases. But for high-volume operations, it creates workflow inefficiencies. You’re making hundreds of individual API calls, managing individual responses, handling individual errors.

We’ve built something better: the Batch Endpoint.

How It Works

Instead of sending content one piece at a time, you submit a batch, up to 500 pieces in a single request. The system processes them in parallel, returns the results as a structured batch response, and gives you simplified error handling. One request instead of 500.

The results come back in the same order you submitted them, which means you can match input to output without additional parsing. If one item in the batch fails, the others still succeed and you get detailed information about why the failure happened so you can fix and resubmit just the failed items.

Who Benefits

E-commerce companies processing thousands of product descriptions benefit immediately. Instead of looping through their product database and making individual API calls, they submit batches and get humanized descriptions back in minutes instead of hours.

Content agencies managing bulk humanization for multiple clients can process entire projects in batches instead of fighting with API call limits and rate throttling.

Any team running regular bulk operations on content, newsletter archives, customer email imports, knowledge base migrations, content library overhauls, can now process that content in hours instead of days.

The Technical Details

Batch processing isn’t just multiple requests bundled together. We’ve redesigned the backend to handle parallel processing efficiently. When you submit a batch, the items are queued for processing and handled by available worker processes. You don’t pay per-request pricing for batch jobs, you pay a single batch processing fee regardless of batch size (up to 500 items).

Response time depends on batch size and current system load, but our testing shows 500-item batches typically process in 30-60 seconds. That’s roughly 10x faster than submitting 500 individual API requests sequentially.

The batch response includes detailed metadata about each item: processing time, token usage, confidence score. That transparency helps you understand exactly what happened to each piece of content.

Error Handling That Actually Works

One problem with bulk processing: a single error shouldn’t tank your entire batch. Our Batch Endpoint is built to prevent that. If item 47 fails for some reason, items 1-46 and 48-500 still process successfully. You get detailed information about why item 47 failed, and you can fix and resubmit just that item.

That granular error reporting means you spend less time troubleshooting and more time processing content.

Pricing

Batch processing costs less than individual requests at volume. Here’s the structure: you pay $0.02 per 1000 tokens processed, same as with individual requests. But batch jobs come with a $1.00 minimum fee per batch regardless of size. That minimum applies whether you’re processing 10 items or 500 items.

For high-volume operations, the math works out dramatically in your favor. A company processing 10,000 product descriptions per month will see roughly 40% cost reduction by moving to batch processing.

Implementation

If you’re already using our API, adding batch processing is straightforward. We’ve updated our documentation with code examples for every major language. The request structure is similar to our standard API, you just include multiple content items and submit.

We’ve also built a simple batch processing portal in your account dashboard. If you prefer not to write API code, you can upload a CSV file with your content, submit it, and download the results when processing completes.

Check out our API documentation for implementation details and code examples in your language.

When You Should Use Batch vs. Individual

Use the Batch Endpoint when: you’re processing 10+ items at once, you have a deadline that’s hours or days away, you want simplified error handling, cost per item matters for your use case.

Use individual API requests when: you’re processing single items on-demand, you need immediate response times (under 5 seconds), you’re integrating into a real-time system where latency matters.

For most high-volume operations, batch processing is faster, cheaper, and simpler. That’s the sweet spot this endpoint targets.

What We’re Thinking About Next

We’re working on scheduled batch processing, the ability to queue batches for processing at specific times (like 2am when your infrastructure has capacity). That should help teams with tight deadlines spread their processing across less busy hours.

We’re also designing batch webhooks, so you can get a notification when your batch finishes instead of polling the API to check status. That’s useful for teams processing very large batches that take 15+ minutes.

Ready to Process at Scale?

The Batch Endpoint is live now for all customers with API access. If you have questions about whether it’s right for your use case, check out our use cases or review the technical documentation.

Want to start processing batches today? Sign up or upgrade your plan on our pricing page.

When you actually need the batch endpoint

If you’re processing fewer than 10 items at a time, the standard /v1/humanize endpoint is fine – it’s faster per-request because there’s no batch coordination overhead. The batch endpoint earns its place when you have:

• 50+ items in a queue – overnight content runs, weekly content sprints, bulk migrations
• Latency tolerance – you don’t need each result instantly; minutes-to-hours is fine
• Webhook-friendly architecture – your system can receive results asynchronously
• Cost sensitivity at volume – batch processing earns better effective per-word rates on enterprise plans

Endpoint specification

The batch endpoint accepts up to 100 items in a single request. For larger jobs, use the async variant with a webhook callback.

POST /v1/humanize/batch
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "items": [
    { "id": "post-1", "text": "...", "tone": "professional" },
    { "id": "post-2", "text": "...", "tone": "casual" },
    { "id": "post-3", "text": "...", "tone": "academic", "language": "es" }
  ]
}

Response (synchronous, for ≤100 items):

{
  "results": [
    {
      "id": "post-1",
      "success": true,
      "humanized_text": "...",
      "confidence_score": 0.94,
      "processing_time_ms": 1247
    },
    { "id": "post-2", "success": true, "humanized_text": "...", "confidence_score": 0.91, ... },
    { "id": "post-3", "success": true, "humanized_text": "...", "confidence_score": 0.93, ... }
  ],
  "batch_id": "b_abc123",
  "total_processed": 3,
  "total_failed": 0
}

Async batch with webhooks (for >100 items)

For jobs larger than 100 items, queue them with a callback URL. The API returns immediately with a job ID, processes in the background, and POSTs the full results to your webhook when complete.

POST /v1/humanize/batch/async
{
  "items": [/* up to 10,000 items */],
  "callbackUrl": "https://yourapp.com/webhook/humanize-complete",
  "callbackSecret": "shared-secret-for-hmac-verification"
}

// Immediate response
{ "job_id": "j_xyz789", "status": "queued", "estimated_completion": "2026-04-29T12:34:56Z" }

Your webhook receives the full results when the job finishes. See webhook setup for the verification + retry pattern.

Patterns we see in production

Nightly content batches

SEO and content marketing teams queue all of the day’s drafted content (typically 20-200 pieces), then run a single async batch overnight. Editors review the humanized versions in the morning. Maximum throughput, minimum API call overhead.

# Cron job at midnight
import requests, os

drafts = fetch_drafts_for_today()  # from your CMS

response = requests.post(
    'https://api.aihumanizerapi.com/v1/humanize/batch/async',
    headers={'Authorization': f'Bearer {os.environ["AIH_KEY"]}'},
    json={
        'items': [
            {'id': str(d.id), 'text': d.body, 'tone': 'professional'}
            for d in drafts
        ],
        'callbackUrl': 'https://yourapp.com/api/webhook/humanize',
    },
)
job_id = response.json()['job_id']
log.info(f'queued batch job {job_id} with {len(drafts)} items')

Migration backfills

Teams with a backlog of AI-drafted content already published often run a one-time migration to humanize older posts. Use the async endpoint, batch in chunks of 1,000, and stagger over a week to avoid sudden ranking changes.

Multi-tenant SaaS workflows

If you’re building a SaaS that humanizes on behalf of customers, batch their requests with their tenant ID in the id field. The response preserves the ID so you can route results back correctly.

Performance characteristics

Internally, all three modes use the same humanization engine. The async endpoint just pre-allocates more parallel workers and returns the result via webhook instead of holding the HTTP connection open.

Rate limits and concurrency

Batch requests count as one against your per-minute rate limit, regardless of the number of items inside. So a Pro plan with 60 RPM can submit 60 batches per minute = up to 6,000 humanizations per minute via batch – vs 60 per minute via single-call.

If you’re hitting limits even on batch, see rate-limit best practices for backoff patterns and tier-upgrade guidance.

Error handling within a batch

Individual items can fail without failing the whole batch. Failed items return:

{
  "id": "post-7",
  "success": false,
  "error_code": "text_too_short",
  "error_message": "Input must be at least 10 characters"
}

Iterate the response and retry only the failed items. Common error codes:

• text_too_short – input under 10 chars
• text_too_long – input over plan-specific cap (Free: 5K chars, Pro: 50K, Enterprise: 200K)
• language_not_supported – language code not in the supported list
• invalid_tone – tone parameter not one of professional/conversational/casual/academic

Cost optimization at high volume

• Use async batch when possible. Same per-word cost, but the batched processing is more efficient for our infrastructure, which lets us pass through better effective rates on enterprise plans.
• Cache identical inputs. The API caches results for 1 hour server-side, but at high volume you should also cache client-side to save the round-trip.
• Trim before submitting. Don’t humanize boilerplate (footers, repeated CTAs, navigation) – extract just the body content.
• Use the right tone. “academic” is more compute-intensive than “casual” because it preserves more sentence structure. Pick the lightest tone that fits your audience.

Get started with batch

The API docs have the full schema for both sync and async batch endpoints, including webhook payload format and HMAC verification. Free-tier accounts can use the sync batch endpoint up to plan limits.

For volume-sensitive use cases (10K+ items/month), talk to our team about Enterprise pricing – better effective per-word rates kick in past certain thresholds.

Sign up for an API key to start testing batch flows on the free tier.