SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsghostcut-api-guide

ghostcut-api-guide

General & other

View repository

Updated 10-16 16:28

About this skill

GhostCut API Guide

This document is the main skill description after installation, intended for Agents executing tasks. The installation command, distribution instructions, and repository-level entry point for new users are in the repository root directory's skills.md; this document only maintains the documentation map, feature routing, parameter hard rules, and maintenance rules that Agents must follow at runtime.

When using this skill, you must work based on the accompanying GhostCut API guide documentation. Do not guess API paths, field names, ID meanings, task types, language codes, or result query processes from memory.

Reference Documentation Map

Detailed documentation is located at references/api-guide/. When a user newly installs the skill, is integrating for the first time, or wants to first run through a minimal example, read references/api-guide/01-quickstart.mdfirst. When the user's goal is relatively broad, or they are not yet sure which API to call, read references/api-guide/llms.txtfirst. When the user only wants to try the feature but has no material, read references/sample-assets.md, which can provide demo video or image URLs, and clearly state that it is not default business material.

Core Entry Points:

  • references/api-guide/00-api-overview.md: Overview, feature selection, main call processes, and documentation routing.
  • references/api-guide/01-quickstart.md: 5-minute quick start, using example payloads to run through the video text removal task and status query.
  • references/api-guide/02-auth-and-sign.md：AppKey、AppSecret acquisition method,AppSign signature rules and authentication errors.
  • references/api-guide/03-media-requirements.md: URL, format, local upload, and batch quantity requirements for videos, images, and SRT.
  • references/api-guide/10-file-upload.md: Upload local videos, SRT, and images, obtain URLs usable by subsequent APIs, and view the video material status enumeration.
  • references/api-guide/11-work-status-query.md: Query /v-w-c/gateway/ve/work/status, and read video work results.
  • references/api-guide/12-point-balance-query.md: Query the valid point card balance corresponding to the merchant of the current AppKey .
  • references/api-guide/27-video-basic-processing.md: Basic video editing, trimming, resolution, intelligent optimization, filters, mirroring, scaling, and frame movement.
  • references/api-guide/13-language-support.md: Languages supported by different features.
  • references/api-guide/14-video-process-status.md：processStatus and common error codes.
  • references/api-guide/15-async-and-callbacks.md: Asynchronous tasks, polling strategies, callback format,Callback-Sign signature verification, retries, and idempotency rules.
  • references/api-guide/51-series-overview.md: Entry point for the translation and globalization module.
  • references/api-guide/52-series-edit-common-task-structure.md: General request structure, field sources, and Python general submission template for translation and globalization.
  • references/api-guide/53-series-edit-task-list.md: Translation and globalization task/list task query.
  • references/api-guide/59-series-edit-errors-and-checklist.md: Translation and globalization error examples and pre-submission checks.
  • references/sample-assets.md: Optional demo videos and image URLs when material is lacking, and usage restrictions.
  • examples/: Copyable minimal request bodies and environment variable templates.

General Basics:

  • Credentials and Signatures:02-auth-and-sign.md。
  • Material URL and Format Requirements:03-media-requirements.md。
  • File Upload and Video Material Status Enumeration:10-file-upload.md。
  • Video Task Status Query:11-work-status-query.md。
  • Point Card Balance Query:12-point-balance-query.md。
  • Language Support:13-language-support.md。
  • Processing Status and Error Codes:14-video-process-status.md。
  • Asynchronous Tasks, Polling, and Callbacks:15-async-and-callbacks.md。

Video AI Processing:

  • Subtitle/Text Removal:21-erase-video-subtitle.md, for mask box rules see 22-inpaint-masks-supplement.md。
  • Subtitle Burning:23-burn-subtitles.md, for subtitle style details see 26-subtitle-style-and-fonts.md。
  • OCR Subtitle Extraction:24-ocr-subtitle-extraction.md。
  • ASR subtitle extraction:25-asr-subtitle-extraction.md。
  • Basic video processing:27-video-basic-processing.md。
  • Background music removal/separation:30-background-music-separation.md。
  • Video translation and re-dubbing:31-video-voice-translation.md, for public voice timbres see 32-public-voice-characters.md; by default, the original video background audio is retained with priority. When the original video has hard subtitles, prioritize combining subtitle erasure parameters in the same request.

Image AI processing:

  • AI image processing:81-image-processing.md, including image text erasure, image translation, secondary fine-tuning of translation results, and re-composition.

Translation and overseas distribution features:

  • Subtitle extraction:54-series-subtitle-extract.md。
  • Subtitle erasure:55-series-subtitle-inpaint.md。
  • AI dubbing:56-series-dubbing.md。
  • Subtitle burning:57-series-subtitle-burn.md。
  • Audio separation:58-series-audio-separate.md。
  • Projects and video materials:60-series-project-and-video-materials.md。
  • Subtitle materials and slInfo：61-series-subtitle-materials.md。
  • Subtitle translation:62-series-subtitle-translation.md。
  • Translation glossary:63-series-translation-glossary.md。
  • Multi-work merging:64-series-video-merge.md。
  • Series character management:65-series-character-management.md。

Usage flow

  1. When a new user is getting started for the first time or wants to first run through the minimal closed loop, read 01-quickstart.mdfirst. You can use examples/video-inpaint-advanced-lite-fullscreen.payload.json to create a video text removal task.
  2. First determine whether the user wants to call the regular single-video API or the translation and overseas distribution module. By default, prioritize the regular single-video API; only when the user explicitly mentions "translation and overseas distribution", short drama/AI drama overseas distribution, series, project-level materials, batch series processing,idSeries or idMaterialVideo , recommend the translation and overseas distribution module.
  3. For regular single-video tasks, read 00-api-overview.mdfirst; for signature authentication issues, read 02-auth-and-sign.md; for material URL, format, and upload constraints, read 03-media-requirements.md; for translation and overseas distribution tasks, read 51-series-overview.md。
  4. Before assembling parameters, you must read the corresponding feature documentation. Do not infer API paths or field names from memory.
  5. Keep the request hierarchy as in the documentation. Regular translation and overseas distribution editing tasks use items[]、workDto、videoEditParamsDto; multi-work merging uses the JSON string data in episodes[]。
  6. If the user provides a local file path, read 10-file-upload.md first to complete the upload; task creation APIs usually require a URL or material ID and do not directly accept local paths.
  7. When language fields are involved, read 13-language-support.md. Do not guess language codes based on common sense.
  8. Query status and results according to the correct flow:
    • Regular single-video task: after creating the task, get the work ID, then call /v-w-c/gateway/ve/work/status。
    • Translation and overseas distribution task: first call task/list; if you need the work ID, playback address, or work details, use task/list.body[].id as the project/task ID to call /v-w-c/gateway/ve/work/status, then read the work ID from body.content[].id .

Quick routing

  • User provides a local file path: read 10-file-upload.md. When actual upload is needed, use scripts/ghostcut_api.py upload。
  • User is using the skill for the first time, wants to quickly run through the API, or requests a minimal example: read 01-quickstart.md, prioritize using examples/video-inpaint-advanced-lite-fullscreen.payload.json。
  • User has no video or image but wants to try it: read references/sample-assets.md, provide a demo video or image URL according to the goal, and remind them that features depending on speech, subtitles, series context, or real layout quality should be switched to real materials.
  • User asks about API Key,AppKey、AppSecret, where to obtain credentials, how to sign, or how to authenticate: read 02-auth-and-sign.md。
  • User asks about account balance, point card balance, available points, remaining points, or merchant balance: read 12-point-balance-query.md。
  • The user asks about video/image formats, URLs cannot contain Chinese characters, whether local files can be uploaded directly, batch urls quantity limits: read 03-media-requirements.md。
  • The user asks about video material status, upload status, transcoding status, or the post ordinary upload / translation export upload processStatus: read 10-file-upload.md video material status enum; do not apply the /work/status work processing status table.
  • The user wants to query the result of a single ordinary video: read 11-work-status-query.md, and when an actual query is needed, use scripts/ghostcut_api.py work-status。
  • The user wants to understand async tasks, polling strategies, callback,Callback-Sign signature verification, retries, or idempotency: read 15-async-and-callbacks.md. For production integration, callbackis preferred, with polling as active query and compensation fallback.
  • The user wants to do basic video editing, trimming, resolution, intelligent optimization, filters, mirroring, scaling, or frame movement: read 27-video-basic-processing.md。
  • The user wants to do video speech translation, dubbing, or re-dubbing: read 31-video-voice-translation.md; by default use removeBgAudio=0 to preserve the original video background sound. Only when the user explicitly requests muting, no original sound, removal of background music, or keeping only AI speech/ambient sound, switch to removeBgAudio=1 or 2. If the original video frame already has hard subtitles, read the combined scenario; speech translation and subtitle erasure are usually combined with parameters in the same /work/free request, and should not be split into two separate processing steps by default.
  • The user only says video translation, video dubbing, e-commerce short videos, localization, multilingual subtitles, subtitle removal, or subtitle burning, but does not explicitly say "translation export", short drama/AI drama export, series, project-level materials, or idSeries: by default follow the ordinary single-video video AI processing documentation, and do not proactively recommend the translation export solution.
  • The user wants to query translation export tasks: read 53-series-edit-task-list.md, and when an actual query is needed, use scripts/ghostcut_api.py task-list。
  • The user wants to continue processing based on a previous translation export result: first query task/list to get the task ID, then query /work/status to get body.content[].id as the work ID.
  • The user wants to merge multiple existing works under the same series into a long video: read 64-series-video-merge.md; submit the work IDs in the order of data.episodes[] . The creation response body is already the merged work ID, and /work/status。
  • can be queried directly. The user wants to create, query, update, delete, restore, or copy translation export series roles: read 65-series-character-management.md; the role list object's id corresponds to id_ve_character。
  • The user wants translation export dubbing: at minimum read 51-series-overview.md、52-series-edit-common-task-structure.md、56-series-dubbing.md; when voice timbre is involved, read 32-public-voice-characters.md; when subtitle style is involved, read 26-subtitle-style-and-fonts.md。
  • The user wants to process text in images, image translation, text erasure in images, image translation refinement, or Image Redo: read 81-image-processing.md; when local images are involved, first read 10-file-upload.md; when languages are involved, read 13-language-support.md。

Strong rules

  • The response body business success code of the GhostCut gateway interface is uniformly judged by code == 1000 ; do not confuse HTTP 200 with the response body business code .
  • Do not treat task/list.body[].id as a work ID. It is a task ID, and can also be understood as a project ID.
  • When a subsequent translation export task needs workDto.materialWorkIds , take /work/status.body.content[].id。
  • Multi-work merging does not use items[]、workDto or videoEditParamsDto; the top-level data must be a JSON string containing episodes[] .
  • Do not use idRelation as a business field.
  • When there is no clear intent to translate for overseas distribution, the translate-for-overseas-distribution module is not recommended; general needs such as ordinary video translation, dubbing, subtitle erasure, subtitle burn-in, and e-commerce short video localization use by default the /v-w-c/gateway/ve/work/free video AI processing solution.
  • In translate-for-overseas-distribution AI dubbing and subtitle burn-in, bothworkDto.idVeMaterialSrt and workDto.extraOptions.customer_input.content[] must be passed; subtitles must not be omitted entirely, and do not pass only one of them.
  • workDto.idVeMaterialSrt comes from translate-for-overseas-distribution subtitle assets: the body.idMaterialSrt、series/srt/create of the body.iduploaded from a local SRT, the series/srt/list queried via body[].idafter subtitle extraction/subtitle translation, or the body[].id。
  • Classic dubbing mode uses wyTaskType=FULL, and passes character_voices[]。
  • Emotion clone mode uses wyTaskType=VOICE_CLONE_PRO, and does not pass character_voices[]。
  • voice_type=CLONE indicates an ultra-realistic voice in classic mode, not emotion clone mode.
  • Public voices uniformly use character_voices[].id_ve_voice_character, with values taken from the voicecharacter/aggregate/list returned by body[].id。
  • id_ve_character is the business role ID in the current series, from the series role list or subtitle role information;id_ve_voice_character is the public voice ID. The two cannot be interchanged.
  • Whether translate-for-overseas-distribution AI dubbing requires subtitle erasure first depends on whether the original asset already has no hard subtitles, and whether this dubbing has reused the work after subtitle erasure via workDto.materialWorkIds ; if neither is the case, ask the user whether a subtitle erasure task should be created first.
  • Ordinary single-video speech translation and re-dubbing pass removeBgAudio=0by default, prioritizing preservation of the original video background audio; do not use removeBgAudio=1 global mute by default.
  • For ordinary single-video speech translation + subtitle erasure, parameters can be combined in the same /v-w-c/gateway/ve/work/free request; do not erase first and then translate by default, unless the user explicitly requests two-step processing.
  • Subtitle erasure mask boxes and OCR boxes use 0 to 1 relative coordinates, with the point order being top-left, top-right, bottom-right, bottom-left.

Available scripts

Scripts are located at scripts/, used to reduce repetitive signing, uploading, and querying code. Before running the scripts, first obtain credentials and set environment variables according to 02-auth-and-sign.md ; do not write real keys into documents or commit them to repositories.

Common commands:

  • python scripts/ghostcut_api.py sign --payload payload.json: generate for the JSON request body AppSign。
  • python scripts/ghostcut_api.py post --path /v-w-c/gateway/ve/work/status --payload payload.json: send a signed GhostCut JSON request.
  • python scripts/ghostcut_api.py upload --file /path/input.mp4 --material-file-type video: upload a local file, output the URL and OSS key.
  • python scripts/ghostcut_api.py work-status 521461135: query /v-w-c/gateway/ve/work/status and summarize the status and common result URLs.
  • python scripts/ghostcut_api.py point-balance: query the point card balance of the merchant corresponding to the current AppKey .
  • python scripts/ghostcut_api.py task-list --id-series 10001 --task-type-in SERIES_CLIP2 SERIES_CLIP3: query the translate-for-overseas-distribution task list.

Minimal example:

  • examples/.env.example: environment variable template.
  • examples/video-inpaint-advanced-lite-fullscreen.payload.json: video text removal high-erasure Lite, full-screen box selection create task request body.
  • examples/work-status.payload.json: ordinary video task status query request body.
  • examples/image-translate.payload.json: image translation create task request body.

When maintaining snapshots, use:

  • python scripts/sync_api_guide.py --check: check whether the current references/api-guide/ snapshot directory exists, and confirm that the llms.txt index covers all Markdown documents.
  • python scripts/sync_api_guide.py --check --source /path/to/api-guide: if there is another external source document directory, explicitly specify it and then compare whether it is consistent with the skill snapshot.
  • python scripts/sync_api_guide.py --source /path/to/api-guide: if there is another external source document directory, explicitly specify it and then sync it to the skill snapshot.

Documentation writing and maintenance

When updating the accompanying API guide, keep the Agent-oriented approach:

  • Recommended stable section order: checklist, usage flow, key fields, request body, complete Python example, result query, Agent decision rules, related documentation.
  • The Python example must be directly copyable: include imports, credential placeholders, signature function, request body, POST call, and result printing.
  • Avoid speculative wording, incomplete placeholders, internal historical phrasing, and explanations of fields not used in the business flow.
  • Prefer linking long tables and general rules to shared documentation; do not repeatedly maintain subtitle styles, language lists, status enums, or mask box rules across multiple feature documents.
  • The current accompanying API guide is maintained directly in references/api-guide/. Only when an external source document directory exists, use sync_api_guide.py --source /path/to/api-guide for comparison or synchronization.