Skip to content
Playcut Docs

Quickstart

Every public API endpoint goes through the tools registry — one consistent URL pattern that every tool follows:

POST /api/v1/tools/{tool-name}/execute
Authorization: Bearer pk_live_...
Content-Type: application/json


{ ...tool input }

This is the same surface the MCP server uses, so anything you build with the API translates directly to MCP and vice versa. Browse the full tool list in the live Swagger UI.

  1. Get an API key

    Open app.playcut.ai/settings/api → Create API key. Copy the key — it’s shown once only.

    Terminal window
    export PLAYCUT_API_KEY="pk_live_..."

  2. Create a session

    Sessions group related generations together. Every generation tool needs a workerId.

    Terminal window
    curl -X POST https://api.playcut.ai/api/v1/tools/create-session/execute \
      -H "Authorization: Bearer $PLAYCUT_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"title": "My first API session"}'
    {
      "data": { "sessionId": "65f3a1b2c3d4e5f600000001", "title": "My first API session" }
    }

  3. Submit a generation task

    Terminal window
    curl -X POST https://api.playcut.ai/api/v1/tools/generate-image-from-text/execute \
      -H "Authorization: Bearer $PLAYCUT_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "workerId": "65f3a1b2c3d4e5f600000001",
        "prompt": "A golden retriever surfing at sunset, photorealistic",
        "aspectRatio": "16:9",
        "imageSize": "1K"
      }'

    Every generation tool returns the same async-task acknowledgement:

    {
      "data": {
        "taskId": "65f3a1b2c3d4e5f600000002",
        "status": "PENDING",
        "estimatedCredits": 80
      }
    }

  4. Wait for the result

    Two options — pick whichever fits your client:

    Terminal window
    curl -X POST https://api.playcut.ai/api/v1/tools/get-task-status/execute \
      -H "Authorization: Bearer $PLAYCUT_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"taskId": "65f3a1b2c3d4e5f600000002"}'

    Repeat until status is COMPLETED or FAILED. Typical latency:

    • Images: 5–15 seconds
    • Videos: 60–120 seconds
    • TTS: 3–10 seconds

    Completed response:

    {
      "data": {
        "taskId": "65f3a1b2c3d4e5f600000002",
        "status": "COMPLETED",
        "output": { "assetIds": ["65f3a1b2c3d4e5f600000003"] }
      }
    }

  5. Download the asset

    Terminal window
    curl -X POST https://api.playcut.ai/api/v1/tools/download-asset/execute \
      -H "Authorization: Bearer $PLAYCUT_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"assetId": "65f3a1b2c3d4e5f600000003"}'

    Returns a short-lived signed URL you can curl -L -o file.png or open in a browser.

Node.js end-to-end

Section titled “Node.js end-to-end”
const API_KEY = process.env.PLAYCUT_API_KEY!
const BASE = "https://api.playcut.ai/api/v1/tools"


async function tool<T = any>(name: string, input: Record<string, unknown>): Promise<T> {
  const res = await fetch(`${BASE}/${name}/execute`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(input),
  })
  if (!res.ok) throw new Error(`${name} failed: ${res.status} ${await res.text()}`)
  const json = await res.json()
  return json.data
}


// 1. Create session
const { sessionId } = await tool<{ sessionId: string }>("create-session", {
  title: "API session",
})


// 2. Submit task
const { taskId } = await tool<{ taskId: string }>("generate-image-from-text", {
  workerId: sessionId,
  prompt: "A cat in space, photorealistic",
  aspectRatio: "1:1",
})


// 3. Block until done (server-side long-poll)
const result = await tool<{ status: string; output?: { assetIds: string[] } }>(
  "wait-for-task",
  { taskId },
)


// 4. Get a signed download URL
const { url } = await tool<{ url: string }>("download-asset", {
  assetId: result.output!.assetIds[0],
})


console.log("Result:", url)

Next steps

Section titled “Next steps”