Developers
The Craftful API
Create images, edits, videos, songs and speech from your own code. The API runs the same models at the same prices as the website, from the same credit balance, with the same content rules.
- Base URL
- https://craftful.ai/api/v1
- OpenAPI 3.1
- /api/v1/openapi.json
The API is in early access. If Account › API keys says so, it isn't enabled for your account yet.
Quickstart
- 1
Get an API key
Create a key on Account › API keys. It's shown once: keep it in a secret manager or an environment variable named
CRAFTFUL_API_KEY. Every sample reads it from there.export CRAFTFUL_API_KEY=cf_live_…
- 2
Authenticate
Send the key as
Authorization: Bearer …on every request, from a server: the API refuses browser requests, and a key in a URL is rejected. Check it withGET /account, which returns your plan and credits:Loading the example…
- 3
Create an image
A create reserves the price from your balance and queues the job: you get
202with the generation. TheIdempotency-Keymakes retries safe: the same key never charges twice. Price a request first, for free, withPOST /estimates.Loading the example…
- 4
Wait for it
?wait=55holds the request until the generation finishes or 55 seconds pass. Call it again whilestatusisqueuedorrunning. A failed or canceled generation is refunded in full.Loading the example…
- 5
Download
Each output has a signed
urlthat works for an hour: fetch the generation again for fresh ones. Add&download=1to save it as a file.Loading the example…
Every endpoint, with samples in 13 languages: the API reference. Every model with its options and price: Models. On the website, Account › Preferences › Developer mode shows a </> button next to actions, with the API call for exactly what you're doing.
Idempotency
Requests that spend credits (POST /generations, …/regenerate, POST /lyrics, POST /voices) accept an Idempotency-Key header: 1-255 printable characters, unique per request. Retrying with the same key and body within 24 hours returns the first response (with Idempotent-Replayed: true) instead of spending again; a retry while the first is still running gets 409. The same key with a different request is 422 idempotency_key_reused.
Errors
Every error uses one envelope. Branch on code, which is stable; message is for people and may change. Quote request_id (also the X-Request-Id header) to support. Failures after a create aren't HTTP errors: they appear on the generation as status: "failed" with an error.
{
"error": {
"type": "invalid_request_error",
"code": "invalid_option",
"message": "resolution must be one of 480p, 720p, 1080p, 4k for seedance-2.5.",
"param": "options.resolution",
"details": {
"allowed": [
"480p",
"720p",
"1080p",
"4k"
]
},
"request_id": "req_01JD2V7K8Q4M9N3X5B6C7D8E9F",
"doc_url": "https://craftful.ai/developers/errors#invalid_option"
}
}Limits
Limits apply per account: every key shares them. Responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; a 429 always carries Retry-After. Running out of credits is 402, never 429.
| Plan | Requests / min | Spending / min | In flight | Running | Keys | Uploads / day |
|---|---|---|---|---|---|---|
| free | 60 | 4 | 4 | 1 | 2 | 500 MB |
| pro | 120 | 12 | 16 | 2 | 5 | 5 GB |
| ultra | 240 | 30 | 32 | 4 | 10 | 10 GB |
| studio | 600 | 60 | 64 | 8 | 25 | 25 GB |
“In flight” counts queued and running generations from every source. Jobs over your plan's running limit wait in the queue, as on the website.
Webhooks
Rather than waiting on ?wait=55, let Craftful call you: signed (Standard Webhooks) generation.succeeded, generation.failed and generation.canceled events for your API generations, with retries.
Coming soon
Craftful for AI agents (MCP)
An MCP server, built on this API, so assistants like Claude can browse models, price and create generations for you, within a budget you set per key.