Skip to main content
Aya integrates with multiple AI providers to power intelligent features like content translation, automatic summarization, and future AI-driven capabilities.

​
Supported Providers

Anthropic

Claude models for high-quality translation and summarization

OpenAI

GPT models with broad language support

Google Gemini

Gemini models for multimodal capabilities
Aya uses a provider-agnostic abstraction layer. Configure any provider, and features work seamlessly.

​
AI Features

​
Auto-Translation

Translate stories and profiles to all 13 supported languages: How it works:
1

User requests translation

Select source and target locale for story
2

Permission check

System verifies user can edit the story
3

Points deducted

Profile points charged for translation (configurable cost)
4

AI translation

  • Story title, summary, and content sent to AI provider
  • Provider returns translated text in target locale
  • Preserves Markdown formatting
5

Save translation

Translated content saved to story_tx table
6

Audit log created

Translation event recorded for transparency
Supported Content:
  • Story titles
  • Story summaries
  • Story content (full Markdown)
  • Profile titles (planned)
  • Profile descriptions (planned)
  • Profile pages (planned)
AI translations are a starting point. Always review and edit for cultural nuance and accuracy.

​
Auto-Summarization

Generate concise summaries for long-form content: Batch Processing:
1

Identify unsummarized stories

Nightly job finds stories without summary_ai
2

Create batch job

  • Stories grouped into batch (up to 1000)
  • Batch submitted to AI provider’s batch API
  • Job ID returned for tracking
3

Provider processes batch

  • AI generates summaries offline
  • Typically completes within 24 hours
  • Cost-effective bulk processing
4

Retrieve results

  • System polls for batch completion
  • Downloads result file
  • Parses summaries
5

Store summaries

Summaries saved to summary_ai field on stories
Use Cases:
  • Generate summaries for imported content
  • Backfill summaries for old stories
  • Consistent summary style across platform
  • Used in bulletin board digests
Summarization uses batch API for cost efficiency. Results appear within 24 hours, not real-time.

​
Configuration

​
Provider Setup

AI providers are configured via environment variables using the AI__ prefix: Target Structure: 
AI__TARGETS__[name]__PROVIDER=anthropic
AI__TARGETS__[name]__API_KEY=your_api_key
AI__TARGETS__[name]__MODEL=claude-sonnet-4-20250514

​
Anthropic Configuration

# Primary translation target
AI__TARGETS__DEFAULT__PROVIDER=anthropic
AI__TARGETS__DEFAULT__API_KEY=sk-ant-api03-xxx
AI__TARGETS__DEFAULT__MODEL=claude-sonnet-4-20250514
AI__TARGETS__DEFAULT__MAX_TOKENS=4096
AI__TARGETS__DEFAULT__TEMPERATURE=0.3
AI__TARGETS__DEFAULT__REQUEST_TIMEOUT=60s
Models:
  • claude-sonnet-4-20250514 (recommended for translation)
  • claude-opus-4-20250514 (highest quality)
  • claude-haiku-4-20250514 (fastest, cheapest)

​
OpenAI Configuration

AI__TARGETS__OPENAI__PROVIDER=openai
AI__TARGETS__OPENAI__API_KEY=sk-proj-xxx
AI__TARGETS__OPENAI__MODEL=gpt-4o
AI__TARGETS__OPENAI__MAX_TOKENS=4096
AI__TARGETS__OPENAI__TEMPERATURE=0.3
Models:
  • gpt-4o (multimodal, recommended)
  • gpt-4o-mini (fast, economical)
  • gpt-4-turbo (previous generation)
Properties: 
AI__TARGETS__OPENAI__PROPERTIES__EXPOSE_INTERNAL_ERRORS=false

​
Google Gemini Configuration

AI__TARGETS__GEMINI__PROVIDER=gemini
AI__TARGETS__GEMINI__API_KEY=AIzaSyxxx
AI__TARGETS__GEMINI__MODEL=gemini-2.0-flash-exp
AI__TARGETS__GEMINI__MAX_TOKENS=8192
AI__TARGETS__GEMINI__TEMPERATURE=0.3
Models:
  • gemini-2.0-flash-exp (fast, experimental)
  • gemini-1.5-pro (production-ready)
  • gemini-1.5-flash (economical)

​
Vertex AI Configuration

For Google Cloud Vertex AI: 
AI__TARGETS__VERTEX__PROVIDER=vertexai
AI__TARGETS__VERTEX__PROJECT_ID=your-gcp-project
AI__TARGETS__VERTEX__LOCATION=us-central1
AI__TARGETS__VERTEX__MODEL=gemini-1.5-pro
AI__TARGETS__VERTEX__PROPERTIES__SERVICE_ACCOUNT=base64_encoded_json
AI__TARGETS__VERTEX__PROPERTIES__BATCH_BUCKET=gs://your-bucket
AI__TARGETS__VERTEX__PROPERTIES__PROJECT_NUMBER=123456789
Service Account: 
# Base64 encode service account JSON
cat service-account.json | base64 -w 0
Keep API keys secure. Never commit them to version control. Use environment variables or secret management.

​
Multi-Provider Setup

Configure multiple providers for fallback: 
# Primary provider (Anthropic)
AI__TARGETS__DEFAULT__PROVIDER=anthropic
AI__TARGETS__DEFAULT__API_KEY=sk-ant-xxx
AI__TARGETS__DEFAULT__MODEL=claude-sonnet-4-20250514

# Fallback provider (OpenAI)
AI__TARGETS__FALLBACK__PROVIDER=openai
AI__TARGETS__FALLBACK__API_KEY=sk-proj-xxx
AI__TARGETS__FALLBACK__MODEL=gpt-4o

# Batch processing (Vertex AI for cost)
AI__TARGETS__BATCH__PROVIDER=vertexai
AI__TARGETS__BATCH__PROJECT_ID=aya-prod
AI__TARGETS__BATCH__MODEL=gemini-1.5-pro
Usage in Code: 
// Use default for translation
translator := aifx.GetClient(registry, "default")

// Use batch for summarization
summarizer := aifx.GetClient(registry, "batch")

​
Provider Selection Guide

Best for:
  • High-quality translations
  • Complex content understanding
  • Long context windows
  • Accurate Markdown preservation
Pricing:
  • Sonnet: Moderate cost
  • Opus: Higher cost, best quality
  • Haiku: Low cost, good for simple tasks
Limits:
  • Rate limits by tier
  • Context window: up to 200K tokens
Best for:
  • General-purpose tasks
  • Batch processing
  • Broad language support
  • Structured output
Pricing:
  • GPT-4o: Moderate cost
  • GPT-4o-mini: Very economical
Limits:
  • Rate limits by tier
  • Context window: up to 128K tokens
  • Batch API available (50% discount)
Best for:
  • Multimodal content (future)
  • Cost-effective processing
  • Google Cloud integration
  • Long context tasks
Pricing:
  • Very competitive
  • Flash models extremely economical
Limits:
  • Context window: up to 1M tokens (Pro)
  • Rate limits vary by region
Best for:
  • Enterprise deployments
  • Google Cloud customers
  • Batch processing at scale
  • Data residency requirements
Pricing:
  • Pay-per-use
  • Committed use discounts
  • Batch discounts
Limits:
  • GCP project quotas
  • Region-specific availability

​
Translation Workflow

​
User-Initiated Translation

1

Create story in source language

Write story content in your primary language (e.g., English)
2

Open translation dialog

Click “Translate” button on story edit page
3

Select target locale

Choose from 13 supported languages
4

Confirm and pay points

Translation costs profile points (typically 50-100 points)
5

AI translates

  • System sends content to configured AI provider
  • Provider returns translation
  • Usually completes in 5-30 seconds
6

Review translation

  • Translation displayed in editor
  • Edit for accuracy and cultural fit
  • Save when satisfied

​
Bulk Translation

For translating multiple stories: 
# API endpoint for bulk translation
POST /api/stories/bulk-translate
{
  "story_ids": ["id1", "id2", "id3"],
  "source_locale": "en",
  "target_locales": ["es", "fr", "ja"],
  "profile_id": "individual-profile-id"
}
Bulk translation charges points per story per target locale. Ensure sufficient points before starting.

​
Batch Processing

Batch processing reduces costs for non-urgent tasks:

​
OpenAI Batch API

1

Prepare batch file

Create JSONL file with requests:
{"custom_id": "story-123", "method": "POST", "url": "/v1/chat/completions", "body": {...}}
{"custom_id": "story-456", "method": "POST", "url": "/v1/chat/completions", "body": {...}}
2

Upload batch file

File uploaded to OpenAI via Files API
3

Create batch job

Batch created with 24-hour completion window
4

Monitor progress

Poll batch status: validating → in_progress → completed
5

Retrieve results

Download output file and parse responses
6

Process results

Save summaries/translations to database
Batch Benefits:
  • 50% cost reduction vs. real-time
  • Efficient for 100s-1000s of items
  • No rate limit concerns
  • Better for non-urgent tasks

​
Points System Integration

AI features cost profile points:

​
Translation Costs

const CostAutoTranslate = 50 // points per translation
Cost Factors:
  • Per story, per target locale
  • Deducted from individual profile
  • Non-refundable once translation starts
  • Adjustable via configuration

​
Earning Points

Users earn points through:
  • Profile creation (+100)
  • Publishing stories (+50)
  • Community engagement (+10-25)
  • Verified contributions (+50)
  • Special achievements (varies)
Translation is a premium feature. Users should earn or purchase points to access AI capabilities.

​
Error Handling

AI operations can fail for various reasons: Common Errors: 
Error: Insufficient points for translation
Required: 50 points
Available: 25 points
Solution: Earn more points or purchase points
Error: AI provider rate limit exceeded
Retry after: 60 seconds
Solution: Wait and retry, or configure fallback provider
Error: AI translation failed
Provider: anthropic
Reason: Context too long
Solution: Split content into smaller chunks or use provider with larger context window
Error: AI provider authentication failed
Provider: openai
Solution: Check API key configuration, verify key is active

​
Monitoring & Observability

​
Audit Logs

All AI operations are logged: 
{
  "event_type": "story_auto_translated",
  "entity_type": "story",
  "entity_id": "story-ulid",
  "actor_id": "user-ulid",
  "payload": {
    "source_locale": "en",
    "target_locale": "es",
    "provider": "anthropic",
    "model": "claude-sonnet-4",
    "duration_ms": 3500
  }
}

​
Metrics

Track AI usage:
  • Translation count per day/week/month
  • Tokens consumed by provider
  • Average translation latency
  • Error rates by provider
  • Points spent on AI features
  • Cost tracking (tokens × price)
Set up alerts for high error rates or unexpected cost spikes.

​
Cost Optimization

  • Use cheaper models for simple translations
  • Reserve Opus/GPT-4o for complex content
  • Use batch processing for non-urgent tasks
  • Consider Gemini Flash for cost savings
  • Keep system prompts concise
  • Send only necessary content
  • Use structured output to reduce tokens
  • Cache prompts when possible
  • Implement user-level rate limits
  • Use queue for batch operations
  • Implement exponential backoff
  • Monitor usage patterns
  • Set monthly budget caps
  • Alert on unusual spending
  • Track cost per user/story
  • Charge points appropriately

​
Best Practices

  • Rotate keys quarterly
  • Use separate keys per environment (dev/staging/prod)
  • Store in secret management system (Vault, AWS Secrets Manager)
  • Never log API keys
  • Restrict key permissions to minimum needed
  • Always review AI translations
  • Provide context in prompts (domain, audience)
  • Use consistent terminology
  • Maintain glossary for technical terms
  • A/B test different providers/models
  • Use provider abstraction (don’t couple to one provider)
  • Implement circuit breaker pattern
  • Queue AI requests for reliability
  • Cache common translations
  • Log all operations for debugging
  • Show progress indicators
  • Provide estimated completion time
  • Allow cancellation for long operations
  • Clear error messages
  • Preview translations before saving

​
Troubleshooting

  1. Check source content encoding (UTF-8)
  2. Verify Markdown is valid
  3. Test with simpler content
  4. Try different model/provider
  5. Check prompt engineering
  6. Review provider API logs
  1. Check batch status via API
  2. Verify batch size is within limits
  3. Ensure JSONL format is correct
  4. Check provider service status
  5. Review batch logs for errors
  6. Try smaller batch size
  1. Check network connectivity
  2. Verify provider region (use closest)
  3. Reduce content size if possible
  4. Increase request timeout
  5. Use faster model variant
  6. Implement retry with backoff

​
Roadmap

Planned AI features:
  • Profile description translation
  • Custom page translation
  • AI-assisted content editing
  • Automatic content tagging
  • Smart content recommendations
  • Sentiment analysis for discussions
  • Spam detection
  • Image generation for stories
  • Voice synthesis for accessibility
  • Multi-modal content analysis

​
Next Steps

Stories

Use AI translation on your stories

Profiles

Understand points system for AI features

Bulletin Board

AI summaries in digest emails

Custom Domains

Serve translated content on your domain

Build docs developers (and LLMs) love

Get started for freeTalk to us