Ecliptic API

This service powers the Ecliptic × Daydreams montage workflow. Use the guides below to integrate, or visit ecliptic.gg for the full product experience.

POST /montages

Submit a song plus one or more video clips, optionally with a creative brief. The API queues a montage job and stages your media in R2/GenAI Files. The response echoes staged asset identifiers so you can reuse them.

Send either a JSON payload or a multipart form with the same fields. At least one video clip is required.

audio: Provide assetId of an existing audio asset or a url we can fetch directly (HTTPS, serves raw media). Optional filename and contentType override persisted metadata.
videos: Array of clip descriptors. Each entry accepts assetId or url plus optional filename/contentType. Multipart submissions repeat the videos field.
prompt: Optional creative brief (≤1000 characters) forwarded to the Gemini montage planner.
username: Optional display name (≤50 characters) used in job tracking and output naming.

Example JSON

{
  "audio": { "url": "https://cdn.example.com/assets/audio.mp3" },
  "videos": [
    { "url": "https://cdn.example.com/assets/clip-1.mp4" },
    { "assetId": "vid_123" }
  ],
  "prompt": "Dreamy sunrise over the city skyline.",
  "username": "daydreams-user"
}

Response

Returns jobId, audioAssetId, and videoAssetIds. Poll GET /jobs/<jobId> until status = "succeeded" to receive the final video URL.

Payments (Coinbase X402)

This endpoint enforces an X402 payment guard on Base. Clients must settle a request matching the published schema before media will queue.

Network: Base mainnet (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 USDC)
Pay to: 0xFdeAE251395004654FBd741824D08Df95315Ed6c
Maximum required amount: 20,000 atomic units (0.02 USDC)
Payment window: 60 seconds

Decode the WWW-Authenticate challenge or use the x402 helper SDKs to construct the payment payload. Include the signed settlement headers in your POST request.

Next Steps

Monitor GET /jobs/<jobId> for status updates and final asset URLs.
List recent jobs via GET /jobs?limit=<n> to inspect prior runs.
Use staged audioAssetId/videoAssetIds to launch future montages without re-uploading.

Need help? Reach out to the Ecliptic team or review integration examples in the repository README.