File-阿里云帮助中心

The <File> element contains the metadata for a single file. It is a child of the <Files> container in the response body of DoMetaQuery, SimpleQuery, and SemanticQuery. Fields are returned on demand. Only existing metadata appears in the <File> element. Fields that do not have a value are not returned as empty tags.

General fields

Name	Type	Required	Example	Description
URI	String	No	oss://examplebucket/photos/sunset.jpg	The full URI of the OSS object. Parent node: File
OSSURI	String	No	oss://examplebucket/photos/sunset.jpg	An alias for URI. This field name is used in some scenarios. Parent node: File
Filename	String	No	photos/sunset.jpg	The filename (the key of the OSS object). Parent node: File
Size	Integer	No	2097152	The file size in bytes. Parent node: File
ContentType	String	No	image/jpeg	The MIME type of the file. Parent node: File
ETag	String	No	"D41D8CD98F00B204E9800998ECF8427E"	The ETag of the OSS object. Parent node: File
ContentMd5	String	No	1B2M2Y8AsgTpgAmY7PhCfg==	The Content-MD5 hash of the file. Parent node: File
OSSCRC64	String	No	12345678901234567890	The CRC-64 checksum of the file. Parent node: File
FileHash	String	No	abc123def456	The hash value of the file content. Parent node: File
ContentEncoding	String	No	gzip	The Content-Encoding set when the object was uploaded. Parent node: File
ContentLanguage	String	No	zh-CN	The Content-Language set when the object was uploaded. Parent node: File
ContentDisposition	String	No	attachment; filename="sunset.jpg"	The Content-Disposition set when the object was uploaded. Parent node: File
CacheControl	String	No	max-age=3600	The Cache-Control set when the object was uploaded. Parent node: File
MediaType	String	No	image	The media type. Valid values: image: Image video: Video audio: Audio document: Document Parent node: File
OSSStorageClass	String	No	Standard	The OSS storage class. Valid values: Standard: Standard IA: Infrequent Access Archive: Archive Storage ColdArchive: Cold Archive DeepColdArchive: Deep Cold Archive Parent node: File
ObjectACL	String	No	default	The access permissions of the OSS object. Valid values: default: Inherits bucket permissions private: Private public-read: Public-read public-read-write: Public-read-write Parent node: File
OSSObjectType	String	No	Normal	The OSS object type. Valid values: Normal: Normal object Multipart: Multipart upload Appendable: Appendable Parent node: File
OSSVersionId	String	No	CAEQNRiBgIDyz.6C0BYiIGQ2Y2I0ZTQ1Mz****	The version ID of the OSS object. Parent node: File
OSSDeleteMarker	String	No	true	Indicates whether the current version is a delete marker. Parent node: File
OSSExpiration	String	No	2026-12-31T00:00:00.000Z	The expiration time specified by the OSS lifecycle rule. The format is RFC 3339. Parent node: File
OSSTagging	Container	No	N/A	A container for the list of OSS object tags. Each tag corresponds to a `<Tagging>` child element, which contains the `<Key>` and `<Value>` fields. For a complete example, see the OSSTagging / OSSUserMeta XML example below. Parent node: File
OSSTaggingCount	Integer	No	2	The number of OSS object tags. Parent node: File
OSSUserMeta	Container	No	N/A	A container for custom OSS user metadata, corresponding to the `x-oss-meta-*` headers used during upload. Each piece of metadata corresponds to a `<UserMeta>` child element, which contains the `<Key>` and `<Value>` fields. For a complete example, see the OSSTagging / OSSUserMeta XML example below. Parent node: File
ServerSideEncryption	String	No	AES256	The server-side encryption algorithm. Parent node: File
ServerSideEncryptionCustomerAlgorithm	String	No	AES256	The encryption algorithm used when a key is provided by the customer. Parent node: File
ServerSideEncryptionKeyId	String	No	9468da86-3509-4f8d-a61e-6eab1eac****	The KMS key ID. Parent node: File
ServerSideDataEncryption	String	No	SM4	The KMS data encryption algorithm. Parent node: File
AccessControlAllowOrigin	String	No	*	The `Access-Control-Allow-Origin` CORS response header. Parent node: File
AccessControlRequestMethod	String	No	GET	The `Access-Control-Request-Method` CORS request header. Parent node: File
CreateTime	String	No	2026-05-20T08:00:00.000+08:00	The time when the metadata was first created. The format is RFC 3339. Parent node: File
UpdateTime	String	No	2026-05-20T08:30:00.000+08:00	The time when the metadata was last updated. The format is RFC 3339. Parent node: File
FileCreateTime	String	No	2026-05-18T10:00:00.000+08:00	The time when the file was created. The format is RFC 3339. Parent node: File
FileModifiedTime	String	No	2026-05-19T15:30:00.000+08:00	The time when the file was last modified. The format is RFC 3339. Parent node: File
FileAccessTime	String	No	2026-05-19T15:30:00.000+08:00	The time when the file was last accessed. The format is RFC 3339. Parent node: File
ProduceTime	String	No	2026-04-01T12:00:00.000+08:00	The time when the content was captured or created, parsed from EXIF or multimedia metadata. The format is RFC 3339. Parent node: File
Timezone	String	No	UTC+08:00	The timezone information. Parent node: File
LatLong	String	No	30.2741,120.1551	The geographic coordinates in `latitude,longitude` format. Parent node: File
Addresses	Container	No	N/A	A list of address resolution results. Each child element is an address record that contains fields such as country, province, city, and district. Parent node: File
DatasetName	String	No	photos-2026	The name of the dataset where the file is located. Parent node: File
Language	String	No	zh	The language of the file. Parent node: File
CustomId	String	No	user-12345	A custom identifier. Parent node: File
CustomLabels	Container	No	N/A	A container for custom tags. Parent node: File
Reason	String	No	N/A	A description of the reason for a file processing failure or an exception. Parent node: File

Image-specific fields

Name	Type	Required	Example value	Description
ImageWidth	Integer	No	4032	The image width in pixels. Parent node: File
ImageHeight	Integer	No	3024	The image height in pixels. Parent node: File
Orientation	Integer	No	1	The EXIF orientation. Parent node: File
EXIF	String	No	{"Make":"Canon",...}	The complete EXIF information as a JSON string. Parent node: File
ImageScore	Container	No	N/A	The image quality score. Child elements include `<OverallScore>`. Parent node: File
CroppingSuggestions	Container	No	N/A	A list of smart cropping suggestions. Parent node: File
OCRContents	Container	No	N/A	The OCR text recognition results in blocks. Parent node: File
OCRTexts	String	No	Merged OCR text content	The OCR text recognition results merged into a single string. Parent node: File

Video/Audio-specific fields

Name	Type	Required	Example	Description
VideoWidth	Integer	No	1920	The width of the video frames in pixels. Parent node: File
VideoHeight	Integer	No	1080	The height of the video frames in pixels. Parent node: File
Duration	Float	No	120.5	The duration in seconds. Parent node: File
Bitrate	Integer	No	8000000	The bitrate in bps. Parent node: File
FormatName	String	No	mov,mp4,m4a,3gp,3g2,mj2	The short name of the container format. Parent node: File
FormatLongName	String	No	QuickTime / MOV	The full name of the container format. Parent node: File
StreamCount	Integer	No	2	The number of multimedia streams. Parent node: File
ProgramCount	Integer	No	1	The number of programs. Parent node: File
StartTime	Float	No	0.0	The start time in seconds. Parent node: File
VideoStreams	Container	No	N/A	A list of video track details. Each child element contains information such as encoding, resolution, frame rate, and bitrate. Parent node: File
AudioStreams	Container	No	N/A	A list of audio track details. Each child element contains information such as encoding, sample rate, and the number of sound channels. Parent node: File
AudioCovers	Container	No	N/A	A list of audio thumbnails. Parent node: File
Subtitles	Container	No	N/A	A list of caption tracks. Parent node: File

Music metadata fields

Name	Type	Required	Example	Description
Title	String	No	Imagine	The title. Parent node: File
Album	String	No	Imagine	The album name. Parent node: File
AlbumArtist	String	No	John Lennon	The album artist. Parent node: File
Artist	String	No	John Lennon	The artist. Parent node: File
Composer	String	No	John Lennon	Composition Parent node: File
Performer	String	No	John Lennon	The performer. Parent node: File

Document-specific fields

Name

Type

Required

Example

Description

PageCount

Integer

The total number of pages in the document.

Parent node: File

AI content understanding fields

Name	Type	Required	Example	Description
Insights	Container	No	N/A	A container for AI content understanding results. It includes elements such as caption, summary, and description, organized by media type. For details about the fields, see the Insights substructure below. Parent node: File
Labels	Container	No	N/A	A container for the list of AI labels. Child node: Label. For details about the fields, see the Labels substructure below. Parent node: File
SemanticTypes	String list	No	N/A	A list of semantic types. Child node: SemanticType. Parent node: File
SceneElements	Container	No	N/A	A list of scene elements, mainly for videos. Child elements include `<FrameTimes>`, `<TimeRange>`, `<VideoStreamIndex>`, and `<Labels>`. Parent node: File
Elements	Container	No	N/A	A list of general elements. Parent node: File

Insights substructure

Child nodes within <Insights> are organized by media type. The common structure is as follows:

Name	Type	Required	Example value	Description
Image	Container	No	N/A	A container for image content understanding results. Parent node: Insights
Video	Container	No	N/A	A container for video content understanding results. Parent node: Insights
Caption	String	No	An orange cat is lying on the living room sofa, with sunlight streaming in from the window.	A short description. Parent node: Insights.Image or Insights.Video
Description	String	No	The image shows a chubby orange cat lying curled up on a light gray fabric sofa.	A detailed description. Parent node: Insights.Image or Insights.Video
Summary	String	No	The video shows the entire process of an orange cat falling asleep and waking up.	A video summary. Parent node: Insights.Video

Labels substructure

Name	Type	Required	Example	Description
Label	Container	No	N/A	A container for a single label. Parent node: Labels Child nodes: LabelName, LabelConfidence, LabelLevel, ParentLabelName, LabelAlias, Language, CentricScore, Clips
LabelName	String	No	Cat	The label name. Parent node: Label
LabelConfidence	Float	No	0.98	The confidence level. The value ranges from `[0, 1]`. Parent node: Label
LabelLevel	Integer	No	2	The label level, used for the system's preset multi-level tag system. Parent node: Label
ParentLabelName	String	No	Animal	The name of the parent label. Parent node: Label
LabelAlias	String	No	Cat	The label alias. Parent node: Label
Language	String	No	zh	The language of the label. Parent node: Label
CentricScore	Float	No	0.85	The centricity score of the label. Parent node: Label
Clips	Container	No	N/A	A list of hit video clips (for video files only). Child node: Clip. Parent node: Label
Clip	Container	No	N/A	A single video clip. Parent node: Clips Child node: TimeRange
TimeRange	Integer list	No	0 5000	The time range of the video clip. It consists of two `<TimeRange>` elements that specify the start time and end time in milliseconds. Parent node: Clip

Figure / Clustering fields

Name	Type	Required	Example	Description
FigureCount	Integer	No	2	The number of figures. Parent node: File
Figures	Container	No	N/A	A list of face or figure details. Each child element contains information such as the figure's bounding box, feature vector, and the cluster it belongs to. Parent node: File
TravelClusterId	String	No	travel-20260520-001	The ID of the travel cluster. Parent node: File

OSSTagging / OSSUserMeta XML example

The XML structure for OSSTagging and OSSUserMeta uses a standard structure with <Key> and <Value> child elements. The user-provided key for a tag or metadata appears inside the <Key> element, not as the XML tag name itself.

OSSTagging:

<OSSTagging>
  <Tagging>
    <Key>routing-dataset</Key>
    <Value>photos-2026</Value>
  </Tagging>
  <Tagging>
    <Key>env</Key>
    <Value>production</Value>
  </Tagging>
</OSSTagging>

OSSUserMeta:

<OSSUserMeta>
  <UserMeta>
    <Key>category</Key>
    <Value>photo</Value>
  </UserMeta>
  <UserMeta>
    <Key>album</Key>
    <Value>vacation</Value>
  </UserMeta>
</OSSUserMeta>