Submit Screenplay Task

curl --request POST \
  --url https://mavi-backend.memories.ai/serve/api/v2/screenplay/tasks \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "mode": "short_drama",
  "episodes": {
    "1": "re_657739295220518912",
    "2": "re_657739295220518913",
    "3": "re_657739295220518914"
  },
  "config": {
    "language": "zh-CN",
    "use_face_recognition": true,
    "use_subtitle": false,
    "require_json": true,
    "require_xlsx": false,
    "require_merge_xlsx": false,
    "concurrency": 100
  }
}
'

import requests

url = "https://mavi-backend.memories.ai/serve/api/v2/screenplay/tasks"

payload = {
    "mode": "short_drama",
    "episodes": {
        "1": "re_657739295220518912",
        "2": "re_657739295220518913",
        "3": "re_657739295220518914"
    },
    "config": {
        "language": "zh-CN",
        "use_face_recognition": True,
        "use_subtitle": False,
        "require_json": True,
        "require_xlsx": False,
        "require_merge_xlsx": False,
        "concurrency": 100
    }
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    mode: 'short_drama',
    episodes: {
      '1': 're_657739295220518912',
      '2': 're_657739295220518913',
      '3': 're_657739295220518914'
    },
    config: {
      language: 'zh-CN',
      use_face_recognition: true,
      use_subtitle: false,
      require_json: true,
      require_xlsx: false,
      require_merge_xlsx: false,
      concurrency: 100
    }
  })
};

fetch('https://mavi-backend.memories.ai/serve/api/v2/screenplay/tasks', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://mavi-backend.memories.ai/serve/api/v2/screenplay/tasks",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'mode' => 'short_drama',
    'episodes' => [
        '1' => 're_657739295220518912',
        '2' => 're_657739295220518913',
        '3' => 're_657739295220518914'
    ],
    'config' => [
        'language' => 'zh-CN',
        'use_face_recognition' => true,
        'use_subtitle' => false,
        'require_json' => true,
        'require_xlsx' => false,
        'require_merge_xlsx' => false,
        'concurrency' => 100
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://mavi-backend.memories.ai/serve/api/v2/screenplay/tasks"

	payload := strings.NewReader("{\n  \"mode\": \"short_drama\",\n  \"episodes\": {\n    \"1\": \"re_657739295220518912\",\n    \"2\": \"re_657739295220518913\",\n    \"3\": \"re_657739295220518914\"\n  },\n  \"config\": {\n    \"language\": \"zh-CN\",\n    \"use_face_recognition\": true,\n    \"use_subtitle\": false,\n    \"require_json\": true,\n    \"require_xlsx\": false,\n    \"require_merge_xlsx\": false,\n    \"concurrency\": 100\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://mavi-backend.memories.ai/serve/api/v2/screenplay/tasks")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"mode\": \"short_drama\",\n  \"episodes\": {\n    \"1\": \"re_657739295220518912\",\n    \"2\": \"re_657739295220518913\",\n    \"3\": \"re_657739295220518914\"\n  },\n  \"config\": {\n    \"language\": \"zh-CN\",\n    \"use_face_recognition\": true,\n    \"use_subtitle\": false,\n    \"require_json\": true,\n    \"require_xlsx\": false,\n    \"require_merge_xlsx\": false,\n    \"concurrency\": 100\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://mavi-backend.memories.ai/serve/api/v2/screenplay/tasks")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"mode\": \"short_drama\",\n  \"episodes\": {\n    \"1\": \"re_657739295220518912\",\n    \"2\": \"re_657739295220518913\",\n    \"3\": \"re_657739295220518914\"\n  },\n  \"config\": {\n    \"language\": \"zh-CN\",\n    \"use_face_recognition\": true,\n    \"use_subtitle\": false,\n    \"require_json\": true,\n    \"require_xlsx\": false,\n    \"require_merge_xlsx\": false,\n    \"concurrency\": 100\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "ros-sd-20260313-a3f8c2b1",
    "status": "pending",
    "mode": "short_drama",
    "created_at": "2026-03-13T10:00:00Z",
    "total_duration_seconds": 450.5
  },
  "failed": false,
  "success": true
}

{
  "code": 200,
  "message": "SUCCESS",
  "data": {
    "task_id": "ros-sd-20260313-a3f8c2b1",
    "status": "completed"
  },
  "task_id": "ros-sd-20260313-a3f8c2b1"
}

{
  "code": 200,
  "message": "SUCCESS",
  "data": {
    "task_id": "ros-sd-20260313-a3f8c2b1",
    "status": "failed",
    "error_code": "PROCESSING_FAILED",
    "error_message": "Episode 3 processing failed: episode-pipeline ep3 failed: ..."
  },
  "task_id": "ros-sd-20260313-a3f8c2b1"
}

POST

screenplay

tasks

Submit Screenplay Task

curl --request POST \
  --url https://mavi-backend.memories.ai/serve/api/v2/screenplay/tasks \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "mode": "short_drama",
  "episodes": {
    "1": "re_657739295220518912",
    "2": "re_657739295220518913",
    "3": "re_657739295220518914"
  },
  "config": {
    "language": "zh-CN",
    "use_face_recognition": true,
    "use_subtitle": false,
    "require_json": true,
    "require_xlsx": false,
    "require_merge_xlsx": false,
    "concurrency": 100
  }
}
'

import requests

url = "https://mavi-backend.memories.ai/serve/api/v2/screenplay/tasks"

payload = {
    "mode": "short_drama",
    "episodes": {
        "1": "re_657739295220518912",
        "2": "re_657739295220518913",
        "3": "re_657739295220518914"
    },
    "config": {
        "language": "zh-CN",
        "use_face_recognition": True,
        "use_subtitle": False,
        "require_json": True,
        "require_xlsx": False,
        "require_merge_xlsx": False,
        "concurrency": 100
    }
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    mode: 'short_drama',
    episodes: {
      '1': 're_657739295220518912',
      '2': 're_657739295220518913',
      '3': 're_657739295220518914'
    },
    config: {
      language: 'zh-CN',
      use_face_recognition: true,
      use_subtitle: false,
      require_json: true,
      require_xlsx: false,
      require_merge_xlsx: false,
      concurrency: 100
    }
  })
};

fetch('https://mavi-backend.memories.ai/serve/api/v2/screenplay/tasks', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://mavi-backend.memories.ai/serve/api/v2/screenplay/tasks",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'mode' => 'short_drama',
    'episodes' => [
        '1' => 're_657739295220518912',
        '2' => 're_657739295220518913',
        '3' => 're_657739295220518914'
    ],
    'config' => [
        'language' => 'zh-CN',
        'use_face_recognition' => true,
        'use_subtitle' => false,
        'require_json' => true,
        'require_xlsx' => false,
        'require_merge_xlsx' => false,
        'concurrency' => 100
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://mavi-backend.memories.ai/serve/api/v2/screenplay/tasks"

	payload := strings.NewReader("{\n  \"mode\": \"short_drama\",\n  \"episodes\": {\n    \"1\": \"re_657739295220518912\",\n    \"2\": \"re_657739295220518913\",\n    \"3\": \"re_657739295220518914\"\n  },\n  \"config\": {\n    \"language\": \"zh-CN\",\n    \"use_face_recognition\": true,\n    \"use_subtitle\": false,\n    \"require_json\": true,\n    \"require_xlsx\": false,\n    \"require_merge_xlsx\": false,\n    \"concurrency\": 100\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://mavi-backend.memories.ai/serve/api/v2/screenplay/tasks")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"mode\": \"short_drama\",\n  \"episodes\": {\n    \"1\": \"re_657739295220518912\",\n    \"2\": \"re_657739295220518913\",\n    \"3\": \"re_657739295220518914\"\n  },\n  \"config\": {\n    \"language\": \"zh-CN\",\n    \"use_face_recognition\": true,\n    \"use_subtitle\": false,\n    \"require_json\": true,\n    \"require_xlsx\": false,\n    \"require_merge_xlsx\": false,\n    \"concurrency\": 100\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://mavi-backend.memories.ai/serve/api/v2/screenplay/tasks")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"mode\": \"short_drama\",\n  \"episodes\": {\n    \"1\": \"re_657739295220518912\",\n    \"2\": \"re_657739295220518913\",\n    \"3\": \"re_657739295220518914\"\n  },\n  \"config\": {\n    \"language\": \"zh-CN\",\n    \"use_face_recognition\": true,\n    \"use_subtitle\": false,\n    \"require_json\": true,\n    \"require_xlsx\": false,\n    \"require_merge_xlsx\": false,\n    \"concurrency\": 100\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "ros-sd-20260313-a3f8c2b1",
    "status": "pending",
    "mode": "short_drama",
    "created_at": "2026-03-13T10:00:00Z",
    "total_duration_seconds": 450.5
  },
  "failed": false,
  "success": true
}

{
  "code": 200,
  "message": "SUCCESS",
  "data": {
    "task_id": "ros-sd-20260313-a3f8c2b1",
    "status": "completed"
  },
  "task_id": "ros-sd-20260313-a3f8c2b1"
}

{
  "code": 200,
  "message": "SUCCESS",
  "data": {
    "task_id": "ros-sd-20260313-a3f8c2b1",
    "status": "failed",
    "error_code": "PROCESSING_FAILED",
    "error_message": "Episode 3 processing failed: episode-pipeline ep3 failed: ..."
  },
  "task_id": "ros-sd-20260313-a3f8c2b1"
}

Product: Visual Agents Use case: Managed endpoints powering Memories.ai’s open-source video search and editing agents (queries, video clipping/editing, screenplay extraction) Host: https://mavi-backend.memories.ai/serve/api/v2 Auth: Authorization: sk-mavi-... (no Bearer prefix)

This endpoint submits an asynchronous screenplay extraction task. It analyzes video episodes and generates structured storyboard data including transcripts, scene breakdowns, and character namelists.

This is an async endpoint. You must configure a webhook URL in Webhooks Settings before calling this endpoint, otherwise you will not receive the processing results. See Webhooks Configuration Guide for details.

Pricing:

$1.00/minute of video (rounded up per episode)

Asset Validation:

Each asset must be a video file (not audio or image)
Each video must be under 5 minutes in duration
Invalid assets will be reported in the error response with specific reasons

Code Examples

const BASE_URL = "https://mavi-backend.memories.ai/serve/api/v2";
const API_KEY = "sk-mavi-...";

const response = await fetch(`${BASE_URL}/screenplay/tasks`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': API_KEY
  },
  body: JSON.stringify({
    mode: "short_drama",
    episodes: {
      "1": "re_657739295220518912",
      "2": "re_657739295220518913",
      "3": "re_657739295220518914"
    },
    config: {
      language: "zh-CN",
      use_face_recognition: true,
      use_subtitle: false,
      require_json: true,
      require_xlsx: false,
      require_merge_xlsx: false,
      concurrency: 100
    }
  })
});

const data = await response.json();
console.log(data);

import axios from 'axios';

const BASE_URL = "https://mavi-backend.memories.ai/serve/api/v2";
const API_KEY = "sk-mavi-...";

const response = await axios.post(`${BASE_URL}/screenplay/tasks`, {
  mode: "short_drama",
  episodes: {
    "1": "re_657739295220518912",
    "2": "re_657739295220518913",
    "3": "re_657739295220518914"
  },
  config: {
    language: "zh-CN",
    use_face_recognition: true,
    use_subtitle: false,
    require_json: true,
    require_xlsx: false,
    require_merge_xlsx: false,
    concurrency: 100
  }
}, {
  headers: {
    'Authorization': API_KEY
  }
});

console.log(response.data);

import requests

BASE_URL = "https://mavi-backend.memories.ai/serve/api/v2"
API_KEY = "sk-mavi-..."
HEADERS = {
    "Authorization": f"{API_KEY}"
}

def submit_screenplay_task(mode, episodes, config):
    url = f"{BASE_URL}/screenplay/tasks"
    data = {
        "mode": mode,
        "episodes": episodes,
        "config": config
    }
    response = requests.post(url, json=data, headers=HEADERS)
    return response.json()

# Usage example
result = submit_screenplay_task(
    mode="short_drama",
    episodes={
        "1": "re_657739295220518912",
        "2": "re_657739295220518913",
        "3": "re_657739295220518914"
    },
    config={
        "language": "zh-CN",
        "use_face_recognition": True,
        "use_subtitle": False,
        "require_json": True,
        "require_xlsx": False,
        "require_merge_xlsx": False,
        "concurrency": 100
    }
)
print(result)

Request Body

Field	Type	Required	Description
mode	string	Yes	Extraction mode: `"short_drama"` (short drama), `"korean_drama"` (Korean drama, coming soon), `"prompt_script"` (prompt-driven, coming soon)
episodes	object	Yes	Map of episode number (string) to asset_id. Example: `{"1": "re_abc001", "2": "re_abc002"}`
config	object	Yes	Configuration options for the extraction task
config.language	string	No	Language code for extraction (e.g., `"zh-CN"`, `"en"`)
config.use_face_recognition	boolean	No	Enable face recognition for character identification
config.use_subtitle	boolean	No	Use subtitle extraction instead of ASR
config.require_json	boolean	No	Return JSON format results (transcript + storyboard JSON URIs). Default: `true`
config.require_xlsx	boolean	No	Return per-episode XLSX storyboard files. Default: `false`
config.require_merge_xlsx	boolean	No	Return a merged XLSX file combining all episodes. Default: `false`
config.concurrency	integer	No	Processing concurrency limit. Default: `100`

At least one output format must be enabled: require_json, require_xlsx, or require_merge_xlsx.

Response

Returns task information for the screenplay extraction task.

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "ros-sd-20260313-a3f8c2b1",
    "status": "pending",
    "mode": "short_drama",
    "created_at": "2026-03-13T10:00:00Z",
    "total_duration_seconds": 450.5
  },
  "failed": false,
  "success": true
}

{
  "code": 200,
  "message": "SUCCESS",
  "data": {
    "task_id": "ros-sd-20260313-a3f8c2b1",
    "status": "completed"
  },
  "task_id": "ros-sd-20260313-a3f8c2b1"
}

{
  "code": 200,
  "message": "SUCCESS",
  "data": {
    "task_id": "ros-sd-20260313-a3f8c2b1",
    "status": "failed",
    "error_code": "PROCESSING_FAILED",
    "error_message": "Episode 3 processing failed: episode-pipeline ep3 failed: ..."
  },
  "task_id": "ros-sd-20260313-a3f8c2b1"
}

Response Parameters

Parameter	Type	Description
code	integer	Response code indicating the result status
msg	string	Response message describing the operation result
data.task_id	string	Unique identifier of the screenplay task (from third-party service)
data.status	string	Initial task status: `"pending"`
data.mode	string	The extraction mode used
data.created_at	string	ISO 8601 timestamp of task creation
data.total_duration_seconds	number	Total video duration across all episodes in seconds
success	boolean	Indicates whether the submission was successful
failed	boolean	Indicates whether the submission failed

Callback Response Parameters

When the task completes or fails, a callback will be sent to your configured webhook URL.

Parameter	Type	Description
code	integer	Response code (200 indicates success)
message	string	Status message
data.task_id	string	The screenplay task ID
data.status	string	Final task status: `"completed"` or `"failed"`
data.error_code	string	Error code (only present when failed)
data.error_message	string	Detailed error message (only present when failed)
task_id	string	Your original request ID

Asset Validation Error Example

If any submitted asset fails validation, the API returns an error with details:

{
  "code": 200,
  "msg": "Asset validation failed:\n  Episode 1 (asset_id: re_abc001): Not a video file (type: image/png)\n  Episode 3 (asset_id: re_abc003): Video duration is 360.0 seconds, maximum allowed is 300 seconds (5 minutes)",
  "success": false,
  "failed": true
}

Notes

Screenplay extraction is processed asynchronously
The task_id returned is from the third-party processing service, use it for status queries, downloads, and cancellation
Cost is calculated based on total video duration across all episodes at $1/minute (rounded up)
Billing occurs after the task is successfully submitted to the processing service
Use Get Task Status to check progress
Use Download Task Result to download completed results as a zip file

Authorizations

Authorization

string

header

required

API key for authentication

Body

application/json

mode

enum<string>

required

Extraction mode

Available options:

short_drama,

korean_drama,

prompt_script

Example:

"short_drama"

episodes

object

required

Map of episode number to asset_id

Show child attributes

Example:

{
  "1": "re_657739295220518912",
  "2": "re_657739295220518913",
  "3": "re_657739295220518914"
}

config

object

required

Configuration options for the extraction task

Show child attributes

Response

200 - application/json

Task submitted successfully

code

integer

Response code indicating the result status

Example:

200

msg

string

Response message

Example:

"success"

data

object

Show child attributes

success

boolean

Indicates whether the operation was successful

Example:

true

failed

boolean

Indicates whether the operation failed

Example:

false

Split Video Get Task Status

​Code Examples

​Request Body

​Response

​Response Parameters

​Callback Response Parameters

​Asset Validation Error Example

​Notes

Authorizations

Body

Response

Code Examples

Request Body

Response

Response Parameters

Callback Response Parameters

Asset Validation Error Example

Notes