# Reve API Research and Specifications

## Overview

Reve API provides image generation, editing, and remixing capabilities through three main endpoints. This document consolidates the available information about the API structure, authentication, and operation parameters.

## Base API Information

- **Base URL**: `https://api.reve.com`
- **Authentication**: Bearer token via Authorization header
- **Content Type**: `application/json`
- **Response Format**: JSON with base64 encoded images

## Authentication

### API Key Management
- **Header Format**: `Authorization: Bearer {api_key}`
- **Environment Variable**: `REVE_API_KEY`
- **Scope**: All endpoints require authentication

### Error Responses
- **401 Unauthorized**: Invalid or missing API key
- **403 Forbidden**: Insufficient permissions
- **429 Too Many Requests**: Rate limiting exceeded

## API Endpoints

### 1. Create Endpoint
**Purpose**: Generate images from text prompts

```
POST /api/create
```

**Parameters**:
- `prompt` (required): Text description of desired image
- `aspect_ratio` (optional): Image dimensions (16:9, 9:16, 3:2, 2:3, 4:3, 3:4, 1:1)
- `version` (optional): Model version (latest, reve-create@20250915)
- `output_format` (optional): Image format (png, jpeg, webp, json)

**Cost**: 18 credits per generation

### 2. Edit Endpoint  
**Purpose**: Modify existing images with text instructions

```
POST /api/edit
```

**Parameters**:
- `prompt` (required): Text instruction for editing
- `reference_image` (required): Base64 encoded source image
- `version` (optional): Model version (latest, reve-edit@20250915)
- `output_format` (optional): Image format (png, jpeg, webp, json)

**Cost**: 30 credits per edit

### 3. Remix Endpoint
**Purpose**: Combine multiple images with text guidance

```
POST /api/remix
```

**Parameters**:
- `prompt` (required): Text description with XML tags for image references
- `reference_images` (required): Array of 1-4 base64 encoded images
- `aspect_ratio` (optional): Output image dimensions
- `version` (optional): Model version (latest, reve-remix@20250915)
- `output_format` (optional): Image format (png, jpeg, webp, json)

**Cost**: 30 credits per remix

**XML Tag Format**: Use `<img1>`, `<img2>`, etc. in prompt to reference images

## Response Format

### Success Response
```json
{
  "image": "base64_encoded_image_data",
  "request_id": "unique_request_identifier",
  "credits_used": 18,
  "credits_remaining": 982,
  "metadata": {
    "operation": "create|edit|remix",
    "parameters": {...},
    "processing_time": 2.5,
    "model_version": "reve-create@20250915"
  }
}
```

### Error Response
```json
{
  "error": {
    "code": "CONTENT_POLICY_VIOLATION",
    "message": "Content violates policy guidelines",
    "details": "Specific violation description"
  },
  "request_id": "unique_request_identifier"
}
```

## Error Codes

### Client Errors (4xx)
- `400 BAD_REQUEST`: Invalid parameters or malformed request
- `401 UNAUTHORIZED`: Invalid or missing API key
- `403 FORBIDDEN`: Insufficient permissions or credits
- `404 NOT_FOUND`: Endpoint not found
- `429 TOO_MANY_REQUESTS`: Rate limit exceeded

### Server Errors (5xx)
- `500 INTERNAL_SERVER_ERROR`: Server processing error
- `502 BAD_GATEWAY`: Upstream service error
- `503 SERVICE_UNAVAILABLE`: Service temporarily unavailable

## Rate Limiting

- **Default Limits**: Not explicitly documented
- **Headers**: Check `X-RateLimit-*` headers in responses
- **Retry Strategy**: Exponential backoff recommended

## Content Policy

### Prohibited Content
- Violence, gore, or harmful content
- Adult or sexual content
- Copyrighted material without permission
- Hate speech or discriminatory content

### Detection
- Automatic content filtering on all operations
- Returns `CONTENT_POLICY_VIOLATION` error code
- No credits charged for policy violations

## Image Specifications

### Input Requirements
- **Format**: Base64 encoded (PNG, JPEG, WebP)
- **Size Limits**: 
  - Edit: Single image, max 10MB
  - Remix: 1-4 images, max 5MB each
- **Resolution**: Recommended 512x512 to 2048x2048

### Output Specifications
- **Format**: PNG, JPEG, WebP, or JSON metadata
- **Quality**: High resolution, production ready
- **Encoding**: Base64 in JSON response

## Model Versions

### Available Versions
- `latest`: Always points to newest stable version
- `reve-create@20250915`: Specific create model version
- `reve-edit@20250915`: Specific edit model version  
- `reve-remix@20250915`: Specific remix model version

### Version Selection
- Default: `latest` for all operations
- Explicit: Specify exact version for reproducibility
- Compatibility: Older versions may be deprecated

## Integration Notes

### Best Practices
1. **Error Handling**: Implement comprehensive error handling for all response codes
2. **Retry Logic**: Use exponential backoff for rate limiting and server errors
3. **Credit Monitoring**: Track credit usage to prevent service interruption
4. **Image Optimization**: Compress images before base64 encoding to reduce payload size
5. **Caching**: Cache successful responses when appropriate

### Performance Considerations
- **Request Size**: Minimize base64 payload size
- **Concurrent Requests**: Respect rate limits
- **Timeout Handling**: Set appropriate timeouts (30-60 seconds)
- **Memory Management**: Handle large image data efficiently

## Security Considerations

### API Key Protection
- Store API keys securely (environment variables, secure storage)
- Never expose keys in client-side code
- Rotate keys regularly
- Monitor for unauthorized usage

### Data Privacy
- Images are processed server-side
- No guarantee of data retention policies
- Consider data sensitivity before uploading

## Testing and Development

### Sandbox Environment
- No explicit sandbox mentioned in documentation
- Use low-cost operations for testing
- Monitor credit usage during development

### Debugging
- Use `request_id` for support requests
- Log API responses for troubleshooting
- Monitor error patterns and rates

---

*Note: This documentation is based on available project specifications and common API patterns. Some details may need verification against the actual Reve API documentation when accessible.*