Skip to main content
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
  }
}
'
{
  "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
}

Documentation Index

Fetch the complete documentation index at: https://api-tools.memories.ai/llms.txt

Use this file to discover all available pages before exploring further.

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-mai-this_a_test_string_please_use_your_generated_key_during_testing";

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);

​
Request Body

FieldTypeRequiredDescription
modestringYesExtraction mode: "short_drama" (short drama), "korean_drama" (Korean drama, coming soon), "prompt_script" (prompt-driven, coming soon)
episodesobjectYesMap of episode number (string) to asset_id. Example: {"1": "re_abc001", "2": "re_abc002"}
configobjectYesConfiguration options for the extraction task
config.languagestringNoLanguage code for extraction (e.g., "zh-CN", "en")
config.use_face_recognitionbooleanNoEnable face recognition for character identification
config.use_subtitlebooleanNoUse subtitle extraction instead of ASR
config.require_jsonbooleanNoReturn JSON format results (transcript + storyboard JSON URIs). Default: true
config.require_xlsxbooleanNoReturn per-episode XLSX storyboard files. Default: false
config.require_merge_xlsxbooleanNoReturn a merged XLSX file combining all episodes. Default: false
config.concurrencyintegerNoProcessing 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
}

​
Response Parameters

ParameterTypeDescription
codeintegerResponse code indicating the result status
msgstringResponse message describing the operation result
data.task_idstringUnique identifier of the screenplay task (from third-party service)
data.statusstringInitial task status: "pending"
data.modestringThe extraction mode used
data.created_atstringISO 8601 timestamp of task creation
data.total_duration_secondsnumberTotal video duration across all episodes in seconds
successbooleanIndicates whether the submission was successful
failedbooleanIndicates whether the submission failed

​
Callback Response Parameters

When the task completes or fails, a callback will be sent to your configured webhook URL.
ParameterTypeDescription
codeintegerResponse code (200 indicates success)
messagestringStatus message
data.task_idstringThe screenplay task ID
data.statusstringFinal task status: "completed" or "failed"
data.error_codestringError code (only present when failed)
data.error_messagestringDetailed error message (only present when failed)
task_idstringYour 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

Example:
{
  "1": "re_657739295220518912",
  "2": "re_657739295220518913",
  "3": "re_657739295220518914"
}
​
config
object
required

Configuration options for the extraction task

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
​
success
boolean

Indicates whether the operation was successful

Example:

true

​
failed
boolean

Indicates whether the operation failed

Example:

false