LetzAI API Integration Skill

Overview

Helps you integrate the LetzAI public API for AI image and video generation, editing, upscaling, asset uploads, and custom model (LoRA) training. Custom-trained models for persons, objects and styles are referenced inside prompts with @modelname.

Authentication

• Base URL: https://api.letz.ai
• Auth: Authorization: Bearer YOUR_API_KEY
• Get an API key: letz.ai/subscription
• Swagger (source of truth): api.letz.ai/doc — machine-readable at /doc-json and /doc-yaml

const headers = {
  'Content-Type': 'application/json',
  Authorization: `Bearer ${process.env.LETZAI_API_KEY}`,
};

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {os.environ['LETZAI_API_KEY']}",
}

Do not confuse the public API with the private one. https://api.letz.ai is the public developer API described here. https://private-api.letz.ai powers the LetzAI web app and has different route names (/upscales, /image_completions, /video-edits). Those routes 404 on the public API.

Unknown-field rejection

The API validates request bodies strictly. Sending a field that is not in the schema returns 400. In particular there is no negativePrompt, seed or aspectRatio on POST /images — aspect ratio is expressed via width/height.

Core Workflows

1. Image Generation — POST /images

Image models

mode is the resolution tier, and the accepted values are model-specific.

Aliases are accepted, e.g. gemini-3-pro-image-preview still resolves to Nano Banana Pro. The live catalogue with pricing lives at letz.ai/docs/models.json.

Workflow

1. POST /images
2. Read id from the response
3. Poll GET /images/{id} every 3 s
4. On status === "ready", read imageVersions.original

See examples/image_generation.js.

2. Video Generation — POST /videos

Image input is optional — omit all of originalImageCompletionId / imageUrl / imageUrls for pure text-to-video.

settings

Video models

Use the video- prefixed key as settings.mode.

Workflow

1. POST /videos
2. Poll GET /videos/{id} every 2–3 s
3. On status === "ready", read videoVersions.original

See examples/video_generation.py.

3. Image Editing — POST /image-edits

settings:

• resolution: "2k" (HD) or "4k" (Ultra HD)
• aspect_ratio: "1:1", "16:9", "9:16", "4:3", "3:4", "21:9", "9:21"
• model: same identifiers as baseModel

Provide at least one source: imageUrl, inputImageUrls, originalImageCompletionId or originalImageCompletionIds.

Prefer the top-level baseModel. Server-side queue routing reads baseModel; settings.model is forwarded to the worker. Setting both to the same value is safest.

Workflow

1. POST /image-edits
2. Poll GET /image-edits/{id} every 3 s
3. On status === "ready", read generatedImageCompletion.imageVersions.original

mode: "in" (inpainting) and mode: "out" (outpainting) are deprecated — use context.

4. Upscaling — POST /upscale

The public route is /upscale (singular). /upscales is the private web-app route and returns 404 here.

Workflow

1. POST /upscale
2. Poll GET /upscale/{id} every 3 s
3. On status === "ready", read imageVersions.original

5. Uploading Your Own Files — POST /user-assets

Two-step pre-signed S3 upload. Use this to get a public URL for a local file before feeding it to /image-edits, /videos or /upscale.

1. POST /user-assets with { extension } (plus optional originalFilename, mimeType, fileSize, caption, metadata, numberOfImages).
2. PUT the raw file bytes to the returned uploadUrl with the matching Content-Type header. No Authorization header — the URL is already signed.
3. The file is then reachable at imageUrl from the step-1 response.

Allowed extension values: jpg, jpeg, png, gif, webp, mp4, webm, mov, avi, mp3, wav, ogg, m4a, aac, flac.

POST /user-images is the older image/video-only variant of the same flow; prefer /user-assets, which also accepts audio.

See examples/uploads_and_training.md.

6. Custom AI Models (@modelname)

Trained models for persons, objects and styles. Tag them inside any image or edit prompt: @john_doe on the beach at sunset.

List: GET /models — query params page, limit, sortBy, sortOrder, search, name, userId, username, class (person | object | style), type, description, privacy (public | private | licensed), systemVersion, isActive, status. Pagination is reported through the X-Total-Count, X-Current-Page, X-Per-Page and X-Total-Pages response headers.

Get one: GET /models/{id}

Train a new model: POST /models — this is available over the API (Enterprise plans).

Training starts automatically. Poll GET /models/{id} until status is available.

Manage: PATCH /models/{id}, DELETE /models/{id}, PUT /models/{id}/thumbnail.

Workflow Decision Tree

Create an image → pick baseModel + mode from the model table → POST /images → poll GET /images/{id} → imageVersions.original.

Use a trained model → GET /models?class=person to find the name → put @name in the prompt → generate normally.

Edit an image → get a source (URL, /user-assets upload, or a LetzAI completion id) → POST /image-edits with mode: "context" → poll → generatedImageCompletion.imageVersions.original.

Create a video → optional source image → POST /videos with settings.mode = a video-* key → poll → videoVersions.original.

Upscale → POST /upscale with imageId or imageUrl → poll → imageVersions.original.

Train a model → upload images via /user-assets → POST /models with trainingDataUrls → poll GET /models/{id} until available.

Status Polling

Every generation endpoint is asynchronous: the POST returns an id, and you poll the matching GET until a terminal status.

There is no "in progress" status — in-flight jobs report generating. Treat ready and saved as success; failed, interrupted and not_allowed as terminal failures. Responses also carry progress (0–100) and, during generation, a base64 previewImage.

Recommended intervals: 3 s for images / edits / upscales, 2–3 s for videos. Pass a webhookUrl instead of polling for production workloads.

For a full implementation, see examples/polling_pattern.md.

Error Handling

Limitations

• All generation is asynchronous — poll or use webhooks.
• Videos are billed per model; per-second models can be expensive at 1080p/4K.
• mode values are model-specific; an unsupported tier falls back to the model default.
• Seedance 2.0 Enterprise requires an organizationId you are a member of.
• A paid subscription is required for API access.

Quick Reference: API Endpoints

Not on the public API (private web-app routes — these 404): /upscales, /video-edits, /image_completions, PUT /videos/{id}/interruption.

Key response fields

• Images / upscales: imageVersions.original, imageVersions["1920x1920"], imageVersions["640x640"]
• Edits: generatedImageCompletion.imageVersions.original (source in originalImageCompletion)
• Videos: videoVersions.original
• In flight: progress (0–100), previewImage (base64), statusDetail on failure

Model Catalogue

To see the current list of AI Models that are supported on LetzAI, including their parameters and token costs, always read the models.json file:

Model catalogue (live): letz.ai/docs/models.json

Additional Resources

• Swagger / OpenAPI: api.letz.ai/doc · /doc-json
• Developer docs: letz.ai/docs/api
• Model catalogue (live): letz.ai/docs/models.json
• Detailed reference: api_reference.md
• Code examples: examples/
• LetzAI Documentation with all features of the platform: letz.ai/docs