letzai-api（letzai API 控制）

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:

1. POST to /images with parameters
2. Receive id in response
3. Poll GET /images/{id} every 3 seconds
4. When status === "ready", access imageVersions.original

For code examples, see examples/image_generation.js

2. 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:

1. Ensure you have a source image (generate one first if needed)
2. POST to /videos with parameters
3. Receive id in response
4. Poll GET /videos/{id} every 2-3 seconds
5. When status === "ready", access videoPaths

For code examples, see examples/video_generation.py

3. 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:

1. POST to /image-edits with parameters
2. Receive id in response
3. Poll GET /image-edits/{id} every 3 seconds
4. When status === "ready", access generatedImageCompletion.imageVersions.original

Note: Inpainting (mode: "in") and Outpainting (mode: "out") are deprecated - use Context Editing instead.

4. 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:

1. POST to /upscales with parameters
2. Receive id in response
3. Poll GET /upscales/{id} every 3 seconds
4. 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:

1. Determine appropriate model based on quality/cost needs
2. Use POST /images with appropriate baseModel
3. If using a trained model, include @modelname in the prompt
4. Poll GET /images/{id} every 3s until ready
5. Return imageVersions.original URL

User wants to use a custom trained model:

1. Use GET /models to list available trained models (filter by class if needed)
2. Include @modelname in the prompt when generating images
3. Generate image normally with POST /images

User wants to edit an existing image:

1. Obtain source image URL, inputImageUrls array, or originalImageCompletionId
2. Use POST /image-edits with mode="context"
3. Include settings for resolution, aspect_ratio, and model as needed
4. Poll GET /image-edits/{id} every 3s until ready
5. Return generatedImageCompletion.imageVersions.original

User wants to create a video:

1. Ensure they have a source image (URL or imageCompletionId)
2. If no source image, generate one first using /images
3. Use POST /videos with desired settings
4. Poll GET /videos/{id} every 2-3s until ready
5. Return video URL from videoPaths

User wants to upscale an image:

1. Obtain source image URL or imageCompletionId
2. Use POST /upscales with desired strength
3. Poll GET /upscales/{id} every 3s until ready
4. 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

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

Error Handling

Common HTTP Status Codes

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

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/