Developer API

NewWorkflow runs, file uploads and history in the API and MCP server

Pixraft for developers and AI agents

One API key gives your code, your terminal and your AI agent the same 750+ models as the studios, billed in the same credits at the same prices.

Quick start

  1. Create a key in Profile → API keys.
  2. Find a model.
    curl "https://pixraft.app/api/v1/models?type=image"
  3. Generate.
    curl -X POST https://pixraft.app/api/v1/generations \
      -H "Authorization: Bearer $PIXRAFT_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"modelId":"<id>","params":{"prompt":"a red fox in snow"},"maxCredits":20}'
  4. Poll GET /api/v1/generations/{generationId} until status is completed, failed or moderated.

Authentication

Send your key in the Authorization header of every request that needs an account, or, in Claude's connector window, the connector link shown when you create a key.

Authorization: Bearer pxr_…
  • Each key is shown once, when you create it. You can revoke it at any time.
  • You can have up to 10 keys per account.
  • Keys are created and revoked in Profile → API keys, from a signed-in browser session. An API key cannot manage keys.
  • Never put a key in browser code. Keep it on a server or in your terminal.

Endpoints

MethodPathDescription
GET/api/v1/modelsSearch the catalog. Query: type (image, video, audio or lipsync) and q. Public.
GET/api/v1/models/{id}One model with its inputs and required fields. Public.
GET/api/v1/balanceYour credit balance.
POST/api/v1/quoteSend { modelId, params } and get the credits it would cost. Free.
POST/api/v1/generationsSend { modelId, params, maxCredits? }. Returns 202 { generationId, creditsCharged }. An instant model returns 200 { generationId, creditsCharged, status: 'completed', url }. Any model can return 200 { generationId, creditsCharged: 0, status: 'moderated', reason? } with no url when the provider refuses the prompt or input, or the output is blocked; it is refunded.
GET/api/v1/generations/{id}Returns { status, url?, creditsCharged, reason? }. A failed or moderated generation includes a short human-readable reason. Output URLs are temporary signed links, so download them promptly.
GET/api/v1/generationsYour history, newest first. Query: limit (up to 50), page and type. Returns { generations, total, page, limit }; failed and moderated generations show 0 credits because they were refunded.
POST/api/v1/uploadsSend { filename, contentType, contentLength } (the size in bytes, up to 100 MB). Returns { uploadUrl, key, viewUrl }: PUT exactly that many bytes to uploadUrl within an hour, then pass viewUrl as a model input or key as a workflow file input.

Reference files

Image-to-video, edits and lip sync take a reference file. Pass any public https URL, or upload a local file first:

curl -X POST https://pixraft.app/api/v1/uploads \
  -H "Authorization: Bearer $PIXRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename":"photo.png","contentType":"image/png","contentLength":48213}'
# contentLength is the file size in bytes (wc -c < photo.png)
# → { "uploadUrl": "…", "key": "inputs/…/….png", "viewUrl": "…" }

curl -X PUT -H "Content-Type: image/png" --upload-file ./photo.png "<uploadUrl>"

Allowed types: jpeg, png, gif, webp and avif images; mp4, webm and mov video; mp3, wav, ogg, webm and m4a audio. Up to 100 MB per file.

Workflows

Run multi-step pipelines from Workflow Studio, such as prompt → image → video or script → voice → lip sync, with one call. Each step is charged like a single generation, and a run pauses instead of going over its maxCredits cap.

MethodPathDescription
GET/api/v1/workflows/templatesStarter workflows and the run inputs each one takes. Public.
GET/api/v1/workflowsYour saved workflows.
POST/api/v1/workflowsSend { templateKey } to copy a template, or { name, graph } to save your own.
GET/api/v1/workflows/{id}One workflow and its runInputs: the node ids a run asks for.
POST/api/v1/workflows/{id}/quoteSend { inputs } and get { credits, approximate, perNode }. Free.
POST/api/v1/workflows/{id}/runsSend { inputs, maxCredits }. Returns 201 with the run. maxCredits is required and must cover the quote.
GET/api/v1/workflows/runs/{runId}The run's status, steps, credits and output URLs. Each call also moves the run forward, so poll it every few seconds until it is completed, failed or canceled.
POST/api/v1/workflows/runs/{runId}/continueResume a paused run with { maxCredits }, at least its current cap.
POST/api/v1/workflows/runs/{runId}/cancelCancel a running or paused run. Steps not yet started are never charged.
# Copy a template, then run it with its one text input
curl -X POST https://pixraft.app/api/v1/workflows \
  -H "Authorization: Bearer $PIXRAFT_API_KEY" -H "Content-Type: application/json" \
  -d '{"templateKey":"prompt-image-video"}'

curl -X POST https://pixraft.app/api/v1/workflows/<id>/runs \
  -H "Authorization: Bearer $PIXRAFT_API_KEY" -H "Content-Type: application/json" \
  -d '{"inputs":{"t1":{"value":"a red fox in snow"}},"maxCredits":80}'

A text input is { "value": "…" }; a file input is { "r2Key": "<key>" } from an upload. Up to 3 runs can go at once.

Credits and safety

  • API calls spend the same credits at the same prices as the studios.
  • Set maxCredits on a generation. If the price is above it, the call is refused with 409 price_above_max before anything is charged.
  • Failed and moderated generations are refunded.
  • Rate limits, per account: 20 generations per minute, 60 quotes per minute, 120 status polls per minute and 60 balance checks per minute.
  • Also per account: 30 uploads, 60 history pages, 10 workflow run starts and 120 run status checks per minute.
StatusMeaning
400Bad input.
401Missing or invalid API key.
402Not enough credits.
409price_above_max: the price is above your maxCredits. Nothing is charged. For a workflow run, cap_below_quote means the same, and too_many_runs means 3 runs are already going.
413storage_full: your storage is full. From /api/v1/uploads, file_too_large: the declared contentLength is over 100 MB.
422The model rejected these parameters, or the model is unavailable upstream. Nothing is charged. Change the parameters (or the model) rather than retrying unchanged.
429Rate limited. Retry shortly.
502The model provider is unavailable. Nothing is charged. Retry shortly.

MCP server

Connect Claude, Cursor and other AI agents to https://pixraft.app/api/mcp (Streamable HTTP). There is no OAuth sign-in yet. In Claude (web or desktop), add a custom connector and paste your connector link: https://pixraft.app/api/mcp/k/<your API key>, which Profile shows when you create a key. Other clients send the key in the Authorization header.

Claude — Settings → Connectors → Add custom connector

https://pixraft.app/api/mcp/k/pxr_…

The connector link contains your key: keep it private, and revoke the key to disable the link.

Claude Code

claude mcp add --transport http pixraft https://pixraft.app/api/mcp --header "Authorization: Bearer pxr_…"

Cursor and other clients

{"mcpServers":{"pixraft":{"url":"https://pixraft.app/api/mcp","headers":{"Authorization":"Bearer pxr_…"}}}}

Stdio-only clients

npx -y mcp-remote https://pixraft.app/api/mcp --header "Authorization: Bearer pxr_…"

Tools: list_models, get_model, quote_price, generate, get_generation, get_balance, list_generations, create_upload. Workflow tools: list_workflow_templates, list_workflows, get_workflow, create_workflow, quote_workflow, run_workflow, get_workflow_run, continue_workflow_run, cancel_workflow_run. The generate and run_workflow tools require max_credits, so an agent can never spend more than you allow.

Command-line tool

npm install -g pixraft
pixraft login
pixraft models --type video
pixraft quote --model <id> --prompt "…"
pixraft generate --model <id> --prompt "…" --max-credits 20 --out ./renders
pixraft balance
pixraft get <generation-id> --out ./renders
pixraft history --type video
pixraft upload ./photo.png
pixraft workflow templates
pixraft workflow run <workflow-id> --max-credits 80 --input t1="…" --out ./renders
pixraft logout

Use pixraft get to resume a generation after a timeout. A --param or --input value of @./file uploads a local file first. Set PIXRAFT_API_KEY to override the saved key, for example in CI.

Get 10 Fast Image starter credits after signup