Query an asset

Check processing status and details for an asset.

Important: Assets are deleted from time to time. Do not use the asset API as long-term storage. Keep the original files and upload them again if an asset expires.

Endpoint

Endpoint: GET https://api-ai.xiaoku.ai/ark/v1/assets/{asset_id}

Request parameters

Parameter	Description	Required
asset_id	Asset ID	Yes

Example

curl https://api-ai.xiaoku.ai/ark/v1/assets/{asset_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

Response fields

Field	Type	Description
Id	string	Asset ID
Name	string	Asset name
URL	string	Asset URL after review
AssetType	string	Image, Video, or Audio
ProjectName	string	Project name
Status	string	Processing status
Moderation	object	Review details
Moderation.Strategy	string	Review strategy
Error	object	Failure details
Error.Code	string	Error code
Error.Message	string	Error message
CreateTime	string	Created at, UTC
UpdateTime	string	Updated at, UTC

Status values

Status	Meaning	Terminal
Pending	Processing	No. Keep polling.
Active	Ready to use	Yes
Failed	Processing failed	Yes
Deleted	Deleted	Yes

Response examples

Ready

{
    "Id": "asset-20250101000000-0000",
    "Name": "Sample image",
    "URL": "https://api-ai.xiaoku.ai/assets/xxx.jpg",
    "AssetType": "Image",
    "ProjectName": "default",
    "Status": "Active",
    "Moderation": {
        "Strategy": "Default"
    },
    "Error": {
        "Code": "",
        "Message": ""
    },
    "CreateTime": "2025-01-01T00:00:00Z",
    "UpdateTime": "2025-01-01T00:00:05Z"
}

Processing

{
    "Id": "asset-20250101000000-0000",
    "Name": "Sample image",
    "URL": "",
    "AssetType": "Image",
    "ProjectName": "default",
    "Status": "Pending",
    "Moderation": {
        "Strategy": "Default"
    },
    "Error": {
        "Code": "",
        "Message": ""
    },
    "CreateTime": "2025-01-01T00:00:00Z",
    "UpdateTime": "2025-01-01T00:00:01Z"
}

Failed

{
    "Id": "asset-20250101000000-0000",
    "Name": "Sample image",
    "URL": "",
    "AssetType": "Image",
    "ProjectName": "default",
    "Status": "Failed",
    "Moderation": {
        "Strategy": "Default"
    },
    "Error": {
        "Code": "InvalidURL",
        "Message": "Unable to access the asset URL"
    },
    "CreateTime": "2025-01-01T00:00:00Z",
    "UpdateTime": "2025-01-01T00:00:05Z"
}

Polling example

import time
import requests

def wait_for_asset(asset_id, api_key, max_wait=300):
    """Wait until asset processing finishes."""
    start_time = time.time()
    
    while time.time() - start_time < max_wait:
        response = requests.get(
            f"https://api-ai.xiaoku.ai/ark/v1/assets/{asset_id}",
            headers={"Authorization": f"Bearer {api_key}"}
        )
        asset = response.json()
        status = asset.get("Status")
        
        if status == "Active":
            return asset
        elif status in ("Failed", "Deleted"):
            raise Exception(f"Asset processing failed: {asset.get('Error', {}).get('Message')}")
        
        time.sleep(2)  # wait 2 seconds, then query again
    
    raise Exception("Timed out waiting for the asset")

Notes

1. Assets are deleted from time to time. Do not use the asset API as long-term storage.
2. Review usually finishes in a few seconds to a few dozen seconds.
3. Review fails if the asset URL cannot be reached.
4. Poll every 2–5 seconds.
5. Once Status is Active, use the asset in a video generation task.