This guide walks through building a full-featured Eden application using our hello-eden starter repository.
Overview
The hello-eden repository is a production-ready Next.js application that demonstrates best practices for integrating with the Eden API. It showcases all major Eden features including AI-powered creation, agent interactions, and content browsing.Hello Eden Repository
Clone the starter repository to follow along with this guide
What You’ll Build
By following this guide, you’ll learn how to:- Generate AI content - Submit creation tasks for images and videos
- Build chat interfaces - Create interactive sessions with Eden agents
- Browse creations - Implement galleries with filtering and pagination
- Handle authentication - Properly manage API keys and credentials
- Poll for results - Implement efficient polling patterns for async operations
Prerequisites
Before starting, ensure you have:- Node.js 18+ and pnpm installed
- Basic familiarity with React and Next.js
- Eden API credentials (request in Discord)
Quick Start
1. Clone and Setup
2. Configure Environment
Edit.env.local
with your credentials:
Keep your
EDEN_API_KEY
private! Never commit it to version control or expose it in client-side code.3. Run the Application
Core Concepts
API Client Structure
The hello-eden app uses a centralized API client (src/lib/eden.ts
) that wraps all Eden API interactions. This pattern provides:
- Type-safe interfaces for all API responses
- Centralized error handling
- Consistent authentication headers
- Clean separation between API logic and UI components
Authentication Pattern
The app uses Next.js API routes as a backend-for-frontend (BFF) pattern to keep API keys secure:- Client makes requests to Next.js API routes
- API Route adds authentication headers
- API Route forwards request to Eden API
- Response flows back through the same chain
Feature Implementation
Creating Images and Videos
The creation flow involves submitting a task and polling for completion:1
Submit Creation Task
Send a POST request to
/v2/tasks/create
with your prompt and configuration2
Poll for Completion
Check task status every few seconds until completed
3
Display Result
Show the generated content once the task completes
Building Agent Chat Interfaces
Eden agents support interactive conversations through sessions:Browsing and Filtering Creations
Implement galleries with advanced filtering:Best Practices
Error Handling
Always implement robust error handling for API calls:Rate Limiting
Be mindful of API rate limits:- Implement exponential backoff for retries
- Cache responses when appropriate
- Batch requests where possible
- Use reasonable polling intervals (3-5 seconds)
Security
- Never expose API keys in client-side code
- Use environment variables for all credentials
- Implement proper CORS headers in production
- Validate and sanitize all user inputs
- Use HTTPS for all API communications
Performance
- Implement loading states for better UX
- Use React hooks for efficient state management
- Lazy load images and videos
- Implement pagination for large datasets
- Cache API responses when appropriate
Common Patterns
Polling Pattern
API Route Pattern
Deployment
Environment Variables
When deploying to production, ensure all environment variables are properly configured:Variable | Required | Description |
---|---|---|
EDEN_API_KEY | Yes | Your Eden API key for authentication |
NEXT_PUBLIC_EDEN_AGENT_ID | Yes | Default agent ID for chat features |
NEXT_PUBLIC_EDEN_API_BASE | No | API endpoint (defaults to production) |
Troubleshooting
Common Issues
Task creation returns 401 Unauthorized
Task creation returns 401 Unauthorized
Polling never completes
Polling never completes
Solution: Some tasks may take longer to process. Increase your polling timeout or implement a maximum retry count to prevent infinite polling.
CORS errors in browser
CORS errors in browser
Solution: Make sure you’re calling your Next.js API routes, not the Eden API directly from the browser. The API routes should proxy requests to Eden.
Agent not responding in chat
Agent not responding in chat
Solution: Verify the agent ID exists and is active. Check that autonomy settings are properly configured for auto-reply.
Next Steps
Now that you have a working Eden application, explore these advanced features:Custom Agents
Learn how to create and configure custom AI agents
Custom Models
Learn how to create and configure custom AI models
Advanced Creation
Explore all creation tools and parameters
API Documentation
Complete API reference and endpoints
Resources
- Hello Eden Repository - Starter code
- Eden Discord - Get help and API keys
- API Documentation - Full API reference
- Eden App - Try Eden features in the browser
Support
Need help? Join our Discord community where you can:- Request API keys
- Get implementation help
- Report bugs and issues
- Share your creations
- Connect with other developers