LetzAI API Integration Skill Overview
This skill enables Claude to help users integrate with the LetzAI API for AI-powered image and video generation, editing, and upscaling. Users can also leverage custom-trained AI models (persons, objects, styles) via the @modelname syntax.
Authentication Base URL: https://api.letz.ai Authentication: Bearer token in Authorization header Get API Key: letz.ai/subscription API Documentation: api.letz.ai/doc Setting Up Authentication const headers = { 'Content-Type': 'application/json', 'Authorization': 'Bearer YOUR_API_KEY' };
headers = { 'Content-Type': 'application/json', 'Authorization': 'Bearer YOUR_API_KEY' }
Core Workflows 1. Image Generation
Endpoint: POST /images
Required Parameters:
prompt (string): Text description of the desired image. Can include @modelname to use trained models.
Optional Parameters:
baseModel: AI model to use "gemini-3-pro-image-preview" - Nano Banana Pro (recommended) "flux2-max" - Flux2 Max "seedream-4-5-251128" - SeeDream 4.5 mode: Resolution mode (varies by model) Nano Banana Pro: "default", "2k", "4k" Flux2 Max: "1k", "hd" SeeDream: "2k", "4k" width / height: Image dimensions (520-2160px)
Workflow:
POST to /images with parameters Receive id in response Poll GET /images/{id} every 3 seconds When status === "ready", access imageVersions.original
For code examples, see examples/image_generation.js
- Video Generation
Endpoint: POST /videos
Required Parameters:
prompt (string): Text description of the desired video Source image (one of): imageUrl: URL of source image originalImageCompletionId: ID from previous image generation
Optional Parameters:
settings.mode: Video model "default" - Default model "veo31" - VEO 3.1 "kling26" - Kling 2.6 "wan25" - Wan 2.5 settings.duration: Video length in seconds (2-12 depending on model)
Workflow:
Ensure you have a source image (generate one first if needed) POST to /videos with parameters Receive id in response Poll GET /videos/{id} every 2-3 seconds When status === "ready", access videoPaths
For code examples, see examples/video_generation.py
- Image Editing (Context Editing)
Endpoint: POST /image-edits
Required Parameters:
mode: Edit mode "context" - AI editing (primary mode) "skin" - Skin fix prompt: Edit instruction (e.g., "change background to beach") Source image (one of): imageUrl: URL of source image inputImageUrls[]: Array of source image URLs (max 9) originalImageCompletionId: ID of previously generated LetzAI image
Optional Parameters:
settings.model: "gemini-3-pro-image-preview", "flux2-max", "seedream-4-5-251128" settings.resolution: "2k" (HD) or "4k" (Ultra HD) settings.aspect_ratio: "1:1", "16:9", "9:16", "4:3", "3:4", "21:9", "9:21" baseModel: Alternative to settings.model webhookUrl: Optional callback URL organizationId: Optional org ID for billing
Workflow:
POST to /image-edits with parameters Receive id in response Poll GET /image-edits/{id} every 3 seconds When status === "ready", access generatedImageCompletion.imageVersions.original
Note: Inpainting (mode: "in") and Outpainting (mode: "out") are deprecated - use Context Editing instead.
- Image Upscaling
Endpoint: POST /upscales
Required Parameters:
Source image (one of): imageUrl: URL of source image imageCompletionId: ID from previous image generation
Optional Parameters:
strength: Upscale factor (1-3)
Workflow:
POST to /upscales with parameters Receive id in response Poll GET /upscales/{id} every 3 seconds When status === "ready", access upscaled image 5. Custom AI Models (Trained Models)
LetzAI users can train custom AI models on persons, objects, or styles via the web interface. These trained models can be used in prompts via the @modelname syntax.
List Models Endpoint: GET /models
Query Parameters:
page: int (default: 1) limit: int (default: 10) sortBy: "createdAt" | "usages" sortOrder: "ASC" | "DESC" class: "person" | "object" | "style"
Get Model Details: GET /models/{id}
Model Classes:
person: Trained on photos of a specific person object: Trained on product/object images style: Trained on artistic style examples
Using Models in Prompts: Tag models with @modelname syntax:
@john_doe on the beach at sunset - Use a person model A product photo featuring @my_product - Use an object model Portrait in @vintage_style aesthetic - Use a style model
Note: Model training is done via the LetzAI web interface (letz.ai), not via API.
Workflow Decision Tree User wants to create an image: Determine appropriate model based on quality/cost needs Use POST /images with appropriate baseModel If using a trained model, include @modelname in the prompt Poll GET /images/{id} every 3s until ready Return imageVersions.original URL User wants to use a custom trained model: Use GET /models to list available trained models (filter by class if needed) Include @modelname in the prompt when generating images Generate image normally with POST /images User wants to edit an existing image: Obtain source image URL, inputImageUrls array, or originalImageCompletionId Use POST /image-edits with mode="context" Include settings for resolution, aspect_ratio, and model as needed Poll GET /image-edits/{id} every 3s until ready Return generatedImageCompletion.imageVersions.original User wants to create a video: Ensure they have a source image (URL or imageCompletionId) If no source image, generate one first using /images Use POST /videos with desired settings Poll GET /videos/{id} every 2-3s until ready Return video URL from videoPaths User wants to upscale an image: Obtain source image URL or imageCompletionId Use POST /upscales with desired strength Poll GET /upscales/{id} every 3s until ready Return upscaled image URL Status Polling Pattern
LetzAI uses asynchronous generation. After any POST request, you must poll the corresponding GET endpoint until the job completes.
Status Values Status Meaning new Job created, queued for processing in progress / generating Currently processing ready Complete - fetch URLs from response failed Error occurred - check error message Polling Intervals Images: Every 3 seconds Videos: Every 2-3 seconds Image Edits: Every 3 seconds Upscales: Every 3 seconds
For detailed polling implementation, see examples/polling_pattern.md
Pricing Reference Feature Model Credits Image Gen Nano Banana Pro 80/160/240 (1k/HD/4K) Image Gen Flux2 Max 60/120 (1k/HD) Image Gen SeeDream 80/160 (HD/4K) Editing Same as above Same pricing Video Default 60 cr/sec (2-6 sec) Video VEO 3.1 1500-6000 cr (8 sec) Video Kling 2.6 750-1500 cr (5-10 sec) Upscale All 40 cr Error Handling Common HTTP Status Codes Status Meaning Solution 401 Invalid or missing API key Check Authorization header format 402 Insufficient credits Top up at letz.ai/subscription 400 Invalid parameters Verify baseModel, mode, dimensions 404 Resource not found Check the ID is correct 429 Rate limited Implement exponential backoff 500 Server error Retry after delay Error Response Format { "error": "Error description", "code": "ERROR_CODE" }
Limitations Async Generation: All generation is asynchronous - must poll for results Video Source: Video generation requires a source image Reference Images: Maximum 9 reference images for image editing Model Training: Cannot train custom AI models via API - use letz.ai web interface API Key Required: Paid subscription required for API access Quick Reference: API Endpoints Endpoint Method Purpose /images GET List user's images /images POST Create image (prompt, baseModel, mode, width, height) /images/{id} GET Get image status & URLs (poll every 3s) /images/{id}/interruption PUT Stop image generation /images/{id}/privacy PUT Change image privacy /videos GET List user's videos /videos POST Create video (prompt, imageUrl, settings) /videos/{id} GET Get video status & URLs (poll every 2-3s) /videos/{id}/interruption PUT Stop video generation /videos/{id}/privacy PUT Change video privacy /image-edits GET List user's edits /image-edits POST Edit image (mode, prompt, imageUrl/inputImageUrls, settings) /image-edits/{id} GET Get edit status & URLs (poll every 3s) /upscales POST Upscale image (imageUrl/imageUrls, strength, mode, size) /upscales/{id} GET Get upscale status & URLs (poll every 3s) /models GET List trained AI models (filter by class: person/object/style) /models/{id} GET Get specific model details Key Response Fields Images/Upscales: imageVersions.original, imageVersions["1920x1920"], imageVersions["640x640"] Edits: generatedImageCompletion.imageVersions.original Videos: videoPaths object, videoVersions array Status values: new, in progress/generating, ready, failed Additional Resources API Documentation: api.letz.ai/doc Developer Docs: letz.ai/docs/api Detailed API Reference: api_reference.md Code Examples: examples/