API Documentation (1.0)

Initializes a media upload and returns a presigned URL for direct upload to S3.

Workflow:

1. Call this endpoint with file metadata (name, type, size)
2. Upload the file directly to the returned uploadUrl using a PUT request
3. Call /api/media/finalize with the mediaId to complete the upload

Example upload to S3:

curl -X PUT -H "Content-Type: image/png" --data-binary @image.png "$uploadUrl"

Finalizes a media upload after the file has been uploaded to S3. Call this after successfully uploading the file to the uploadUrl from /api/media/initialize.

Lists the available avatars. These include stock avatars as well as avatars created by the account associated with the supplied API key.

Lists the available voices. These include stock voices as well as voices created by the account associated with the supplied API key.

Lists the videos that have completed generation.

Fetches metadata for a single completed video.

Downloads a single completed video.

Checks the status of a video generation job. The status will be one of:

• "inference_started": Job has been queued
• "inference_working": Job is in progress
• "inference_complete": Video generation is complete
• "inference_failed": Job failed
• "inference_error": Unknown error occurred

Note: The ID parameter should be the jobId that was returned from the video creation endpoint.

Starts a new video creation job. The specified avatar will be used, and either a speech can be created using a specified voice and script, or an uploaded audio track can be used.

Starts a new text-to-image generation job. Provide a text prompt describing the image you want to generate.

This endpoint generates images from text descriptions without requiring any reference images.

Workflow:

1. Call this endpoint to create a job. You'll receive a jobId in the response.
2. Use the jobId with GET /api/image/{jobId} to check the job status.
3. Poll the status endpoint until the job is complete (status: "inference_complete").
4. When complete, the response will include a downloadUrl field containing the image URL.

Starts a new image-to-image editing job. Upload one or more reference images and provide a prompt describing how you want to edit them. The AI will transform the images based on your prompt.

You can either upload files directly (multipart/form-data) or provide media IDs of previously uploaded images (application/json). You can provide a single image or multiple images.

Workflow:

1. Call this endpoint to create a job. You'll receive a jobId in the response.
2. Use the jobId with GET /api/image/{jobId} to check the job status.
3. Poll the status endpoint until the job is complete (status: "inference_complete").
4. When complete, the response will include a downloadUrl field containing the image URL.

Starts a new image inpainting job. Upload an original image and a mask image (black and white), then specify what you want to replace in the masked areas. The mask should have white areas indicating what to replace and black areas indicating what to keep.

You can either upload files directly (multipart/form-data) or provide media IDs of previously uploaded images (application/json).

To create a mask image, you can use the frontend interface at /create-ai-image:

1. Upload your original image
2. Switch to Inpaint mode
3. Draw mask areas with the blue brush
4. Click "Download Mask" to download the black/white mask image
5. Use the downloaded mask image in your API request

Workflow:

1. Call this endpoint to create a job. You'll receive a jobId in the response.
2. Use the jobId with GET /api/image/{jobId} to check the job status.
3. Poll the status endpoint until the job is complete (status: "inference_complete").
4. When complete, the response will include a downloadUrl field containing the image URL.

Gets the status or result of any job. This is the general entry point for job status management.

When the job is in progress or failed, returns status information:

• "inference_started": Job has been queued
• "inference_working": Job is in progress (may include progress percentage)
• "inference_failed": Job failed

When the job is completed:

• For image jobs: Returns image metadata and download URL
• For other job types: Returns completion status

Note: The jobId parameter should be the jobId that was returned from the job creation endpoint.

Generates a product mockup by compositing logos onto a product image.

Workflow:

1. First upload your product and logo images using the media upload endpoints
2. Call this endpoint with the media IDs and placement instructions
3. The mockup is generated synchronously and returned with an image URL

Creates an 8-second product advertisement video from a saved mockup.

Animation Styles:

• luxury_macro: Luxury macro studio film
• neo_noir_night: Neo-noir night street set
• warm_lifestyle_sunset: Golden-hour lifestyle cinematic
• futuristic_clean_studio: Ultra-clean futuristic studio
• cyberpunk_showcase: Cyberpunk display pedestal
• film_35mm_editorial: 35mm film editorial look
• high_fashion_runway: High-fashion spotlight stage
• nature_premium: Premium nature set
• custom: Custom prompt only

Workflow:

1. Call this endpoint with a mockup ID and animation style
2. A job ID is returned immediately
3. Poll /api/mockup/{jobId}/status to check progress
4. When complete, get the video URL from /api/mockup/videos

Generates a new logo or product image from a text prompt.

Workflow:

1. Call this endpoint to start generation
2. A job ID is returned immediately
3. Poll /api/mockup/{jobId}/status to check progress
4. When complete, retrieve the asset from /api/mockup/assets

Edits an existing image using AI based on a text prompt.

You can provide the image in three ways:

• imageMediaId: Media ID of a previously uploaded image
• imageBase64: Base64-encoded image data
• image: File upload (multipart/form-data)

Workflow:

1. Call this endpoint to start editing
2. A job ID is returned immediately
3. Poll /api/mockup/{jobId}/status to check progress
4. When complete, retrieve the asset from /api/mockup/assets

Lists all saved product mockups for the authenticated user.

Lists all saved logo and product assets for the authenticated user.

Lists all generated product advertisement videos for the authenticated user.

Checks the status of a mockup-related job (mockup generation, asset generation, or video generation).

Generates a YouTube thumbnail from a text prompt, optionally using reference images.

Basic Workflow:

1. Call this endpoint with a text prompt
2. A job ID is returned immediately
3. Poll /api/thumbnail/{jobId} to check status
4. When complete, the response includes the download URL

With Reference Images:

1. Upload reference images using /api/media/initialize and /api/media/finalize
2. Include the mediaId values in referenceImageMediaIds array
3. The AI will use these images as style/content references

Using YouTube Video Thumbnails as Reference:

1. Extract video ID from YouTube URL (e.g., watch?v=abc123 → abc123)
2. Download thumbnail: https://img.youtube.com/vi/{videoId}/maxresdefault.jpg
3. Upload via media endpoints to get a mediaId
4. Pass mediaId in referenceImageMediaIds to generate a similar thumbnail

Lists all generated YouTube thumbnails for the authenticated user.

Gets the status of a thumbnail generation job, or the thumbnail details if completed.