Developers

API reference

Base URL https://craftful.ai/api/v1. Authenticate with Authorization: Bearer $CRAFTFUL_API_KEY. Bodies are JSON (snake_case); unknown fields are refused. The full contract is the OpenAPI document; each model's own options are on Models.

Any endpoint can also answer: api_key_in_url, missing_api_key, invalid_api_key, api_key_expired, api_key_revoked, insufficient_scope, account_banned, api_not_enabled, browser_requests_not_allowed, rate_limited, too_many_auth_failures, internal_error.

Account

Your plan, credits, credit history and API usage.

Get your account

GET/api/v1/account

scope account:read

Your plan, credit balance (monthly and purchased parts), plan features and limits, and the calling API key with its spend this month.

Request

Loading the example…

Response 200

The account.

{
  "object": "account",
  "user_id": "167447843848716288",
  "plan": "pro",
  "credits": {
    "balance": 1340,
    "monthly_remaining": 840,
    "purchased_remaining": 500,
    "monthly_allotment": 1500,
    "refills_at": "2026-12-01T00:05:00.000Z"
  },
  "features": {
    "video": true,
    "adult_content": true,
    "loras": true,
    "voice_cloning": true
  },
  "limits": {
    "api_keys": 5,
    "requests_per_minute": 120,
    "spending_requests_per_minute": 12,
    "generations_in_flight": 16,
    "running_generations": 2
  },
  "api_key": {
    "id": "key_8sT2kQ9vXc1mZ4pL",
    "name": "Render farm",
    "scopes": [
      "models:read",
      "generations:read",
      "generations:write",
      "uploads:write"
    ],
    "expires_at": "2027-02-09T10:00:00.000Z",
    "monthly_credit_limit": 5000,
    "credits_used_this_month": 1220
  }
}

Errors

List credit transactions

GET/api/v1/credits/transactions

scope account:read

Your credit ledger, newest first, paginated. Each row is a debit or a credit with the balance after it. Internal reasons are mapped to public ones (generation, refund, monthly_refill, grant, voice_clone, lyrics, purchase, subscription, referral, agent, other).

Parameters of List credit transactions
ParameterInTypeDescription
limitqueryinteger (1-100)Page size, 1-100 (default 24).
cursorquerystring (max 512)The next_cursor of the previous page. Use it with the same filters.
reasonquerygeneration | refund | monthly_refill | grant | voice_clone | lyrics | purchase | subscription | referral | agent | otherOnly transactions with this public reason.
api_key_idquerystringOnly transactions attributed to this API key.
created_afterquerystring, date-timeOnly transactions created strictly after this time.
created_beforequerystring, date-timeOnly transactions created strictly before this time.

Request

Loading the example…

Response 200

A page of transactions.

{
  "object": "list",
  "data": [
    {
      "id": "txn_99812",
      "object": "credit_transaction",
      "delta": -270,
      "reason": "generation",
      "generation_id": "gen_812345",
      "api_key_id": "key_8sT2kQ9vXc1mZ4pL",
      "balance_after": 1070,
      "created_at": "2026-11-12T10:15:03.120Z"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJjIjoiMjAyNi0xMS0xMlQxMDoxNDo1NS40MTAyMzEiLCJpIjo4MTIzNDV9"
}

Errors

Get usage

GET/api/v1/usage

scope account:read

Credits (net of refunds) and generations per day, model or API key, over at most 92 days (UTC dates, inclusive). By default only API usage counts (source=api).

Parameters of Get usage
ParameterInTypeDescription
startquerystring, dateFirst day (UTC, inclusive). Default: the first day of end's month.
endquerystring, dateLast day (UTC, inclusive), at most 92 days after start. Default: today.
group_byqueryday | model | api_keyGroup rows by day (default), model or API key.
sourcequeryapi | allapi (default): only API usage. all: website and Discord too.

Request

Loading the example…

Response 200

Usage over the range.

{
  "object": "usage",
  "start": "2026-11-01",
  "end": "2026-11-30",
  "source": "api",
  "group_by": "model",
  "data": [
    {
      "model": "seedance-2.5",
      "credits": 540,
      "refunded_credits": 0,
      "generations": 2
    },
    {
      "model": null,
      "credits": 3,
      "refunded_credits": 0,
      "generations": 0
    }
  ]
}

Errors

Models

The model catalog: options, inputs and prices.

List models

GET/api/v1/models

scope models:read

Every model, in the website's order (the first of each mode is its default). Models your plan can't use are included with available: false unless include_unavailable=false. Prices may lag by up to 5 minutes; use POST /estimates for an exact quote.

Parameters of List models
ParameterInTypeDescription
modequeryimage | edit | video | song | speechOnly models of this mode.
include_unavailablequerybooleanInclude models you can't use now (default true), with available: false.
limitqueryinteger (1-100)Accepted and ignored: this list always comes whole.
cursorquerystring (max 512)Accepted and ignored: this list always comes whole.

Request

Loading the example…

Response 200

The models.

{
  "object": "list",
  "data": [
    {
      "id": "z-image-turbo",
      "object": "model",
      "name": "Z-Image Turbo",
      "mode": "image",
      "description": "Fast, high-quality text-to-image.",
      "is_default": true,
      "available": true,
      "unavailable_reason": null,
      "plans": [
        "free",
        "pro",
        "ultra",
        "studio"
      ],
      "adult_only": false,
      "companion_model": null,
      "discount_percent": 0,
      "default_credits": 1,
      "prompt": {
        "required": true,
        "label": "Prompt",
        "max_chars": 4000
      },
      "options": [
        {
          "name": "aspect_ratio",
          "label": "Aspect ratio",
          "type": "enum",
          "values": [
            "1:1",
            "16:9",
            "9:16",
            "4:3",
            "3:4",
            "21:9"
          ],
          "default": "1:1"
        },
        {
          "name": "quality",
          "label": "Quality",
          "type": "enum",
          "values": [
            "fast",
            "standard",
            "high"
          ],
          "value_labels": {
            "fast": "Fast · 768px",
            "standard": "Standard · 1024px",
            "high": "High · 1536px"
          },
          "default": "standard"
        },
        {
          "name": "count",
          "label": "Images",
          "type": "enum",
          "values": [
            "1",
            "2",
            "4"
          ],
          "default": "1",
          "numeric": true
        }
      ],
      "inputs": {
        "images": null,
        "start_image": null,
        "end_image": null,
        "videos": null,
        "audios": null,
        "needs_one_of": [],
        "max_total_files": null,
        "exclusive": [],
        "notes": []
      },
      "fields": {
        "negative_prompt": true,
        "lora": false,
        "voice_id": false,
        "style": false
      },
      "deprecation": null
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Errors

Get a model

GET/api/v1/models/{model}

scope models:read

One model: its options and their allowed values, the media inputs it takes, and its default price.

Parameters of Get a model
ParameterInTypeDescription
model*pathstringThe model id.

Request

Loading the example…

Response 200

The model.

{
  "id": "z-image-turbo",
  "object": "model",
  "name": "Z-Image Turbo",
  "mode": "image",
  "description": "Fast, high-quality text-to-image.",
  "is_default": true,
  "available": true,
  "unavailable_reason": null,
  "plans": [
    "free",
    "pro",
    "ultra",
    "studio"
  ],
  "adult_only": false,
  "companion_model": null,
  "discount_percent": 0,
  "default_credits": 1,
  "prompt": {
    "required": true,
    "label": "Prompt",
    "max_chars": 4000
  },
  "options": [
    {
      "name": "aspect_ratio",
      "label": "Aspect ratio",
      "type": "enum",
      "values": [
        "1:1",
        "16:9",
        "9:16",
        "4:3",
        "3:4",
        "21:9"
      ],
      "default": "1:1"
    },
    {
      "name": "quality",
      "label": "Quality",
      "type": "enum",
      "values": [
        "fast",
        "standard",
        "high"
      ],
      "value_labels": {
        "fast": "Fast · 768px",
        "standard": "Standard · 1024px",
        "high": "High · 1536px"
      },
      "default": "standard"
    },
    {
      "name": "count",
      "label": "Images",
      "type": "enum",
      "values": [
        "1",
        "2",
        "4"
      ],
      "default": "1",
      "numeric": true
    }
  ],
  "inputs": {
    "images": null,
    "start_image": null,
    "end_image": null,
    "videos": null,
    "audios": null,
    "needs_one_of": [],
    "max_total_files": null,
    "exclusive": [],
    "notes": []
  },
  "fields": {
    "negative_prompt": true,
    "lora": false,
    "voice_id": false,
    "style": false
  },
  "deprecation": null
}

Errors

Generations

Price, create, wait for, download and organize generations; lyrics.

Price a generation (dry run)

POST/api/v1/estimates

scope models:read

Takes exactly the body of POST /generations and runs every check a create runs except moderation, then returns the exact price and whether the create would go through right now. Free: no charge, no generation. balance needs account:read.

Parameters of Price a generation (dry run)
ParameterInTypeDescription
model*bodystring (1-64)A model id from GET /models.
promptbodyanyThe prompt (lyrics for songs, the script for speech), at most the model's prompt.max_chars.
negative_promptbodyanyWhere the model's fields.negative_prompt is true. At most 1000 characters.
optionsbodyobjectThe model's options by name (see GET /models/{model}). Omitted options take their defaults.
inputsbodyobjectWhich slots a model takes, and how many refs each, is in the model's inputs.
lorabodyobjectOne of your LoRAs (GET /loras), where fields.lora is true. Paid plans.
voice_idbodyanyOne of your song voices (GET /voices), where fields.voice_id is true.
stylebodyanySong style, where fields.style is true. At most 200 characters.
project_idbodyanyOne of your projects: the generation is filed there.

Request

Loading the example…

Response 200

The price, and what would block a create.

{
  "object": "estimate",
  "model": "z-image-turbo",
  "credits": 1,
  "list_credits": 1,
  "discount_percent": 0,
  "upper_bound": false,
  "balance": 1340,
  "would_succeed": true,
  "blocking_error": null
}

Errors

Create a generation

POST/api/v1/generations

scope generations:writeSpends creditsIdempotency-Key

Validates the request against the model (GET /models/{model}), reserves its price from your balance and queues it: 202 with the generation and a Location header. Wait for it with GET /generations/{id}?wait=55. Send an Idempotency-Key so a retry never charges twice. A failed or canceled generation is refunded in full.

Parameters of Create a generation
ParameterInTypeDescription
model*bodystring (1-64)A model id from GET /models.
promptbodyanyThe prompt (lyrics for songs, the script for speech), at most the model's prompt.max_chars.
negative_promptbodyanyWhere the model's fields.negative_prompt is true. At most 1000 characters.
optionsbodyobjectThe model's options by name (see GET /models/{model}). Omitted options take their defaults.
inputsbodyobjectWhich slots a model takes, and how many refs each, is in the model's inputs.
lorabodyobjectOne of your LoRAs (GET /loras), where fields.lora is true. Paid plans.
voice_idbodyanyOne of your song voices (GET /voices), where fields.voice_id is true.
stylebodyanySong style, where fields.style is true. At most 200 characters.
project_idbodyanyOne of your projects: the generation is filed there.

Request

Loading the example…

Response 202

Accepted: the generation, usually queued.

{
  "id": "gen_812345",
  "object": "generation",
  "status": "queued",
  "mode": "image",
  "model": "z-image-turbo",
  "prompt": "a lighthouse in a storm, oil painting",
  "negative_prompt": null,
  "options": {
    "aspect_ratio": "16:9",
    "quality": "standard",
    "count": "1"
  },
  "inputs": null,
  "lora": null,
  "voice_id": null,
  "style": null,
  "source": "api",
  "api_key_id": "key_8sT2kQ9vXc1mZ4pL",
  "project_id": null,
  "favorite": false,
  "labels": {},
  "deleted": false,
  "cost_credits": 1,
  "credits_charged": 1,
  "credits_refunded": 0,
  "outputs": [],
  "error": null,
  "estimated_duration_seconds": 9,
  "created_at": "2026-11-12T10:14:55.410Z",
  "started_at": null,
  "completed_at": null
}

Errors

List generations

GET/api/v1/generations

scope generations:read

Your gallery, newest first, paginated: website and API generations, plus Discord ones with stored media. Deleted generations only with deleted=true.

Parameters of List generations
ParameterInTypeDescription
limitqueryinteger (1-100)Page size, 1-100 (default 24).
cursorquerystring (max 512)The next_cursor of the previous page. Use it with the same filters.
statusqueryqueued | running | succeeded | failed | canceled
modequeryimage | edit | video | song | speech
modelquerystring (max 64)
sourcequeryapi | web | discord
project_idquerystring (max 32)Only generations filed in this project (prj_…).
favoritequerytrue | false
deletedquerytrue | falsetrue: only deleted generations (default false: only the others).
qquerystring (max 100)Case-insensitive prompt search.
created_afterquerystring, date-time
created_beforequerystring, date-time

Request

Loading the example…

Response 200

A page of generations.

{
  "object": "list",
  "data": [
    {
      "id": "gen_812345",
      "object": "generation",
      "status": "succeeded",
      "mode": "image",
      "model": "z-image-turbo",
      "prompt": "a lighthouse in a storm, oil painting",
      "negative_prompt": null,
      "options": {
        "aspect_ratio": "16:9",
        "quality": "standard",
        "count": "1"
      },
      "inputs": null,
      "lora": null,
      "voice_id": null,
      "style": null,
      "source": "api",
      "api_key_id": "key_8sT2kQ9vXc1mZ4pL",
      "project_id": null,
      "favorite": false,
      "labels": {},
      "deleted": false,
      "cost_credits": 1,
      "credits_charged": 1,
      "credits_refunded": 0,
      "outputs": [
        {
          "index": 0,
          "type": "image",
          "mime_type": "image/webp",
          "url": "https://craftful.ai/api/media/812345?i=0&exp=1794482103&sig=Qm9yZWFsaXMtbGlnaHQ",
          "urls_expire_at": "2026-11-12T11:15:03.000Z"
        }
      ],
      "error": null,
      "estimated_duration_seconds": null,
      "created_at": "2026-11-12T10:14:55.410Z",
      "started_at": "2026-11-12T10:14:56.020Z",
      "completed_at": "2026-11-12T10:15:03.120Z"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJjIjoiMjAyNi0xMS0xMlQxMDoxNDo1NS40MTAyMzEiLCJpIjo4MTIzNDV9"
}

Errors

Get a generation

GET/api/v1/generations/{id}

scope generations:read

With wait, the request is held until the generation finishes or the wait ends (at most 55 s). A generation that isn't finished carries Retry-After. Output URLs expire after an hour: fetch the generation again for fresh ones.

Parameters of Get a generation
ParameterInTypeDescription
id*pathstringThe generation id.
waitqueryinteger (0-55)Long-poll: wait up to this many seconds (0-55) for the generation to finish.

Request

Loading the example…

Response 200

The generation.

{
  "id": "gen_812345",
  "object": "generation",
  "status": "succeeded",
  "mode": "image",
  "model": "z-image-turbo",
  "prompt": "a lighthouse in a storm, oil painting",
  "negative_prompt": null,
  "options": {
    "aspect_ratio": "16:9",
    "quality": "standard",
    "count": "1"
  },
  "inputs": null,
  "lora": null,
  "voice_id": null,
  "style": null,
  "source": "api",
  "api_key_id": "key_8sT2kQ9vXc1mZ4pL",
  "project_id": null,
  "favorite": false,
  "labels": {},
  "deleted": false,
  "cost_credits": 1,
  "credits_charged": 1,
  "credits_refunded": 0,
  "outputs": [
    {
      "index": 0,
      "type": "image",
      "mime_type": "image/webp",
      "url": "https://craftful.ai/api/media/812345?i=0&exp=1794482103&sig=Qm9yZWFsaXMtbGlnaHQ",
      "urls_expire_at": "2026-11-12T11:15:03.000Z"
    }
  ],
  "error": null,
  "estimated_duration_seconds": null,
  "created_at": "2026-11-12T10:14:55.410Z",
  "started_at": "2026-11-12T10:14:56.020Z",
  "completed_at": "2026-11-12T10:15:03.120Z"
}

Errors

Favorite, file or name a generation

PATCH/api/v1/generations/{id}

scope gallery:write

Parameters of Favorite, file or name a generation
ParameterInTypeDescription
id*pathstringThe generation id.
favoritebodyboolean
project_idbodystring (max 32)prj_…, or null to unfile.
labelsbodyobjectOutput index → name (at most 60 characters); "" clears one.

Request

Loading the example…

Response 200

The updated generation. For a key without generations:read, prompt, negative_prompt, style, inputs, lora and voice_id are null and outputs is empty.

{
  "id": "gen_812345",
  "object": "generation",
  "status": "succeeded",
  "mode": "image",
  "model": "z-image-turbo",
  "prompt": "a lighthouse in a storm, oil painting",
  "negative_prompt": null,
  "options": {
    "aspect_ratio": "16:9",
    "quality": "standard",
    "count": "1"
  },
  "inputs": null,
  "lora": null,
  "voice_id": null,
  "style": null,
  "source": "api",
  "api_key_id": "key_8sT2kQ9vXc1mZ4pL",
  "project_id": null,
  "favorite": true,
  "labels": {},
  "deleted": false,
  "cost_credits": 1,
  "credits_charged": 1,
  "credits_refunded": 0,
  "outputs": [
    {
      "index": 0,
      "type": "image",
      "mime_type": "image/webp",
      "url": "https://craftful.ai/api/media/812345?i=0&exp=1794482103&sig=Qm9yZWFsaXMtbGlnaHQ",
      "urls_expire_at": "2026-11-12T11:15:03.000Z"
    }
  ],
  "error": null,
  "estimated_duration_seconds": null,
  "created_at": "2026-11-12T10:14:55.410Z",
  "started_at": "2026-11-12T10:14:56.020Z",
  "completed_at": "2026-11-12T10:15:03.120Z"
}

Errors

Delete a generation

DELETE/api/v1/generations/{id}

scope gallery:write

A soft delete: POST /generations/{id}/restore brings it back. Its output URLs stop working.

Parameters of Delete a generation
ParameterInTypeDescription
id*pathstringThe generation id.

Request

Loading the example…

Response 200

Deleted.

{
  "id": "gen_812345",
  "object": "generation",
  "deleted": true
}

Errors

Cancel a queued generation

POST/api/v1/generations/{id}/cancel

scope generations:write

Only generations created through the API that are still queued; they are refunded in full. Canceling twice returns the canceled generation again.

Parameters of Cancel a queued generation
ParameterInTypeDescription
id*pathstringThe generation id.

Request

Loading the example…

Response 200

The canceled generation.

{
  "id": "gen_812345",
  "object": "generation",
  "status": "canceled",
  "mode": "image",
  "model": "z-image-turbo",
  "prompt": "a lighthouse in a storm, oil painting",
  "negative_prompt": null,
  "options": {
    "aspect_ratio": "16:9",
    "quality": "standard",
    "count": "1"
  },
  "inputs": null,
  "lora": null,
  "voice_id": null,
  "style": null,
  "source": "api",
  "api_key_id": "key_8sT2kQ9vXc1mZ4pL",
  "project_id": null,
  "favorite": false,
  "labels": {},
  "deleted": false,
  "cost_credits": 1,
  "credits_charged": 0,
  "credits_refunded": 1,
  "outputs": [],
  "error": null,
  "estimated_duration_seconds": null,
  "created_at": "2026-11-12T10:14:55.410Z",
  "started_at": null,
  "completed_at": null
}

Errors

Regenerate

POST/api/v1/generations/{id}/regenerate

scope generations:writeSpends creditsIdempotency-Key

A new generation with the same model, prompt, options and inputs as this one (from any source), at today's price.

Parameters of Regenerate
ParameterInTypeDescription
id*pathstringThe generation id.

Request

Loading the example…

Response 202

Accepted: the new generation.

{
  "id": "gen_812346",
  "object": "generation",
  "status": "queued",
  "mode": "image",
  "model": "z-image-turbo",
  "prompt": "a lighthouse in a storm, oil painting",
  "negative_prompt": null,
  "options": {
    "aspect_ratio": "16:9",
    "quality": "standard",
    "count": "1"
  },
  "inputs": null,
  "lora": null,
  "voice_id": null,
  "style": null,
  "source": "api",
  "api_key_id": "key_8sT2kQ9vXc1mZ4pL",
  "project_id": null,
  "favorite": false,
  "labels": {},
  "deleted": false,
  "cost_credits": 1,
  "credits_charged": 1,
  "credits_refunded": 0,
  "outputs": [],
  "error": null,
  "estimated_duration_seconds": 9,
  "created_at": "2026-11-12T10:14:55.410Z",
  "started_at": null,
  "completed_at": null
}

Errors

Restore a deleted generation

POST/api/v1/generations/{id}/restore

scope gallery:write

Parameters of Restore a deleted generation
ParameterInTypeDescription
id*pathstringThe generation id.

Request

Loading the example…

Response 200

The restored generation. For a key without generations:read, prompt, negative_prompt, style, inputs, lora and voice_id are null and outputs is empty.

{
  "id": "gen_812345",
  "object": "generation",
  "status": "succeeded",
  "mode": "image",
  "model": "z-image-turbo",
  "prompt": "a lighthouse in a storm, oil painting",
  "negative_prompt": null,
  "options": {
    "aspect_ratio": "16:9",
    "quality": "standard",
    "count": "1"
  },
  "inputs": null,
  "lora": null,
  "voice_id": null,
  "style": null,
  "source": "api",
  "api_key_id": "key_8sT2kQ9vXc1mZ4pL",
  "project_id": null,
  "favorite": false,
  "labels": {},
  "deleted": false,
  "cost_credits": 1,
  "credits_charged": 1,
  "credits_refunded": 0,
  "outputs": [
    {
      "index": 0,
      "type": "image",
      "mime_type": "image/webp",
      "url": "https://craftful.ai/api/media/812345?i=0&exp=1794482103&sig=Qm9yZWFsaXMtbGlnaHQ",
      "urls_expire_at": "2026-11-12T11:15:03.000Z"
    }
  ],
  "error": null,
  "estimated_duration_seconds": null,
  "created_at": "2026-11-12T10:14:55.410Z",
  "started_at": "2026-11-12T10:14:56.020Z",
  "completed_at": "2026-11-12T10:15:03.120Z"
}

Errors

Get a frame of a video

GET/api/v1/generations/{id}/outputs/{index}/frame

scope generations:read

A JPEG of the video output at t seconds. Has its own per-minute limit.

Parameters of Get a frame of a video
ParameterInTypeDescription
id*pathstringThe generation id.
index*pathstringThe output index.
tquerystringSeconds into the video (default 0).
downloadquery1 | trueSave as a file (Content-Disposition: attachment).

Request

Loading the example…

Response 200

The frame.

A image/jpeg file.

Errors

Write song lyrics

POST/api/v1/lyrics

scope generations:writeSpends creditsIdempotency-Key

AI-written lyrics with [Verse]/[Chorus] tags, for a few credits (3 today). Charged once per Idempotency-Key; if the writer fails you get 503 lyrics_unavailable and the credits back. Pass the lyrics to a song model as prompt.

Parameters of Write song lyrics
ParameterInTypeDescription
idea*bodystringWhat the song is about, 1-600 characters.
stylebodyanyStyle or genre, at most 200 characters.

Request

Loading the example…

Response 200

The lyrics.

{
  "object": "lyrics",
  "lyrics": "[Verse 1]\nThe lamp turns slow above the foam\n[Chorus]\nSing to me, sea, and bring them home",
  "credits_charged": 3
}

Errors

Uploads

Reference files to use as generation inputs.

Upload a reference file

POST/api/v1/uploads

scope uploads:write

Multipart (file) or JSON base64 (at most 20 MB decoded). The type is read from the file's bytes: PNG, JPEG or WebP images (20 MB), MP4, QuickTime or WebM video (100 MB), MP3, WAV or M4A audio (25 MB). Use the returned upl_… id in inputs. There is a daily upload volume per plan.

Parameters of Upload a reference file
ParameterInTypeDescription
file*formstringThe file.
data*bodystringThe file, base64-encoded (at most 20 MB decoded).
mime_typebodystring (max 100)The declared type; it must match the bytes.
filenamebodystring (max 255)For your reference only.

Send the body as multipart/form-data or application/json.

Request

Loading the example…

Response 201

The upload.

{
  "id": "upl_3fK9mQ2xT7bL1vRz",
  "object": "upload",
  "kind": "image",
  "mime_type": "image/png",
  "size_bytes": 482113,
  "sha256": "9f2c1d7e3b8a4f6c0e5d2b9a7c4e1f3a8b6d0c2e4f7a9b1c3d5e7f9a0b2c4d6e",
  "created_at": "2026-11-12T10:15:03.120Z"
}

Errors

Library

Your projects, LoRAs and song voices.

List your LoRAs

GET/api/v1/loras

scope library:read

Your FLUX LoRAs. Use one through lora on flux-dev (paid plans).

Parameters of List your LoRAs
ParameterInTypeDescription
limitqueryinteger (1-100)Accepted and ignored: this list always comes whole.
cursorquerystring (max 512)Accepted and ignored: this list always comes whole.

Request

Loading the example…

Response 200

Your LoRAs.

{
  "object": "list",
  "data": [
    {
      "id": "lora_12",
      "object": "lora",
      "name": "my-style",
      "base_model": "flux-dev"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Errors

List your projects

GET/api/v1/projects

scope library:read

Your projects, newest first, with how many creations each holds.

Parameters of List your projects
ParameterInTypeDescription
limitqueryinteger (1-100)Accepted and ignored: this list always comes whole.
cursorquerystring (max 512)Accepted and ignored: this list always comes whole.

Request

Loading the example…

Response 200

Your projects.

{
  "object": "list",
  "data": [
    {
      "id": "prj_14",
      "object": "project",
      "name": "Album art",
      "generation_count": 37,
      "created_at": "2026-11-12T10:15:03.120Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Errors

Create a project

POST/api/v1/projects

scope gallery:write

Parameters of Create a project
ParameterInTypeDescription
name*bodystring1-80 characters.

Request

Loading the example…

Response 201

The new project.

{
  "id": "prj_14",
  "object": "project",
  "name": "Album art",
  "generation_count": 0,
  "created_at": "2026-11-12T10:15:03.120Z"
}

Errors

Rename a project

PATCH/api/v1/projects/{id}

scope gallery:write

Parameters of Rename a project
ParameterInTypeDescription
id*pathstringThe project id.
name*bodystring1-80 characters.

Request

Loading the example…

Response 200

The renamed project.

{
  "id": "prj_14",
  "object": "project",
  "name": "Album art (final)",
  "generation_count": 37,
  "created_at": "2026-11-12T10:15:03.120Z"
}

Errors

Delete a project

DELETE/api/v1/projects/{id}

scope gallery:write

Unfiles its creations (they stay in your gallery), then deletes the project.

Parameters of Delete a project
ParameterInTypeDescription
id*pathstringThe project id.

Request

Loading the example…

Response 200

The project was deleted.

{
  "id": "prj_14",
  "object": "project",
  "deleted": true
}

Errors

List your song voices

GET/api/v1/voices

scope library:read

Parameters of List your song voices
ParameterInTypeDescription
limitqueryinteger (1-100)Accepted and ignored: this list always comes whole.
cursorquerystring (max 512)Accepted and ignored: this list always comes whole.

Request

Loading the example…

Response 200

Your voices.

{
  "object": "list",
  "data": [
    {
      "id": "voice_7",
      "object": "voice",
      "name": "Stage voice",
      "provider": "mureka",
      "created_at": "2026-11-12T10:15:03.120Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Errors

Clone a singing voice

POST/api/v1/voices

scope generations:writeSpends creditsIdempotency-Key

From an MP3 or M4A sample of at most 10 MB (as on the website): multipart name + file, or JSON name + upload_id. Paid plans; 750 credits, charged once per Idempotency-Key and refunded if the clone fails. At most 25 voices.

Parameters of Clone a singing voice
ParameterInTypeDescription
name*formstring1-80 characters.
file*formstringMP3 or M4A, at most 10 MB.
name*bodystring1-80 characters.
upload_id*bodystringAn MP3 or M4A upload (upl_…) of at most 10 MB.

Send the body as multipart/form-data or application/json.

Request

Loading the example…

Response 201

The new voice.

{
  "id": "voice_8",
  "object": "voice",
  "name": "Stage voice",
  "provider": "mureka",
  "created_at": "2026-11-12T10:15:03.120Z",
  "credits_charged": 750
}

Errors

Delete a song voice

DELETE/api/v1/voices/{id}

scope gallery:write

Parameters of Delete a song voice
ParameterInTypeDescription
id*pathstringThe voice id.

Request

Loading the example…

Response 200

Deleted.

{
  "id": "voice_7",
  "object": "voice",
  "deleted": true
}

Errors