Lucidpic API

Agent quickstart

Create a Lucidpic API key at https://lucidpic.com/profile/api-keys, then paste this into your coding agent:

Use the Lucidpic API docs at https://lucidpic.com/developers/api.md.
If I do not have an API key yet, ask me to create one at https://lucidpic.com/profile/api-keys.
Use my bearer API key for authenticated requests. Store it in the project's .env file as LUCIDPIC_API_KEY or follow the project's secure secret-management conventions; do not hard-code it.
First call GET https://api.lucidpic.com/v2/models/catalog to inspect available image and video models, unless the request should use auto model selection.
If unsure, omit the model field and let Lucidpic choose automatically.
Create generations with POST https://api.lucidpic.com/v2/create, then poll GET https://api.lucidpic.com/v2/generation/{generation_id} until status is completed or failed.
Do not invent provider names or provider model IDs; use the public model keys from the catalog response.

Overview

• Base URL: https://api.lucidpic.com
• Current public surface: /v2
• Authentication: bearer API key
• Primary workflow: list available models if you want to choose one, or leave model selection on auto mode; then create a generation and poll it until it reaches a terminal state.

Practical guidance

• Store the key safely: Use an environment variable such as LUCIDPIC_API_KEY. Do not paste API keys into source files, prompts that will be committed, logs, or browser code.
• Prefer auto mode first: If you do not need a specific model, omit model and video_model_key. Lucidpic will choose a suitable model.
• Choose explicit models from the catalog only: If you do set model, call GET /v2/models/catalog first and use a public key from the response.
• Use IDs from responses: Use generation id values for polling, and image/media id values for edit, upscale, remove-background, enhance-realism, or image-to-video requests.
• Poll politely: Poll every few seconds, back off on 429, and stop when status is completed or failed.
• Treat responses as public API shapes: Provider names, provider request IDs, raw provider errors, routing config, queue names, and internal storage metadata are intentionally omitted.

Authentication

Create an API key from your account API keys page:

• API keys page: https://lucidpic.com/profile/api-keys

New keys are shown once. Copy the key when it is created, store it securely, then send it as a bearer token:

export LUCIDPIC_API_KEY="lp_your_api_key"

curl https://api.lucidpic.com/v2/usage \
  -H "Authorization: Bearer $LUCIDPIC_API_KEY" \
  -H "Accept: application/json"

API keys act as your Lucidpic account. Keep them private and revoke keys you no longer use.

Quickstart

Optional: inspect available image and video models before choosing request fields:

curl https://api.lucidpic.com/v2/models/catalog \
  -H "Authorization: Bearer $LUCIDPIC_API_KEY" \
  -H "Accept: application/json"

Create an image generation:

curl -X POST https://api.lucidpic.com/v2/create \
  -H "Authorization: Bearer $LUCIDPIC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "custom_prompt": "A cinematic studio portrait of a confident founder",
    "image_orientation": "portrait",
    "batch_size": 1
  }'

The response includes a generation ID. Poll until the generation reaches a terminal state:

curl https://api.lucidpic.com/v2/generation/{generation_id} \
  -H "Authorization: Bearer $LUCIDPIC_API_KEY" \
  -H "Accept: application/json"

Common in-progress states include pending, queued, starting, processing, and in_progress. Terminal states are completed and failed.

API responses are intentionally product-facing. They include stable Lucidpic IDs, status, credit usage, prompts, media URLs, and public catalog metadata. Provider names, provider request IDs, raw provider errors, routing config, queue names, and internal storage metadata are not returned through bearer API keys.

Generation

POST /v2/create

Create an image generation, image-to-video generation, or text-to-video generation.

Common request fields:

• custom_prompt (string): Text prompt.
• character_id (integer, optional): Lucidpic character ID.
• style_id (integer, optional): Style ID.
• image_orientation (string, optional): portrait, square, or landscape.
• batch_size (integer, optional): Number of images to create. Range: 1 to 4.
• generate_video (boolean, optional): Set to true for video generation.
• video_prompt (string, optional): Motion prompt for video generation.
• media_id (integer, optional): Existing media ID for image-to-video or variations.
• model (string, optional): Public image model key from GET /v2/models/catalog. Omit for auto mode.
• video_model_key (string, optional): Public video model key from GET /v2/models/catalog. Omit for auto mode.

Required image example:

{
    "custom_prompt": "A cinematic studio portrait of a confident founder",
    "image_orientation": "portrait",
    "batch_size": 1
}

Explicit model example:

{
    "custom_prompt": "A clean ecommerce photo of a red canvas backpack",
    "image_orientation": "square",
    "batch_size": 1,
    "model": "z-image-turbo"
}

Example response:

{
    "id": 456,
    "status": "pending",
    "credits": 1,
    "batch_size": 1,
    "operation": null
}

GET /v2/generation/{generation}

Fetch status and results for a generation owned by the authenticated account.

Polling guidance:

• Poll every 3 to 5 seconds for normal image generations.
• Poll less frequently for video generations.
• Stop polling on completed or failed.
• On failure, show error_message to the user. Do not retry indefinitely.

Example completed response:

{
    "id": 456,
    "status": "completed",
    "credits": 1,
    "images": [
        {
            "id": 789,
            "url": "https://...",
            "thumbnail_url": "https://...",
            "media_type": "image",
            "image_orientation": "portrait"
        }
    ],
    "error_message": null
}

Catalog

GET /v2/characters

List system characters and your own trained characters.

Example response:

{
    "characters": [
        {
            "id": 101,
            "name": "Ava",
            "is_system": true,
            "avatar_url": "https://...",
            "reference_image_count": 1
        }
    ]
}

GET /v2/styles

List available styles.

Example response:

[
    {
        "id": 10201,
        "name": "Cinematic",
        "key": "cinematic",
        "slug": "cinematic",
        "supported_types": ["image", "video"],
        "default_type": "image"
    }
]

GET /v2/models/catalog

List image and video models available in Lucidpic. The response includes public model keys, display names, descriptions, credit costs, supported inputs, and video capabilities.

Example response:

{
    "image": {
        "z-image-turbo": {
            "key": "z-image-turbo",
            "friendly_name": "Z-Image Turbo",
            "credits": 1,
            "supports_reference_image": false
        }
    },
    "video": {
        "wan_i2v_fast": {
            "key": "wan_i2v_fast",
            "friendly_name": "WAN 2.2 Fast",
            "credits": 8,
            "capabilities": {
                "durations": [5, 8],
                "supports_audio": false
            }
        }
    }
}

GET /v2/usage

Check your current credit balance and monthly limit.

Example response:

{
    "status": "ok",
    "credit_balance": 42,
    "limit_hit": false,
    "limit": 0
}

Image operations

POST /v2/create/upscale

Upscale an existing media item.

{
    "media_id": 123
}

Example queued response:

{
    "success": true,
    "message": "Image upscale in progress.",
    "generation_id": 901,
    "media_id": 902,
    "operation": {
        "key": "upscale",
        "status": "queued",
        "source_media_id": 123,
        "output_media_id": 902,
        "output_type": "image"
    }
}

POST /v2/create/remove-background

Remove the background from an existing image.

{
    "media_id": 123
}

POST /v2/create/enhance-realism

Enhance realism for an existing image.

{
    "media_id": 123
}

POST /v2/images/edit

Edit an existing image with a prompt.

{
    "media_id": 123,
    "prompt": "Change the background to a clean white studio backdrop",
    "batch_size": 1
}

Errors and rate limits

Errors return JSON with an HTTP status code.

Common statuses:

• 401: Missing or invalid API key.
• 402: Not enough credits.
• 422: Invalid request fields.
• 429: Rate limit reached.

Generation endpoints use the same credit system and safety rules as the Lucidpic interface.

Example validation error:

{
    "message": "The given data was invalid.",
    "errors": {
        "media_id": ["The selected media does not exist."]
    }
}

Example generation failure:

{
    "id": 456,
    "status": "failed",
    "error_message": "Generation failed. Please try again."
}

Additional resources

• API docs page: https://lucidpic.com/developers/api
• Markdown docs for agents: https://lucidpic.com/developers/api.md