LL API

A REST API for AI video generation through the Virtuals Protocol ACP system. Generate music videos, commercial ads, and personalized narrative videos using AI agents.

Overview

The LL API integrates with two main AI agents:

• Luvi Agent: Generates music videos (MV1, MV2) and commercial ads (CA1, CA2)
• Lucien Agent: Creates personalized narrative videos (PNV)

All video generation jobs are processed asynchronously - submit a request, receive a job ID, then poll for completion status.

Quick Start

1. Install dependencies:

npm install

2. Set up environment variables:

cp .env.example .env
# Edit .env with your actual values (see Environment Variables section)

3. Start development server:

npm run dev

4. Test the API:

curl http://localhost:3000/

Environment Variables

Create a .env file with the following required variables:

AGENT_ENTITIY_ID=your_agent_entity_id
AGENT_WALLET_ADDRESS=0x...
WHITELISTED_WALLET_PRIVATE_KEY=0x...

• AGENT_ENTITIY_ID: ACP agent entity identifier
• AGENT_WALLET_ADDRESS: Ethereum wallet address (0x format)
• WHITELISTED_WALLET_PRIVATE_KEY: Private key for wallet operations (0x format)

API Documentation

Base URL

http://localhost:3000                        # Local development
https://ll-production-58c1.up.railway.app    # Production

Endpoints

Create Music Video (1 Character)

POST /api/luvi/mv1

Request Body:

{
  "type": "string",
  "artstyle": "string",
  "narrative": "string",
  "avatar_url": "string",
  "avatar_name": "string",
  "avatar_description": "string",
  "webhook_url": "string (optional)"
}

Create Music Video (2 Characters)

POST /api/luvi/mv2

Request Body:

{
  "type": "string",
  "artstyle": "string",
  "narrative": "string",
  "avatar_url": "string",
  "avatar2_url": "string",
  "avatar_name": "string",
  "avatar2_name": "string",
  "avatar_description": "string",
  "avatar2_description": "string",
  "webhook_url": "string (optional)"
}

Create Commercial Ad (1 Character)

POST /api/luvi/ca1

Request Body:

{
  "type": "string",
  "artstyle": "string",
  "narrative": "string",
  "avatar_url": "string",
  "avatar_name": "string",
  "avatar_description": "string",
  "webhook_url": "string (optional)"
}

Create Commercial Ad (2 Characters)

POST /api/luvi/ca2

Request Body:

{
  "type": "string",
  "artstyle": "string",
  "narrative": "string",
  "avatar_url": "string",
  "avatar2_url": "string",
  "avatar_name": "string",
  "avatar2_name": "string",
  "avatar_description": "string",
  "avatar2_description": "string",
  "webhook_url": "string (optional)"
}

Create Personalized Narrative Video

POST /api/lucien/pnv

Request Body:

{
  "narrative": "string",
  "artstyle": "string",
  "webhook_url": "string (optional)"
}

Check Job Status

GET /api/job/{job_id}

Response Format

All API responses follow a standardized format with a boolean success indicator:

Success Response:

{
  "success": true,
  "data": {
    "id": 123,
    "status": "pending|completed|failed",
    "url": "https://video-url.mp4",
    "meta": {
      "phase": "negotiation",
      "deliverable": "...",
      "requirements": {...},
      "price": "...",
      "memos": [...],
      "clientAddress": "0x...",
      "providerAddress": "0x..."
    }
  }
}

Error Response:

{
  "success": false,
  "error": "Job not found"
}

Usage Flow

1. Submit Job: POST to any creation endpoint with required parameters
2. Get Job ID: Extract data.id from successful response
3. Check Status: GET /api/job/{job_id} to monitor progress
4. Get Result: When data.status is "completed", check data.url for video URL

Status Values

The data.status field can have the following values:

• pending - Job is in progress (request, negotiation, transaction, or evaluation phases)
• completed - Job is finished with video URL in data.url field
• failed - Job was rejected or expired

Webhook Notifications

You can receive automatic notifications when jobs complete by including a webhook_url in your request:

curl -X POST http://localhost:3000/api/luvi/mv1 \
  -H "Content-Type: application/json" \
  -d '{
    "type": "music_video",
    "artstyle": "cinematic",
    "narrative": "A singer performs on stage",
    "avatar_url": "https://example.com/avatar.jpg",
    "avatar_name": "Singer",
    "avatar_description": "Talented musician",
    "webhook_url": "https://your-app.com/webhook"
  }'

When the job completes, a POST request will be sent to your webhook URL with this payload:

{
  "event": "job.completed",
  "success": true,
  "data": {
    "id": 123,
    "status": "completed",
    "url": "https://video-url.mp4",
    "meta": {
      "phase": "completed",
      "deliverable": "...",
      "requirements": {...},
      "price": "...",
      "memos": [...],
      "clientAddress": "0x...",
      "providerAddress": "0x..."
    }
  }
}