> ## 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.
# Submit Screenplay Task
> Submit an async screenplay extraction task for short drama videos
**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](https://api-platform.memories.ai/webhooks) before calling this endpoint, otherwise you will not receive the processing results. See [Webhooks Configuration Guide](/visual-intelligence/getting-started/webhooks) 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
```javascript fetch theme={null}
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);
```
```javascript axios theme={null}
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);
```
```python Python theme={null}
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.
```json Response theme={null}
{
"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
}
```
```json Callback Response (Success) theme={null}
{
"code": 200,
"message": "SUCCESS",
"data": {
"task_id": "ros-sd-20260313-a3f8c2b1",
"status": "completed"
},
"task_id": "ros-sd-20260313-a3f8c2b1"
}
```
```json Callback Response (Failed) theme={null}
{
"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:
```json theme={null}
{
"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](/visual-agents/screenplay/get-task-status) to check progress
* Use [Download Task Result](/visual-agents/screenplay/download-task-result) to download completed results as a zip file
## OpenAPI
````yaml POST /screenplay/tasks
openapi: 3.1.0
info:
title: Screenplay Extraction API
description: APIs for screenplay extraction from short drama videos
version: v1.0.0
servers:
- url: https://mavi-backend.memories.ai/serve/api/v2
security:
- ApiKeyAuth: []
paths:
/screenplay/tasks:
post:
summary: Submit Screenplay Task
operationId: submit_screenplay_task
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
mode:
type: string
description: Extraction mode
example: short_drama
enum:
- short_drama
- korean_drama
- prompt_script
episodes:
type: object
description: Map of episode number to asset_id
example:
'1': re_657739295220518912
'2': re_657739295220518913
'3': re_657739295220518914
additionalProperties:
type: string
config:
type: object
description: Configuration options for the extraction task
properties:
language:
type: string
description: Language code for extraction
example: zh-CN
use_face_recognition:
type: boolean
description: Enable face recognition for character identification
example: true
use_subtitle:
type: boolean
description: Use subtitle extraction instead of ASR
example: false
require_json:
type: boolean
description: >-
Return JSON format results (transcript + storyboard JSON
URIs)
default: true
example: true
require_xlsx:
type: boolean
description: Return per-episode XLSX storyboard files
default: false
example: false
require_merge_xlsx:
type: boolean
description: Return a merged XLSX file combining all episodes
default: false
example: false
concurrency:
type: integer
description: Processing concurrency limit
default: 100
example: 100
required:
- mode
- episodes
- config
responses:
'200':
description: Task submitted successfully
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 200
description: Response code indicating the result status
msg:
type: string
example: success
description: Response message
data:
type: object
properties:
task_id:
type: string
example: ros-sd-20260313-a3f8c2b1
description: Unique identifier of the screenplay task
status:
type: string
example: pending
description: Initial task status
mode:
type: string
example: short_drama
description: The extraction mode used
created_at:
type: string
example: '2026-03-13T10:00:00Z'
description: ISO 8601 timestamp of task creation
total_duration_seconds:
type: number
example: 450.5
description: Total video duration across all episodes in seconds
success:
type: boolean
example: true
description: Indicates whether the operation was successful
failed:
type: boolean
example: false
description: Indicates whether the operation failed
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Authorization
description: API key for authentication
````