lum3on-ComfyUI_Reve-API/docs/api_research.md

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

{
  "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

{
  "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.