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

The API is in early access. If Account › API keys says so, it isn't enabled for your account yet.

Quickstart

  1. 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. 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 with GET /account, which returns your plan and credits:

    Loading the example…

  3. 3

    Create an image

    A create reserves the price from your balance and queues the job: you get 202 with the generation. The Idempotency-Key makes retries safe: the same key never charges twice. Price a request first, for free, with POST /estimates.

    Loading the example…

  4. 4

    Wait for it

    ?wait=55 holds the request until the generation finishes or 55 seconds pass. Call it again while status is queued or running. A failed or canceled generation is refunded in full.

    Loading the example…

  5. 5

    Download

    Each output has a signed url that works for an hour: fetch the generation again for fresh ones. Add &download=1 to 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"
  }
}

All error codes →

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.

PlanRequests / minSpending / minIn flightRunningKeysUploads / day
free604412500 MB
pro1201216255 GB
ultra240303241010 GB
studio600606482525 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.

Webhooks guide →

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.