AI Video Director API

Keyword target: AI video Director API

The Director chat endpoint gives reseller applications the same cinema planning writer used in Reviral, without requiring a browser-created board. Send one message with optional model settings and owned references; receive a reply and, when the plan is ready, a final video prompt. One reply in progress per account; a second chat waits (409) until it finishes.

1. Read GET /api/v1/models and choose a current video model, duration, resolution, and aspect ratio.
2. Send message to POST /api/v1/director/chat from your server. Pass the returned chatId on the next turn. JSON is the default; request text/event-stream only when your integration can consume a stream.
3. When status is prompt_ready, review prompt and submit it to generate-media only when the user approves it.

Working example

Set REVIRAL_API_KEY only in your server environment, then run this request with values valid for your account.

curl -X POST "https://reviral.ai/api/v1/director/chat" \
  -H "Authorization: Bearer $REVIRAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"message":"Plan a 15-second launch video for a reusable travel mug using @image1.","model":"seedance-2","durationSec":15,"resolution":"720p","aspectRatio":"9:16","referenceImageUrls":["https://storage.example.com/storage/v1/object/public/character_uploads/10000000-0000-4000-8000-000000000001/upload-20000000-0000-4000-8000-000000000002.jpg"]}'

{
  "data": {
    "chatId": "550e8400-e29b-41d4-a716-446655440000",
    "reply": "Open on the mug tipping inside a packed tote without leaking, then follow it through a morning commute.",
    "status": "prompt_ready",
    "prompt": "Vertical product film: a reusable travel mug tips inside a packed tote with no spill, then moves through a bright morning commute; tactile close-ups, natural motion, clean final product frame.",
    "plan": {
      "opening": "Leakproof proof",
      "middle": "Morning commute",
      "ending": "Clean product frame"
    }
  }
}

Legacy, still supported

Existing integrations may keep sending the published messages and cinemaContext body. Its original response fields remain present; the current fields are additive.

curl -X POST "https://reviral.ai/api/v1/director/chat" \
  -H "Authorization: Bearer $REVIRAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"messages":[{"role":"user","content":"Plan a 15-second launch video for a reusable travel mug."}],"cinemaContext":{"modelId":"seedance-2","durationSec":15,"resolution":"720p","aspect":"9:16","references":[]}}'

{
  "data": {
    "replyId": "30000000-0000-4000-8000-000000000003",
    "reply": "Open on the mug tipping inside a packed tote without leaking, then follow it through a morning commute.",
    "finalPrompt": "Vertical product film: a reusable travel mug tips inside a packed tote with no spill, then moves through a bright morning commute.",
    "chatId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "prompt_ready",
    "prompt": "Vertical product film: a reusable travel mug tips inside a packed tote with no spill, then moves through a bright morning commute.",
    "plan": {
      "opening": "Leakproof proof",
      "middle": "Morning commute",
      "ending": "Clean product frame"
    }
  }
}

Example transcript

User

Plan a 15-second launch video for a reusable travel mug.

Director

Should the opening focus on the leakproof lid or temperature retention?

User

Lead with the leakproof lid, then show a commute.

Director

Open on the mug tipping inside a packed tote without leaking, then follow it through a morning commute. The final prompt is ready for approval.

Frequently asked questions

Is the Director API charged in credits?

Director chat is free during launch. Starting a render is a separate operation and can charge credits.

Does Director chat require a canvas board?

No. The API uses the cinema context supplied in the request and does not require a browser-created board.

Can Director chat stream replies?

Yes. Send Accept: text/event-stream for the streaming response; omit it for one JSON response.

Chat with Director

Writes one Cinema planning reply. Free during launch. Send Accept: text/event-stream for the streaming form.

Authentication: Bearer API key required

curl -X POST "https://reviral.ai/api/v1/director/chat" \
  -H "Authorization: Bearer $REVIRAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"message":"Plan a 15-second launch video for a reusable travel mug using @image1.","model":"seedance-2","durationSec":15,"resolution":"720p","aspectRatio":"9:16","referenceImageUrls":["https://storage.example.com/storage/v1/object/public/character_uploads/10000000-0000-4000-8000-000000000001/upload-20000000-0000-4000-8000-000000000002.jpg"]}'