Highlights

Highlights are generated asynchronously and associated with a demo + user.

Example env:

export BASE_URL="https://highlights-api.rankacy.com"
export TOKEN="rk_live_..."
export DEMO_ID="<your_demo_id>"

0) Preview cost and available credit

Endpoints:

• GET /api/public/v1/highlights/cost
• GET /api/public/v1/me/credit

curl -sS "$BASE_URL/api/public/v1/highlights/cost?resolution_id=1&fps_id=1" \
  -H "Authorization: Bearer $TOKEN" | jq

curl -sS "$BASE_URL/api/public/v1/me/credit" \
  -H "Authorization: Bearer $TOKEN" | jq

1) Generate highlight (automatic)

Endpoint:

POST /api/public/v1/highlights

Required fields:

• demo_id
• resolution_id
• fps_id

Optional fields:

• title
• mode (accepted compatibility field, currently ignored by the backend)
• use_transition
• show_tick
• intro (NONE|GENERIC|SCENIC)
• automatic TOP5 highlights created from demo upload always use show_tick=false

curl -X POST "$BASE_URL/api/public/v1/highlights" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"demo_id\": $DEMO_ID,
    \"resolution_id\": 1,
    \"fps_id\": 1,
    \"title\": \"Mirage recap\",
    \"show_tick\": true
  }"

2) Generate highlight by ticks array

Endpoint:

POST /api/public/v1/highlights/by-ticks

Get kill data first (recommended for copy-paste testing):

KILLS_RESPONSE=$(curl -sS -G "$BASE_URL/api/public/v1/demos/$DEMO_ID/kills" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "limit=1" \
  --data-urlencode "offset=0")

TICK=$(echo "$KILLS_RESPONSE" | jq -r '.items[0].tick // empty')
ATTACKER_STEAM_ID=$(echo "$KILLS_RESPONSE" | jq -r '.items[0].attacker_steam_id // empty')
DEMO_KILL_ID=$(echo "$KILLS_RESPONSE" | jq -r '.items[0].demo_kill_id // empty')

if [ -n "$TICK" ] && [ -n "$ATTACKER_STEAM_ID" ]; then
  curl -X POST "$BASE_URL/api/public/v1/highlights/by-ticks" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d "{
      \"demo_id\": $DEMO_ID,
      \"ticks\": [{\"start_tick\": $TICK, \"end_tick\": $TICK, \"speed\": 0.5, \"steam_id\": \"$ATTACKER_STEAM_ID\"}],
      \"resolution_id\": 1,
      \"fps_id\": 1,
      \"show_tick\": true
    }"
fi

Validation note:

• every tick range must be within demo bounds
• end_tick >= start_tick
• each tick range may include speed (0.25|0.5|1|2, default 1)
• steam_id is required per tick range (SteamID64 string)

3) Generate highlight by demo_kill_id

Endpoint:

POST /api/public/v1/highlights/by-kill

Accepted identifier inputs:

• demo_kill_ids: [801, 805] (recommended)
• kill_ids: [801, 805] (alias)
• demo_kill_id: 801 (single-item alias)
• demo_id is optional, but recommended to add an explicit same-demo check
• speed (0.25|0.5|1|2, default 1) applies to every generated segment

Example with pre/post windows:

if [ -n "$DEMO_KILL_ID" ]; then
  curl -X POST "$BASE_URL/api/public/v1/highlights/by-kill" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d "{
      \"demo_id\": $DEMO_ID,
      \"demo_kill_ids\": [$DEMO_KILL_ID],
      \"pre_ticks\": 192,
      \"post_ticks\": 256,
      \"speed\": 2,
      \"resolution_id\": 1,
      \"fps_id\": 1,
      \"title\": \"Round entry\",
      \"show_tick\": true
    }"
fi

4) List highlights with filters

Endpoint:

GET /api/public/v1/highlights

Filter fields:

• demo_id
• status (NEW|PROCESSING|SUCCESS|FAILED)
• created_from
• created_to
• type (auto|ticks|kill)
• limit
• offset

curl -G "$BASE_URL/api/public/v1/highlights" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "demo_id=$DEMO_ID" \
  --data-urlencode "type=kill" \
  --data-urlencode "limit=20" \
  --data-urlencode "offset=0"

5) Get highlight detail

Endpoint: GET /api/public/v1/highlights/{highlight_id}

Typical use:

1. queue highlight via POST /api/public/v1/highlights
2. read highlight_id from {"highlight_id": ..., "status": "queued"}
3. fetch detail, billed cost, and container events

HIGHLIGHT_RESPONSE=$(curl -sS -X POST "$BASE_URL/api/public/v1/highlights" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"demo_id\": $DEMO_ID,
    \"resolution_id\": 1,
    \"fps_id\": 1,
    \"title\": \"Detail probe\"
  }")

HIGHLIGHT_ID=$(echo "$HIGHLIGHT_RESPONSE" | jq -r '.highlight_id')

curl -sS "$BASE_URL/api/public/v1/highlights/$HIGHLIGHT_ID" \
  -H "Authorization: Bearer $TOKEN" | jq

6) Delete a highlight

Endpoint: DELETE /api/public/v1/highlights/{highlight_id}

if [ -n "${HIGHLIGHT_ID:-}" ]; then
  curl -sS -X DELETE "$BASE_URL/api/public/v1/highlights/$HIGHLIGHT_ID" \
    -H "Authorization: Bearer $TOKEN" | jq
fi

Expected response shape:

{
  "highlight_id": 311,
  "status": "deleted"
}

7) List available output options

Resolutions

Endpoint: GET /api/public/v1/highlights/resolutions

Expected response shape:

{
  "items": [
    {
      "id": 1,
      "name": "1280x720",
      "width": 1280,
      "height": 720
    }
  ]
}

FPS

Endpoint: GET /api/public/v1/highlights/fps

Expected response shape:

{
  "items": [
    {
      "id": 1,
      "name": "60 FPS",
      "fps": 60
    }
  ]
}

Response after queueing

All generation endpoints return:

{
  "highlight_id": 311,
  "status": "queued"
}

Use GET /api/public/v1/highlights/{highlight_id} to verify whether show_tick was stored on the created highlight and whether each returned container includes the expected speed.