Docs
Log inStart free
API referenceProjects

Compare a scene with the project's reference

Renders a few frames of the scene and takes the reference frames at the aligned times, then returns how far apart they look: a distance vector (DINO = composition and content, CLIP = meaning; cosine d

istance, smaller is closer), never one score, plus the worst frames with both pictures. The scene must be aligned to the reference. Free.

POST
/projects/{id}/reference/compare

Authorization

bearerAuth
AuthorizationBearer <token>

Typecut API key. Generate one in app.typecut.ai → Settings → API keys. Send as Authorization: Bearer tc_live_….

In: header

Path Parameters

id*string
Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/reference/compare" \  -H "Content-Type: application/json" \  -d '{    "scene_id": "861eef56-1159-4a95-802f-abab2d0cc192"  }'
{
  "data": {
    "scene_id": "string",
    "reference": {
      "analysis_id": "string",
      "span": null
    },
    "against": {
      "image_url": "string"
    },
    "measured": [
      "string"
    ],
    "distances": {
      "property1": {
        "mean": 0,
        "max": 0,
        "median": 0
      },
      "property2": {
        "mean": 0,
        "max": 0,
        "median": 0
      }
    },
    "samples": [
      null
    ],
    "worst": [
      null
    ],
    "detail": null,
    "density": {
      "reference": null,
      "replica": null,
      "ratio": null,
      "findings": [
        "string"
      ]
    },
    "notes": [
      "string"
    ]
  }
}
{
  "error": {
    "type": "string",
    "code": "string",
    "message": "string"
  }
}
{
  "error": {
    "type": "string",
    "code": "string",
    "message": "string"
  }
}
{
  "error": {
    "type": "string",
    "code": "string",
    "message": "string"
  }
}
{
  "error": {
    "type": "string",
    "code": "string",
    "message": "string"
  }
}

Find shots of the project's reference GET

Shots whose on-screen text contains a string, or of a given kind / framing; or, with similar_to (a shot index), the nearest shots by picture (measure dino = composition and content, clip = meaning; cosine distance, smaller is closer).

Get the storyboard GET

The structural map of a project: chapters, script blocks, and the scenes anchored to each block, with voice-over status and durations.