Intelligent production FAQ

How do I export an output video to ApsaraVideo VOD?

When you call the SubmitMediaProducingJob operation to submit a production job, set the OutputMediaTarget parameter to vod-media. In the OutputMediaConfig parameter, set StorageLocation and FileName to the storage location and the filename of the media asset in ApsaraVideo VOD:

"OutputMediaConfig": {
  "StorageLocation": "outin-8e7*******.oss-cn-shanghai.aliyuncs.com",
  "FileName": "vod-output.mp4"
}

How do I get the results of an intelligent production job?

After you call the SubmitMediaProducingJob operation to submit a production job, the response includes a JobId. Call the GetMediaProducingJob operation and pass the JobId to query the job, and then use the returned Status field to determine the job status.

How long does an intelligent production job take?

Production time is roughly equal to the duration of the output video. A 5-minute output video typically takes about 5 minutes to produce. Every job also needs time for queuing, file analysis, and downloading, so even the shortest output video takes at least 15 seconds. Depending on complexity, production time for a 15-second video normally ranges from 10 seconds to 2 minutes. If you submit a large batch of jobs at once, such as tens of thousands, the jobs are queued and processed in order. To increase processing capacity, submit a ticket.

What factors affect production time?

Production processes video frame by frame, so the higher the resolution and the longer the output video, the longer production takes. Production time also increases when the output video uses many special effects or transitions, or when source media is scaled, for example, downscaling 4K media to 480p. An incorrect timeline configuration can also increase production time. If production time does not match your expectations, submit a ticket for technical support or join the support group on DingTalk (ID: 84650000851).

Why is the output video duration different from what I expected?

• "Transitions shorten the output duration." A transition is the passage from one clip to the next, and both clips play during the transition, so the second clip starts earlier and the total duration shrinks. To keep the original duration, leave enough room for the transition when you trim clips. Alternatively, use DLTransition to pad frames during the transition and preserve the output duration.

• "AI_TTS can extend the total duration." When you use AI_TTS, the generated audio clips can be longer than the video track, which extends the overall output. The approach in Automatically align the duration of different media clips resolves this issue.

• "An incorrect timeline configuration changes the duration." If you set only TimelineIn and TimelineOut without setting In and Out, each clip is processed at its original duration. Set in = 0 and out = timelineOut - timelineIn to control how clips are processed.

Why does my output video show a black screen after a certain time?

A black screen usually means that your video media is shorter than another track. For example, if the video clip is 6 seconds long but the audio track is 12 seconds long, everything after 6 seconds renders as a black screen. To fix this, set the video track as the main track so that other tracks align to it, or plan the length of the other tracks so that they match the video track.

Why do I receive a "TimelineFormatError" when calling the API?

Check that the timeline matches the format defined in Timeline configuration and that the JSON contains no syntax errors. The timeline examples in Mix and edit videos and images cover the most common structures.

Why do subtitles fail to display, appear garbled, or render incorrectly after I add them?

If you use a less common language such as Korean, Arabic, or Mongolian, font rendering can cause these issues. Submit the job with the default font (Alibaba PuHuiTi). If the issue persists, search for DingTalk group 84650000851 and join the "Intelligent Media Services product group" to contact us.

Why is the output position of images, text, or subtitles incorrect?

• Make sure that the output frame size matches the preview size. Relative position values between 0 and 1 keep the layout consistent across sizes.

• If clips on the same track overlap in time or position, the anti-collision mechanism may shift their positions. Split these clips onto different tracks to arrange their positions and timing more flexibly.

Why does the subtitle FontSize not match the preview?

• If you use the FontSize property in Effect Type: Text, the font size is scaled based on the clip size and the output video size. Change FontSize to FixedFontSize to keep the font size from being scaled.

• You can use a SubtitleTrackClip subtitle track to specify subtitle content. If you specify a subtitle font, the rendered subtitle height in pixels may be smaller than the font size for certain fonts. Set SizeRequestType=Nominal to make the rendered height in pixels equal to the font size.

• Specifying a preview size keeps the output font size consistent with the preview. For example, to produce a 720p output video, set the preview size parameter to FECanvas={"Height":720,"Width":1280}.

What do I do if I receive a "Throttling.User" error when submitting a job?

• The write operations of IMS are usually limited to 30 QPS. Throttling can occur when you submit jobs at a high concurrency. In this case, wait one second and then continue submitting jobs.

• At 30 QPS, you can submit 1,800 jobs per minute, which meets the needs of most customers. If your business requires sustained submissions above 30 QPS for tens of minutes, for example, producing millions of videos within half an hour for an operational activity, submit a ticket to request a QPS increase.

What should I do if the index analysis fails?

On the Media Asset Management page, select the media asset that you want to re-analyze and click Index Analysis below the list to start a new index analysis job.

What do I do if a production operation returns an insufficient permissions error or Forbidden.SubscriptionRequired?

This error has two possible causes:

• "Insufficient account permissions": Grant the RAM user the AliyunICEFullAccess policy, or a custom policy that includes actions such as ice:SubmitMediaProducingJob, and make sure that the region of the project is the same as the region of the API call.

• "The service is not activated": A Forbidden.SubscriptionRequired error means that you have not subscribed to the required edition or purchased the feature trial package. Subscribe and then try again.

How do I troubleshoot a high production job failure rate?

Troubleshoot in the following order:

• Check the source files: Use a tool such as ffprobe to confirm that the audio and video streams are complete, the metadata is normal, and the format is within the supported range.

• Check the storage region: Make sure that the input and output OSS buckets are in the same region as IMS. Some regions, such as Guangzhou and Chengdu, are not supported.

• Check the timeline parameters: Verify the structure and the field names against the timeline configuration documentation, and make sure that parameters such as MediaId and the duration are correct.

What are the most common timeline configuration errors?

• Effect tracks cannot overlap: Place each effect on a separate track so that effects within EffectTracks do not overlap in time.

• The "Both video tracks and audio tracks are empty" error: The timeline was not passed in the required format. Correct the structure against the documentation.

• MediaId must be a real media asset ID: Do not use a variable placeholder format. Field names must start with a capital letter.

• Configure transition parameters within the video clip instead of creating a separate transition track.

• Do not mix in SSML tags from Intelligent Speech Interaction. Parameters of AudioTrackClips such as Content and Volume must follow the IMS documentation.

How do I control the number of output videos and the title style in automated video production?

• OutputConfig.Count controls the number of output videos. Valid values: 1 to 100. Default value: 1. This parameter applies to scripted automated production and intelligent image-and-text matching production.

• If character spacing is abnormal, set ModifySpacing to true in SubHeadingConfig and reduce the Spacing value.

• A single title supports only one color. To use multiple colors, configure multiple titles in TitleArray and specify a color for each title.

• If copy that contains special characters fails to generate, escape the special characters as required by SSML and submit the job again.

Why does my advanced (AE) template fail to upload?

The template package must meet all of the following requirements:

• The package uses the .zip format. RAR and 7z are not supported.

• The package name contains no Chinese characters or special symbols.

• The package contains the four root directories assets, config.json, datas, and ui.

• The current region supports advanced templates.

  Note that IMS cannot export AE projects and supports exporting Premiere Pro projects only.

Do I need to manually clean up the media assets generated by production jobs?

Output videos generated through the API are automatically registered as media assets and incur storage and management fees. Call DeleteMediaInfos to delete them when they are no longer needed. Do not write the output of two jobs to the same storage location, because the jobs overwrite each other and produce abnormal output videos.

Quick answers to other common questions

• Get the output video URL: A production job is an asynchronous task. After you submit a job, call GetMediaProducingJob to query the job status and get the URL of the output video. You can also receive results through event callbacks (message queues). Make sure that you select the corresponding message type.

• Black screen at the end of an output video: This is usually caused by a mismatch between the video track and the audio track. Adjust the ClipId and ReferenceClipId of the last clip to align the two tracks.

• Custom fonts: After you upload a font file, the system generates a corresponding MediaId. Pass the MediaId values in customFontList to use the fonts.

• Transparent backgrounds for real-scene matting: If you do not pass a background image parameter, the output can be a WEBM file with an alpha channel. Real-scene matting requires a solid-color background and does not apply to complex backgrounds such as homes or outdoors.

• Automatic clipping of live streams: Call the SubmitLiveEditingJob operation.

• Callbacks are not real time: Event callbacks are not guaranteed to be strictly synchronized with job completion, so do not make your business logic fully dependent on callbacks. Poll the job status as the primary method and use callbacks as a supplement. Set the polling interval to at least 5 seconds.

• What automated video production can define besides media: Openings, endings, titles, subtitles, background music, and voiceover scripts can all be defined through the timeline or template parameters. You can find the template ID in Template Factory in the console, and find the endpoint of a bucket on the overview page of the OSS console.

How do I identify the exact cause of a failed production job?

Get the error message yourself and match it to a cause instead of waiting for manual investigation.

• Get the JobId returned when you submitted the job. You can also find it in the job list in the console.

• Call GetMediaProducingJob with the JobId. Check Status first to determine the job stage, and then read the error message in the response.

• Handle the error by category: for account errors such as Forbidden.SubscriptionRequired, insufficient permissions, or an overdue account, resolve the account status first; for parameter errors such as TimelineFormatError, empty tracks, or incorrect field types, correct the parameters first; for media errors such as an unsupported format or abnormal stream information, validate the source file first.

  When you submit a ticket, provide both the JobId and the complete request parameters. A report of only "job failed" cannot be diagnosed.

What do I do if a job fails with a VideoTracks or AudioTracks parameter error?

In a timeline, VideoTracks, AudioTracks, ImageTracks, and SubtitleTracks are all "arrays" and must be enclosed in [ ]. A job fails immediately if you pass an object enclosed in { } by mistake. Even when only one track exists, write it as a single-element array, for example "VideoTracks": [{"VideoTrackClips": [...]}].

What do I do if I receive the "Track duration adaptation and material alignment cannot be used at the same time" error?

Track duration adaptation and clip alignment are mutually exclusive and cannot be used in the same job.

• Track duration adaptation is controlled by TrackShortenMode and TrackExpandMode, such as AutoSpeed.

• Clip alignment is controlled by ClipId and ReferenceClipId.

  To resolve the error, search for these fields in the timeline and delete one set. Keep TrackShortenMode and TrackExpandMode if you need automatic speed adjustment, or keep ReferenceClipId if you need to align clips to a specified clip.

What do I do if I receive the "User not authorized to operate on the specified resource" error or a 403 status code?

This error means that the input file URL cannot be read. Troubleshoot in the following order:

• Use a complete URL that starts with https to pass the parameter. Some manually concatenated URL formats are rejected during validation.

• Make sure that the bucket and IMS are in the same region, and that the service-linked role is authorized.

• When you call the operation as a RAM user, make sure that the user has the read permissions on OSS and the role assumption permission.

How do I tell whether a job that stays in the processing state is abnormal?

• Compare the elapsed time against expectations first: production time is usually equal to the output video duration, and even the shortest output video takes at least 15 seconds. Jobs are queued when you submit a large batch at once.

• The processing state does not mean that all subtasks are normal. For batch jobs, the main job can complete while some subtasks fail. Query the result of each subtask instead of relying only on the summary status.

• If the elapsed time far exceeds expectations, for example, a short video is still incomplete after 30 minutes, provide the JobId and the submission time when you submit a ticket.

How do I prevent an abnormally high bill from a single job?

The most common cause is an incorrect timeline configuration that makes the actual output video far longer than expected. A single job once produced an output video hundreds of thousands of seconds long, and production is billed by the processed duration. Complete the following two checks before you submit jobs in batches:

• Check that In and Out are set in pairs with TimelineIn and TimelineOut for every clip. If you set only TimelineIn and TimelineOut, the clip is processed at its original duration.

• Add an upper limit check on the output video duration in your business logic and block submissions that exceed the expected threshold. Run one or two test jobs and verify the bill before you scale up.

What are the media requirements if an uploaded file fails after I submit it?

Use audio and video files in common container formats such as MP4 and MOV, and make sure that the files play correctly. Before submission, use ffprobe to confirm that the audio and video streams are complete and the metadata is normal. Files with abnormal encoding, a missing video stream, or a rare container format often fail during the analysis phase. Images are less stable than videos in some automated production scenarios. If an output video does not use all of your images as expected, verify the job with video files first.

Why are files still in my bucket after I delete media assets?

Media asset records and physical files are two separate layers. Deleting a media asset does not delete the source file in OSS by default, and the storage fees do not stop automatically.

• To delete the physical files as well, explicitly set the parameter that deletes physical files when you call the delete operation, for example, set DeletePhysicalFiles to true.

• Uploaded media and production outputs do not behave identically: output videos generated through the API are automatically registered as media assets, and deleting them may require you to clean up the output files in OSS separately.

• For bulk cleanup, call DeleteMediaInfos to delete the media asset records first, and then confirm on the OSS side that the corresponding directory is empty.

What is the default validity period of a private Object Storage Service (OSS) URL returned by Intelligent Media Services (IMS)?

By default, a private OSS URL returned by Intelligent Media Services (IMS) is generally valid for 1 hour. To determine the exact expiration time, check the expier parameter in the URL.

What do I do if the media asset library shows storage usage but no specific files?

This issue usually occurs because the source video files are stored in the associated OSS bucket, but the deletion operation did not also delete the source files from OSS. Troubleshoot and resolve the issue as follows:

1. Confirm that Intelligent Media Services (IMS) is authorized to access the corresponding OSS bucket under the current account.

2. Grant the IMS service-linked role the permission to delete OSS objects. You can configure this permission in the Alibaba Cloud Management Console without writing code.

3. After authorization is complete, run the deletion operation again. The system deletes the source files and derived files, such as transcoded and edited files, from OSS, releases the occupied storage, and synchronizes the media asset library list.