Query file status

Query detailed information and current status of a file by file ID.

Status descriptions:

pending: Waiting for processing

uploading: Uploading to target storage

ready: Upload complete, available for inference

failed: Upload failed, check error field for details

expired: File has expired, needs to be recreated

🚀 Call Example: From Import to Inference

The following demonstrates how to use the file in model inference APIs after file processing is complete and file_id is obtained.

Scenario: Video Understanding

Assume you have uploaded a long video through this API and obtained the file ID: qfile-123-1770719212268100147-e0011b.

Request description:
In the inference API (Chat/Completions) messages array, specify type as file or image_url, and fill in the corresponding file_id or url.

Request body (JSON):

{
    "stream": false,
    "model": "gemini-3.0-pro-preview",
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "What happened in this video? Please describe in detail."
                },
                {
                    "type": "file",
                    "file": {
                        "file_id": "qfile-123-1770719212268100147-e0011b",
                        "format": "video/mp4"
                    }
                }
            ]
        }
    ]
}

Responses

🟢200

application/json

Successfully returns file details

Bodyapplication/json

Examples

File readyFile waiting for processingFile sync failed

{
    "id": "qfile-12345-1705382400-abc123",
    "object": "file",
    "status": "ready",
    "model": "gemini-2.0-flash",
    "created_at": 1705382400,
    "synced_at": 1705382450,
    "expires_at": 1705555200,
    "file_name": "sample.pdf",
    "file_size": 1048576,
    "content_type": "application/pdf"
}

🟠400

🟠401

🟠404

🔴500

🚀 Call Example: From Import to Inference#

Scenario: Video Understanding#

Request

Request Code Samples

Responses

🚀 Call Example: From Import to Inference

Scenario: Video Understanding