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",
    "craft": null,
    "scenes": [
      {
        "id": "scene_001",
        "ref": "a1b2c3d4",
        "position": 0,
        "duration": 4.0,
        "description": "Opening shot of the product",
        "image_url": "https://...",
        "video_url": "https://...",
        "video_model": "kling-3.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–50.
`offset`	integer	0	Pagination offset.

Response `200`

{
  "assets": [
    {
      "ref": "x7y8z9a0",
      "type": "video",
      "url": "https://...",
      "model": "kling-3.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": "Brand tone: confident, modern. Visual style: clean, minimal...",
      "tokens": 142,
      "capacity": 4000
    },
    "plan": {
      "content": "4-scene structure with opening, detail, lifestyle, and closing...",
      "tokens": 98,
      "capacity": 5500
    },
    "assets": {
      "content": "Voice: Isabella (warm, conversational). Product image as reference...",
      "tokens": 67,
      "capacity": 5000
    }
  },
  "total_tokens": 307,
  "total_capacity": 14500
}

The agent maintains three memory sections per project:

Creative - Visual direction, brand voice, narrative arc
Plan - Execution tracking, milestones, decisions
Assets - Voice selections, style references, reusable elements

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`. 4K requires a Pro subscription.

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" }

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

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

​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