Skip to content
DER.run
Open studio

API

Build with the DER API

The models and tools in the studio are available over HTTPS with an API key: read the model catalog, submit runs, poll them and download the results. Or plug DER into your AI agent over MCP.

Get an API keyConnect an AI agent
  • AuthenticationBearer API key
  • Models and tools50 in the catalog
  • PollingEvery 5–30 s
  • Pricing1 credit = $0.01

Two ways in

REST for code, MCP for agents

REST API

https://api.der.run/v1

For your own code. Submit a run, poll it, download the result.

  • GET/v1/capabilitiesEvery model with its parameters, upload slots, price mode and polling interval
  • POST/v1/quotesPrice a run before you submit it
  • POST/v1/uploadsStart an upload, then PUT the file to the address it returns
  • POST/v1/uploads/{id}/completeFinish the upload and get the asset id to use in inputs
  • POST/v1/jobsSubmit a run · Idempotency-Key required
  • GET/v1/jobsYour runs, newest first, up to 100 a page
  • GET/v1/jobs/{id}Status of a run
  • GET/v1/jobs/{id}/assets/{index}Download an output through a private link that works for about an hour

MCP server & DER skill

https://api.der.run/mcp

For AI agents like Claude Code, Cursor and Codex. Add the address, sign in with your DER account, then ask in plain words.

  • der_list_modelsModels, prices and limits
  • der_quotePrice a job before it runs (free)
  • der_create_jobStart a video, image, AIdol, face swap or music job
  • der_get_jobStatus and result links
  • der_get_resultsDownload links
  • + 12 more tools in the MCP server
Set up your AI agent

Authentication

One key, your whole account

Send your API key as a Bearer token. A key acts as your account: same credits, same tier. Keys last up to 366 days — create and revoke them in API keys. Up to 10 keys at a time.

HTTP header
# every request
Authorization: Bearer der_user_…

Quick start

Your first run in three steps

  1. Create an API key

    In the studio, under API keys. The key is shown once — store it somewhere safe.

    Open API keys

  2. Read the catalog

    GET /v1/capabilities lists every model with its parameters, upload slots, price mode and polling interval.

    Terminal
    curl "https://api.der.run/v1/capabilities" \
  -H "Authorization: Bearer $DER_API_KEY"

  3. Submit and poll

    Upload your photo first, then POST /v1/jobs with an Idempotency-Key and poll GET /v1/jobs/{id} until the run is finished. Sending the same key again returns the same run.

    Terminal
    curl -X POST "https://api.der.run/v1/jobs" \
  -H "Authorization: Bearer $DER_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "der-v2",
    "params": {
      "prompt": "…"
    },
    "inputs": {
      "image": "<asset id>"
    }
  }'

curl "https://api.der.run/v1/jobs/{id}" \
  -H "Authorization: Bearer $DER_API_KEY"

Good to know

Before you ship

  • Results are private

    Over REST, outputs download with your key: GET /v1/jobs/{id}/assets/{index} sends you to a private link that works for about an hour. There are no public links, and MCP tools hand out the same kind of link. Results and uploads are kept for 7 days, then deleted automatically.

  • Lists come in pages

    GET /v1/jobs returns up to 100 runs, newest first. Pass next_before as before to get older ones, and filter by model, output or state.

  • Prices

    Some models have a fixed price in the catalog; the rest are priced when you submit. POST /v1/quotes tells you the price first.

  • Tiers

    Some models need a Pro or Max account. A request for one of them from a lower tier gets a 403.

  • Same credits

    The API spends the same credits as the studio. Failed runs are refunded automatically.

  • Poll at the model’s pace

    Every model has its own poll_seconds in the catalog. Too many requests get a 429 with a Retry-After header.

For AI agents

Use DER from Claude Code, Cursor or Codex

One command to connect. Same models, same credits, and results show up in the studio too.

Open the AI agents guide