Output

Get timeline

GET /projects/:id/timeline

Returns the full timeline structure: scenes, audio tracks, overlays, and captions.

Parameter	Type	Description
`variation_id`	string	Fetch a specific variation’s timeline instead of the active one.

Response `200`

{
  "timeline": {
    "duration_seconds": 15.2,
    "aspect_ratio": "16:9",
    "skills": [],
    "scenes": [
      {
        "id": "scene_001",
        "ref": "a1b2c3d4",
        "type": "video",
        "position": 0,
        "duration": 4.0,
        "description": "Opening shot of the product",
        "image_url": "https://...",
        "video_url": "https://...",
        "video_model": "seedance-2.0",
        "image_model": "nano-banana-pro",
        "prompt": "Opening shot of the product on a clean background...",
        "volume": 1,
        "fade_in": 0.5,
        "fade_out": null
      }
    ],
    "audio": {
      "voiceover": {
        "url": "https://...",
        "duration": 12.5,
        "voice": "Isabella",
        "voice_id": "voice_001",
        "language": "en",
        "script": "Your voiceover script here..."
      },
      "music": {
        "url": "https://...",
        "duration": 15.2,
        "genre": "ambient",
        "mood": "warm",
        "bpm": 72,
        "role": "background",
        "instrumental": true
      },
      "tracks": [
        {
          "id": "track_001",
          "type": "voiceover",
          "url": "https://...",
          "duration": 12.5,
          "volume": 100,
          "start_time": 0.5,
          "name": "Main narration",
          "voice": "Isabella",
          "voice_id": "voice_001",
          "language": "en",
          "script": "Your voiceover script here..."
        }
      ]
    },
    "overlays": [
      {
        "id": "text-0",
        "type": "text",
        "content": "Your Brand",
        "start_time": 12.0,
        "duration": 3.0,
        "position": "bottom-center",
        "font_size": 48,
        "color": "#FFFFFF",
        "background_color": "rgba(0,0,0,0.5)"
      }
    ],
    "captions": {
      "enabled": true,
      "preset": "clean"
    }
  }
}

Get assets

GET /projects/:id/assets

Returns all generated assets (images, videos, audio) for the project. Each asset has a ref, an 8-character short identifier that links assets to scenes on the timeline.

Parameter	Type	Default	Description
`limit`	integer	20	Results per page. 1–200.
`offset`	integer	0	Pagination offset.

Response `200`

{
  "assets": [
    {
      "ref": "x7y8z9a0",
      "type": "video",
      "url": "https://...",
      "model": "seedance-2.0",
      "prompt": "Opening shot of the product on a clean background...",
      "duration": 5.0,
      "aspect_ratio": "16:9",
      "source_image_url": "https://...",
      "source_video_url": null,
      "reference_image_url": null,
      "created_at": "2025-03-15T10:32:00Z"
    }
  ],
  "total": 24,
  "limit": 20,
  "offset": 0
}

List variations

GET /projects/:id/variations

Returns all variations for a project. Variations are read-only via the API. Create, switch, and delete them by sending messages to the agent.

Response `200`

{
  "variations": [
    {
      "id": "var_001",
      "title": "Original",
      "description": null,
      "aspect_ratio": "16:9",
      "language": "en",
      "scene_count": 4,
      "is_active": true,
      "created_at": "2025-03-15T10:30:00Z"
    },
    {
      "id": "var_002",
      "title": "TikTok Version",
      "description": "Portrait format for social",
      "aspect_ratio": "9:16",
      "language": "en",
      "scene_count": 4,
      "is_active": false,
      "created_at": "2025-03-15T10:40:00Z"
    }
  ]
}

To create or switch variations, send a message to the agent:

{ "message": "Create a 9:16 version for TikTok" }
{ "message": "Switch to variation var_002" }
{ "message": "Duplicate the current variation" }

Use GET /projects/:id/timeline?variation_id=var_002 to inspect a non-active variation’s timeline without switching.

Get agent memory

GET /projects/:id/memory

Read the agent’s working memory for this project.

Response `200`

{
  "sections": {
    "creative": {
      "content": "Markdown summary of the locked creative direction and production settings...",
      "tokens": 142
    },
    "todos": {
      "content": "Checklist tracking what's done and what's next...",
      "tokens": 98
    },
    "assets": {
      "content": "Structured ledger of characters, products, environments, and references...",
      "tokens": 67
    }
  },
  "total_tokens": 307
}

The agent maintains three memory sections per project:

Creative — Markdown of the locked creative direction and chosen production settings
Todos — Checklist of what’s done and what’s next
Assets — Structured ledger of characters, products, environments, and references the agent is using

Memory is per-project (shared across all variations). The agent condenses automatically as sections grow. Separately, learned preferences persist across all projects. These are patterns the agent picks up from your feedback about style and production choices. Manage these via the account endpoints.

Render video

POST /projects/:id/render

Trigger a final video render. Composites all timeline content (scenes, audio, overlays, captions) into a single video file. Only valid when status is idle.

Request body

Parameter	Type	Default	Description
`quality`	string	`1080p`	`1080p` or `4k`. 1080p is free (rate-limited per day). 4K charges credits.

Response `202`

{
  "id": "proj_abc123",
  "status": "rendering",
  "quality": "1080p"
}

Poll the project status. When rendering completes, the status returns to idle and assembled_url contains the video URL.

Rendered video URLs expire after 24 hours. Create a share link for a permanent URL, or render again.

POST /projects/:id/share

Create a permanent, public URL for a rendered video. Requires a completed render.

Request body

Parameter	Type	Description
`title`	string	Optional title for the shared page.
`description`	string	Optional description.

Response `201`

{
  "share_url": "https://eversince.ai/share/abc123",
  "video_url": "https://..."
}

The video_url from a share link does not expire.

Upload files

Upload reference media (images, videos, audio) for use in project creation or messages.

Step 1: Get a presigned upload URL

POST /uploads

Parameter	Type	Required	Description
`file_name`	string	Yes	Original file name.
`content_type`	string	Yes	MIME type (e.g., `image/jpeg`, `video/mp4`).
`file_size`	integer	Yes	File size in bytes.

Size limits: Images 10 MB, Videos 500 MB, Audio 50 MB. Accepted types: image/jpeg, image/jpg, image/png, image/webp, video/mp4, video/webm, video/quicktime, video/x-msvideo, audio/mpeg, audio/mp3, audio/wav, audio/mp4, audio/m4a.

Response `200`

{
  "upload_url": "https://...",
  "r2_key": "uploads/abc123/image.jpg",
  "expires_in": 3600
}

Step 2: Upload the file

PUT {upload_url}

Upload the file directly to the presigned URL with the matching Content-Type header.

Step 3: Confirm the upload

POST /uploads/confirm

Parameter	Type	Required	Description
`r2_key`	string	Yes	The `r2_key` from step 1.
`file_name`	string	Yes	Original file name.
`file_size`	integer	Yes	File size in bytes.
`content_type`	string	Yes	MIME type.

Response `201`

{
  "upload_id": "upl_abc123",
  "type": "image"
}

Use the upload_id as a reference when creating projects or sending messages:

{
  "brief": "Create an ad featuring this product",
  "references": [{ "upload_id": "upl_abc123" }]
}

Full upload example

# 1. Get presigned URL
PRESIGN=$(curl -s -X POST https://eversince.ai/api/v1/uploads \
  -H "Authorization: Bearer $EVERSINCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_name": "product.jpg",
    "content_type": "image/jpeg",
    "file_size": 245000
  }')

UPLOAD_URL=$(echo $PRESIGN | jq -r '.upload_url')
R2_KEY=$(echo $PRESIGN | jq -r '.r2_key')

# 2. Upload the file
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: image/jpeg" \
  --data-binary @product.jpg

# 3. Confirm
curl -X POST https://eversince.ai/api/v1/uploads/confirm \
  -H "Authorization: Bearer $EVERSINCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"r2_key\": \"$R2_KEY\",
    \"file_name\": \"product.jpg\",
    \"file_size\": 245000,
    \"content_type\": \"image/jpeg\"
  }"

# Response: { "upload_id": "upl_abc123", "type": "image" }

import os

file_path = "product.jpg"
file_size = os.path.getsize(file_path)

# 1. Get presigned URL
presign = requests.post(f"{BASE}/uploads", headers=headers, json={
    "file_name": "product.jpg",
    "content_type": "image/jpeg",
    "file_size": file_size
}).json()

# 2. Upload the file
with open(file_path, "rb") as f:
    requests.put(presign["upload_url"],
                 data=f,
                 headers={"Content-Type": "image/jpeg"})

# 3. Confirm
upload = requests.post(f"{BASE}/uploads/confirm", headers=headers, json={
    "r2_key": presign["r2_key"],
    "file_name": "product.jpg",
    "file_size": file_size,
    "content_type": "image/jpeg"
}).json()

# Use in project creation
requests.post(f"{BASE}/projects", headers=headers, json={
    "brief": "Create an ad featuring this product",
    "references": [{"upload_id": upload["upload_id"]}]
})

const fs = require("fs");

const filePath = "product.jpg";
const fileSize = fs.statSync(filePath).size;

// 1. Get presigned URL
const presign = await fetch(`${BASE}/uploads`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    file_name: "product.jpg",
    content_type: "image/jpeg",
    file_size: fileSize,
  }),
}).then((r) => r.json());

// 2. Upload the file
await fetch(presign.upload_url, {
  method: "PUT",
  headers: { "Content-Type": "image/jpeg" },
  body: fs.readFileSync(filePath),
});

// 3. Confirm
const upload = await fetch(`${BASE}/uploads/confirm`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    r2_key: presign.r2_key,
    file_name: "product.jpg",
    file_size: fileSize,
    content_type: "image/jpeg",
  }),
}).then((r) => r.json());

// Use in project creation
await fetch(`${BASE}/projects`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    brief: "Create an ad featuring this product",
    references: [{ upload_id: upload.upload_id }],
  }),
});

Overview

Resources

API Reference

Get timeline

Response `200`

Get assets

Response `200`

List variations

Response `200`

Get agent memory

Response `200`

Render video

Request body

Response `202`

Request body

Response `201`

Upload files

Step 1: Get a presigned upload URL

Response `200`

Step 2: Upload the file

Step 3: Confirm the upload

Response `201`

Full upload example

​Get timeline

​Response 200

​Get assets

​Response 200

​List variations

​Response 200

​Get agent memory

​Response 200

​Render video

​Request body

​Response 202

​Create share link

​Request body

​Response 201

​Upload files

​Step 1: Get a presigned upload URL

​Response 200

​Step 2: Upload the file

​Step 3: Confirm the upload

​Response 201

​Full upload example

Get timeline

Response `200`

Get assets

Response `200`

List variations

Response `200`

Get agent memory

Response `200`

Render video

Request body

Response `202`

Create share link

Request body

Response `201`

Upload files

Step 1: Get a presigned upload URL

Response `200`

Step 2: Upload the file

Step 3: Confirm the upload

Response `201`

Full upload example