# Check an asset

`GET /v1/assets/{asset_id}`

Requires service.use and an asset owned by your team. Unknown IDs, deleted assets and assets owned by another team all return asset_not_found. Active assets include their size and digest, plus dimensions or duration where applicable. These measurements are omitted during processing or when unavailable. The original source address is never returned.

- Put your API key after `Authorization: Bearer`; the key needs `service.use` permission.
- Only your team's assets are visible; any other ID returns `asset_not_found`.
- `active` assets return dimensions, size and digest; for `unavailable`, read `failure_reason`.

## Headers

| Field | Type | Requirement | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Required | Bearer, a space and your API key. A missing or invalid key returns 401 authentication_failed. |
| `X-Request-ID` | string | Optional | Your own request identifier. An invalid or repeated value is replaced; the value used comes back in the X-Request-ID response header. |

## Path parameters

| Field | Type | Requirement | Description |
| --- | --- | --- | --- |
| `asset_id` | string | Required | ID of an asset owned by the signed-in team. Length: 36–36. Format: ast- and 32 hex digits. |

## Returns · HTTP 200

The asset's current state and the metadata safe to return at that state.

Returns [The asset object](./api-docs-en-api-assets-object.md); its fields are described there.

### Response headers

| Field | Type | Requirement | Description |
| --- | --- | --- | --- |
| `X-Request-ID` | string | Required | The identifier of this request: the valid value you sent, or its replacement. |
| `Cache-Control` | string | Required | Instructs clients not to cache the response. |

## Status codes

Each `error.code` and what to do about it is on [Error codes](./api-docs-en-api-errors.md).

| Status | Meaning | error.code |
| --- | --- | --- |
| 200 | The asset's current state and the metadata safe to return at that state. Response headers: `Cache-Control` |  |
| 400 | The submitted request is not valid. | invalid_request |
| 401 | The API key is missing or invalid. Response headers: `WWW-Authenticate` | authentication_failed |
| 403 | This API key does not have service.use permission. | permission_denied |
| 404 | No visible asset matches this ID. | asset_not_found |
| 503 | The service is temporarily unavailable. | dependency_unavailable |

## Related guides

- [Upload assets](./api-docs-en-assets.md)
- [Generate a video](./api-docs-en-video-generate.md)

## Request examples

```bash
curl --request GET "${CHENVOYA_BASE_URL}/v1/assets/${ASSET_ID}" \
  --header "Authorization: Bearer ${CHENVOYA_API_KEY}"
```

```python
import urllib.request
import urllib.parse
import json
import os
import sys
import re
import uuid

key = os.environ["CHENVOYA_API_KEY"].strip()
if not key or re.search(r"[\x00-\x1f\x7f-\x9f]", key):
    sys.exit("Set CHENVOYA_API_KEY to a non-empty value without control characters")
base = os.environ["CHENVOYA_BASE_URL"].rstrip("/")
headers = {"Authorization": "Bearer " + key}
ASSET_ID = os.environ["ASSET_ID"]
if not re.fullmatch("^ast-[0-9a-f]{32}$", ASSET_ID):
    sys.exit("Set ASSET_ID to the ID from the creation response")
path = "/v1/assets/{asset_id}".replace("{asset_id}", urllib.parse.quote(ASSET_ID, safe=""))
request = urllib.request.Request(base + path, data=None, headers=headers, method="GET")
try:
    with urllib.request.urlopen(request) as response:
        print(response.read().decode("utf-8"))
except urllib.request.HTTPError as error:
    print(error.read().decode("utf-8"))
    sys.exit(1)
```

```javascript
// Needs Node.js 20 or later; save it as a .mjs file and run it.
const key = process.env.CHENVOYA_API_KEY?.trim();
if (!key || /[\x00-\x1f\x7f-\x9f]/.test(key)) {
  console.error("Set CHENVOYA_API_KEY to a non-empty value without control characters");
  process.exit(1);
}
const base = process.env.CHENVOYA_BASE_URL;
if (!base) throw new Error("Set CHENVOYA_BASE_URL");
const headers = {Authorization: `Bearer ${key}`};
const ASSET_ID = process.env.ASSET_ID;
if (!ASSET_ID) throw new Error("Set ASSET_ID");
if (typeof ASSET_ID !== "string" || (new RegExp("^ast-[0-9a-f]{32}$")).exec(ASSET_ID)?.[0] !== ASSET_ID) throw new Error("Set ASSET_ID to the ID from the creation response");
const path = "/v1/assets/{asset_id}".replace("{asset_id}", encodeURIComponent(ASSET_ID));
const response = await fetch(base.replace(/\/$/, "") + path, {method: "GET", headers, body: undefined});
console.log(await response.text());
if (!response.ok) process.exitCode = 1;
```

```go
package main

import (
	"fmt"
	"io"
	"net/http"
	"net/url"
	"os"
	"regexp"
	"strings"
)

func main() {
	key := strings.TrimSpace(os.Getenv("CHENVOYA_API_KEY"))
	if key == "" || regexp.MustCompile(`[\x00-\x1f\x7f-\x9f]`).MatchString(key) {
		fail("Set CHENVOYA_API_KEY to a non-empty value without control characters")
	}
	base := strings.TrimRight(os.Getenv("CHENVOYA_BASE_URL"), "/")
	if base == "" {
		fail("Set CHENVOYA_BASE_URL")
	}
	assetID := os.Getenv("ASSET_ID")
	if assetID == "" {
		fail("Set ASSET_ID")
	}
	if !regexp.MustCompile(`\A(?:ast-[0-9a-f]{32})\z`).MatchString(assetID) {
		fail("Set ASSET_ID to the ID from the creation response")
	}
	path := strings.Replace("/v1/assets/{asset_id}", "{asset_id}", url.PathEscape(assetID), 1)
	request, err := http.NewRequest("GET", base+path, nil)
	if err != nil {
		fail(err.Error())
	}
	request.Header.Set("Authorization", "Bearer "+key)
	response, err := http.DefaultClient.Do(request)
	if err != nil {
		fail(err.Error())
	}
	text, err := io.ReadAll(response.Body)
	response.Body.Close()
	if err != nil {
		fail(err.Error())
	}
	fmt.Println(string(text))
	if response.StatusCode < 200 || response.StatusCode > 299 {
		os.Exit(1)
	}
}

func fail(message string) {
	fmt.Fprintln(os.Stderr, message)
	os.Exit(1)
}
```

## Response examples

200

```json
{
  "asset_id": "ast-11111111111111111111111111111111",
  "object": "asset",
  "media_type": "image",
  "model": "dreamina-seedance-2-0-260128",
  "name": "reference",
  "created_at": 1700000000,
  "updated_at": 1700000100,
  "status": "processing"
}
```

400

```json
{
  "error": {
    "code": "invalid_request",
    "message": "request parameters are invalid"
  },
  "trace_id": "trace_error_example"
}
```

401

```json
{
  "error": {
    "code": "authentication_failed",
    "message": "authentication failed"
  },
  "trace_id": "trace_error_example"
}
```

403

```json
{
  "error": {
    "code": "permission_denied",
    "message": "permission denied"
  },
  "trace_id": "trace_asset_permission"
}
```

404

```json
{
  "error": {
    "code": "asset_not_found",
    "message": "asset not found"
  },
  "trace_id": "trace_asset_missing"
}
```

503

```json
{
  "error": {
    "code": "dependency_unavailable",
    "message": "service is not ready"
  },
  "trace_id": "trace_error_example"
}
```