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).
| Parameter | In | Type | Description |
|---|---|---|---|
| limit | query | integer (1-100) | Page size, 1-100 (default 24). |
| cursor | query | string (max 512) | The next_cursor of the previous page. Use it with the same filters. |
| reason | query | generation | refund | monthly_refill | grant | voice_clone | lyrics | purchase | subscription | referral | agent | other | Only transactions with this public reason. |
| api_key_id | query | string | Only transactions attributed to this API key. |
| created_after | query | string, date-time | Only transactions created strictly after this time. |
| created_before | query | string, date-time | Only 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).
| Parameter | In | Type | Description |
|---|---|---|---|
| start | query | string, date | First day (UTC, inclusive). Default: the first day of end's month. |
| end | query | string, date | Last day (UTC, inclusive), at most 92 days after start. Default: today. |
| group_by | query | day | model | api_key | Group rows by day (default), model or API key. |
| source | query | api | all | api (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.
| Parameter | In | Type | Description |
|---|---|---|---|
| mode | query | image | edit | video | song | speech | Only models of this mode. |
| include_unavailable | query | boolean | Include models you can't use now (default true), with available: false. |
| limit | query | integer (1-100) | Accepted and ignored: this list always comes whole. |
| cursor | query | string (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.
| Parameter | In | Type | Description |
|---|---|---|---|
| model* | path | string | The 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.
| Parameter | In | Type | Description |
|---|---|---|---|
| model* | body | string (1-64) | A model id from GET /models. |
| prompt | body | any | The prompt (lyrics for songs, the script for speech), at most the model's prompt.max_chars. |
| negative_prompt | body | any | Where the model's fields.negative_prompt is true. At most 1000 characters. |
| options | body | object | The model's options by name (see GET /models/{model}). Omitted options take their defaults. |
| inputs | body | object | Which slots a model takes, and how many refs each, is in the model's inputs. |
| lora | body | object | One of your LoRAs (GET /loras), where fields.lora is true. Paid plans. |
| voice_id | body | any | One of your song voices (GET /voices), where fields.voice_id is true. |
| style | body | any | Song style, where fields.style is true. At most 200 characters. |
| project_id | body | any | One 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.
| Parameter | In | Type | Description |
|---|---|---|---|
| model* | body | string (1-64) | A model id from GET /models. |
| prompt | body | any | The prompt (lyrics for songs, the script for speech), at most the model's prompt.max_chars. |
| negative_prompt | body | any | Where the model's fields.negative_prompt is true. At most 1000 characters. |
| options | body | object | The model's options by name (see GET /models/{model}). Omitted options take their defaults. |
| inputs | body | object | Which slots a model takes, and how many refs each, is in the model's inputs. |
| lora | body | object | One of your LoRAs (GET /loras), where fields.lora is true. Paid plans. |
| voice_id | body | any | One of your song voices (GET /voices), where fields.voice_id is true. |
| style | body | any | Song style, where fields.style is true. At most 200 characters. |
| project_id | body | any | One 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
- 400input_not_readyinvalid_idempotency_keyinvalid_inputinvalid_jsoninvalid_optioninvalid_parametermissing_inputmissing_parametermodel_retiredprompt_too_longtoo_many_inputsunknown_modelunknown_optionunknown_parameter
- 402insufficient_creditskey_monthly_limit_reached
- 403plan_required
- 404not_found
- 409idempotency_request_in_progress
- 413request_too_large
- 415unsupported_media_type
- 422content_blockedidempotency_key_reused
- 429spend_rate_limitedtoo_many_in_flight
- 503content_unverifiedupstream_unavailable
- 504upstream_timeout
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.
| Parameter | In | Type | Description |
|---|---|---|---|
| limit | query | integer (1-100) | Page size, 1-100 (default 24). |
| cursor | query | string (max 512) | The next_cursor of the previous page. Use it with the same filters. |
| status | query | queued | running | succeeded | failed | canceled | |
| mode | query | image | edit | video | song | speech | |
| model | query | string (max 64) | |
| source | query | api | web | discord | |
| project_id | query | string (max 32) | Only generations filed in this project (prj_…). |
| favorite | query | true | false | |
| deleted | query | true | false | true: only deleted generations (default false: only the others). |
| q | query | string (max 100) | Case-insensitive prompt search. |
| created_after | query | string, date-time | |
| created_before | query | string, 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.
| Parameter | In | Type | Description |
|---|---|---|---|
| id* | path | string | The generation id. |
| wait | query | integer (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
| Parameter | In | Type | Description |
|---|---|---|---|
| id* | path | string | The generation id. |
| favorite | body | boolean | |
| project_id | body | string (max 32) | prj_…, or null to unfile. |
| labels | body | object | Output 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.
| Parameter | In | Type | Description |
|---|---|---|---|
| id* | path | string | The 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.
| Parameter | In | Type | Description |
|---|---|---|---|
| id* | path | string | The 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.
| Parameter | In | Type | Description |
|---|---|---|---|
| id* | path | string | The 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
- 400cannot_regenerateinvalid_idempotency_keyinvalid_jsoninvalid_parametermissing_parameterunknown_parameter
- 402insufficient_creditskey_monthly_limit_reached
- 403plan_required
- 404not_found
- 409idempotency_request_in_progress
- 413request_too_large
- 415unsupported_media_type
- 422content_blockedidempotency_key_reused
- 429spend_rate_limitedtoo_many_in_flight
- 503content_unverifiedupstream_unavailable
- 504upstream_timeout
Restore a deleted generation
POST/api/v1/generations/{id}/restore
scope gallery:write
| Parameter | In | Type | Description |
|---|---|---|---|
| id* | path | string | The 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.
| Parameter | In | Type | Description |
|---|---|---|---|
| id* | path | string | The generation id. |
| index* | path | string | The output index. |
| t | query | string | Seconds into the video (default 0). |
| download | query | 1 | true | Save 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.
| Parameter | In | Type | Description |
|---|---|---|---|
| idea* | body | string | What the song is about, 1-600 characters. |
| style | body | any | Style 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.
| Parameter | In | Type | Description |
|---|---|---|---|
| file* | form | string | The file. |
| data* | body | string | The file, base64-encoded (at most 20 MB decoded). |
| mime_type | body | string (max 100) | The declared type; it must match the bytes. |
| filename | body | string (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).
| Parameter | In | Type | Description |
|---|---|---|---|
| limit | query | integer (1-100) | Accepted and ignored: this list always comes whole. |
| cursor | query | string (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.
| Parameter | In | Type | Description |
|---|---|---|---|
| limit | query | integer (1-100) | Accepted and ignored: this list always comes whole. |
| cursor | query | string (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
| Parameter | In | Type | Description |
|---|---|---|---|
| name* | body | string | 1-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
| Parameter | In | Type | Description |
|---|---|---|---|
| id* | path | string | The project id. |
| name* | body | string | 1-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.
| Parameter | In | Type | Description |
|---|---|---|---|
| id* | path | string | The 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
| Parameter | In | Type | Description |
|---|---|---|---|
| limit | query | integer (1-100) | Accepted and ignored: this list always comes whole. |
| cursor | query | string (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.
| Parameter | In | Type | Description |
|---|---|---|---|
| name* | form | string | 1-80 characters. |
| file* | form | string | MP3 or M4A, at most 10 MB. |
| name* | body | string | 1-80 characters. |
| upload_id* | body | string | An 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
- 400invalid_idempotency_keyinvalid_inputinvalid_jsoninvalid_parametermissing_parameterunknown_parameterupload_empty
- 402insufficient_creditskey_monthly_limit_reached
- 403plan_required
- 404not_found
- 409idempotency_request_in_progressvoice_limit_reached
- 413file_too_largerequest_too_large
- 415unsupported_file_typeunsupported_media_type
- 422idempotency_key_reused
- 429spend_rate_limited
- 503upstream_unavailable
- 504upstream_timeout
Delete a song voice
DELETE/api/v1/voices/{id}
scope gallery:write
| Parameter | In | Type | Description |
|---|---|---|---|
| id* | path | string | The voice id. |
Request
Loading the example…
Response 200
Deleted.
{
"id": "voice_7",
"object": "voice",
"deleted": true
}