API Reference

Integrate Elcine Studios into your applications using our REST API.

Authentication

All API requests require authentication. Include your API token in the Authorization header:

Authorization: Bearer your-api-token

Base URL

https://elcinestudios.com/api/v1

Endpoints

Chat Streaming

POST /api/chat/stream

Stream assistant responses from a companion

{
  "companion_id": "cinematic-director",
  "session_id": "sess_123",
  "messages": [
    {
      "role": "user",
      "content": "Help me plan a product launch video"
    }
  ]
}

Returns a Server-Sent Events stream with assistant responses. Each event contains a chunk of the response text.

Generate Artifacts

POST /api/artifacts/generate

Generate structured artifacts from conversation

{
  "session_id": "sess_123",
  "artifact_type": "shotlist",
  "context": {
    "brief": "...",
    "script": "..."
  }
}

Artifact types: brief, script, shotlist, prompt_pack

Generate Prompt Pack

POST /api/prompt-pack

Generate a complete prompt pack from brief and shotlist

{
  "project_id": "proj_123",
  "brief_id": "art_001",
  "shotlist_id": "art_002",
  "style_overrides": {
    "lighting": "dramatic rim light"
  }
}

Image Generation

POST /api/studio/image

Generate an image using specified provider

{
  "prompt": "Professional product photography...",
  "negative": "blurry, low quality",
  "provider": "openai",
  "model": "dall-e-3",
  "size": "1792x1024",
  "quality": "hd",
  "style": "vivid",
  "project_id": "proj_123"
}

Returns the generated image URL and metadata.

Video Generation

POST /api/studio/video

Queue a video generation job

{
  "prompt": "Slow push in on product...",
  "provider": "openai",
  "duration_s": 5,
  "aspect_ratio": "16:9",
  "project_id": "proj_123"
}

Returns a job ID for polling status.

Job Status

GET /api/jobs/:id

Poll for job completion status

Returns job status: pending, processing, completed, failed

Export Project

POST /api/export

Export project as JSON

{
  "project_id": "proj_123",
  "include": ["brief", "shotlist", "prompt_pack", "assets"]
}

Rate Limiting

The API implements rate limiting to ensure fair usage:

  • Chat: 60 requests/minute
  • Generation: 20 requests/minute
  • Export: 10 requests/minute

Rate limit headers are included in responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1704067200

Errors

Errors follow a consistent format:

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Missing required field: prompt",
    "details": {}
  }
}

Error Codes

  • UNAUTHORIZED — Invalid or missing API token
  • FORBIDDEN — Insufficient permissions
  • NOT_FOUND — Resource not found
  • INVALID_REQUEST — Malformed request body
  • RATE_LIMITED — Too many requests
  • PROVIDER_ERROR — AI provider returned an error
  • INTERNAL_ERROR — Server error