Asset (Tư liệu tham chiếu)

Thông tin chung

• Base URL: https://api.routeapi.ai
• Xác thực: Authorization: Bearer $ROUTEAPI_KEY với API Key bắt đầu bằng sk- (tạo tại trang API Key). Khóa quản lý bắt đầu bằng rat_ không thể gọi mô hình.
• Định dạng lỗi: trên các endpoint này, lỗi do RouteAPI tự trả về có dạng {"error": "..."} hoặc {"error": "...", "code": "..."}; yêu cầu bị middleware xác thực hoặc giới hạn tần suất chung từ chối có thể nhận {"error": {"message": "...", "type": "error", "code": "..."}}. Mã trạng thái và body của upstream được truyền nguyên vẹn. Xem Giới hạn và lỗi bên dưới và Lỗi thường gặp.

API asset lưu trữ tư liệu tham chiếu — hình ảnh, video, âm thanh — mà các mô hình video Seedance có thể nhận làm đầu vào. Bạn thêm tư liệu một lần, chờ dịch vụ asset phía upstream xử lý xong, sau đó tham chiếu nó bằng asset://<asset_id> trong yêu cầu tạo video thay vì phải truyền lại cùng một URL công khai mỗi lần.

Đây là API quản lý, không phải API tạo nội dung. RouteAPI xác thực lệnh gọi bằng API Key của bạn, chuyển tiếp đến dịch vụ asset phía upstream và trả về phản hồi của upstream. Các lệnh gọi trên những endpoint này không bị tính phí như mức sử dụng mô hình. Chúng cũng nằm ngoài phạm vi OpenAI SDK, nên hãy dùng HTTP thuần thay vì client SDK.

Body được chuyển tiếp nguyên vẹn

RouteAPI không định hình lại payload của asset. Ngoài các giới hạn kích thước và cách xử lý nêu dưới đây, body yêu cầu và phản hồi được truyền nguyên vẹn, nên tập trường hiển thị ở đây chính là hợp đồng của upstream. Đừng coi tập trường phản hồi chính xác là bất biến.

Quy trình

1. Tạo nhóm asset bằng POST /v1/asset-groups.
2. Thêm asset vào nhóm đó bằng POST /v1/assets, truyền một URL có thể tải xuống công khai.
3. Thăm dò asset bằng GET /v1/assets/{assetID} cho đến khi trạng thái là Active. Quá trình xử lý là bất đồng bộ.
4. Tham chiếu asset bằng asset://<asset_id> trong metadata.content của yêu cầu POST /v1/video/generations. Xem Sử dụng asset trong yêu cầu Seedance và Seedance.
5. Thăm dò tác vụ video như thông thường. Yêu cầu video dùng asset chỉ được gửi đến upstream một lần; chúng không được thử lại hay chuyển sang kênh khác.

Endpoint

Phương thức	Đường dẫn	Mục đích	Cấp phát không gian asset
POST	/v1/asset-groups	Tạo nhóm asset	Có
GET	/v1/asset-groups	Liệt kê nhóm	Không
GET	/v1/asset-groups/{groupID}	Lấy một nhóm	Không
DELETE	/v1/asset-groups/{groupID}	Xóa một nhóm	Không
PUT	/v1/asset-groups/{groupID}	Đổi tên một nhóm	Không
POST	/v1/assets	Thêm asset vào một nhóm	Có
GET	/v1/assets	Liệt kê asset trong một nhóm	Không
GET	/v1/assets/{assetID}	Lấy một asset (dùng để thăm dò)	Không
DELETE	/v1/assets/{assetID}	Xóa một asset	Không
PUT	/v1/assets/{assetID}	Đổi tên một asset	Không
POST	/v1/assets/verify-sessions	Tạo phiên xác minh người thật	Có
GET	/v1/assets/verify-sessions/{sessionID}	Lấy một phiên xác minh	Không

Xác thực

Gửi Model API Key trong header tiêu chuẩn:

Authorization: Bearer sk-your-routeapi-key

Key này định danh tài khoản RouteAPI. Asset được cô lập theo tài khoản: mọi API Key thuộc cùng một tài khoản đều thấy các nhóm, asset và phiên xác minh giống nhau, và không tài khoản nào khác thấy được chúng. Key không bao giờ được gửi đến upstream — RouteAPI dùng một thông tin xác thực upstream riêng thay cho bạn.

Lần dùng đầu tiên và khóa asset pool

Mỗi tài khoản được gắn với một thông tin xác thực upstream, mà dịch vụ asset dùng để tách biệt tư liệu của tài khoản đó. Nó được cấp tự động trong lần đầu tài khoản gọi một endpoint tạo:

• POST /v1/asset-groups
• POST /v1/assets
• POST /v1/assets/verify-sessions

Sau khi được cấp, liên kết này là vĩnh viễn với tài khoản và được dùng lại trong mọi lệnh gọi sau đó, bao gồm các yêu cầu video tham chiếu asset asset://.

Các endpoint đọc và xóa không bao giờ cấp phát. Trước khi liên kết tồn tại:

Lệnh gọi	Phản hồi
GET /v1/asset-groups	200, danh sách rỗng: {"total": 0, "asset_groups": []}
Mọi GET hoặc DELETE khác	404, {"error": "not found"}

Nghĩa là, danh sách nhóm rỗng là câu trả lời bình thường với một tài khoản mới, còn 404 trên một asset hoặc nhóm cụ thể trước lần dùng đầu tiên có nghĩa là “tài khoản này chưa có không gian asset”, chứ không phải “ID sai”.

Việc định tuyến nhóm đến thông tin xác thực là chi tiết cấu hình phía dịch vụ. Nếu nhóm của bạn chưa cấu hình kênh asset, lệnh gọi tạo đầu tiên sẽ thất bại với 503 asset_pool_exhausted hoặc 503 asset_pool_misconfigured thay vì cấp phát. Hãy thử lại sau, hoặc liên hệ bộ phận hỗ trợ nếu tình trạng kéo dài.

Khóa bị lỗi sẽ không được dùng

Nếu upstream từ chối thông tin xác thực của bạn với 401, RouteAPI đánh dấu liên kết là bị lỗi và trả về 503 asset_key_unavailable. Mọi lệnh gọi asset — và mọi yêu cầu video tham chiếu asset — sẽ liên tục trả về mã đó cho đến khi quản trị viên khôi phục liên kết, vì vậy hãy kiểm thử đường dẫn này trước khi dựa vào nó trên production.

Nhóm asset

Tạo nhóm asset

POST /v1/asset-groups

curl https://api.routeapi.ai/v1/asset-groups \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "product-refs",
    "description": "Reference material for product videos"
  }'

Trường	Kiểu	Bắt buộc	Mô tả
name	string	Có	Tên nhóm
description	string	Không	Mô tả nhóm

Phản hồi:

{
  "asset_group_id": "local_group_2c8186e6d8b44ffa73b371677bfe4af2",
  "name": "product-refs",
  "project_name": "default",
  "status": "active"
}

Hãy giữ asset_group_id: trường này bắt buộc khi thêm asset.

Liệt kê nhóm asset

GET /v1/asset-groups

curl "https://api.routeapi.ai/v1/asset-groups?page=1&page_size=20" \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

Các tham số phân trang như page và page_size được chuyển tiếp nguyên vẹn; giá trị mặc định và kích thước trang tối đa của dịch vụ upstream sẽ được áp dụng.

{
  "total": 1,
  "asset_groups": [
    {
      "asset_group_id": "local_group_2c8186e6d8b44ffa73b371677bfe4af2",
      "group_type": "AIGC",
      "project_name": "default",
      "session_id": "",
      "status": "active",
      "created_at": 1792050332,
      "updated_at": 1792050332
    }
  ]
}

session_id chỉ được đặt cho các nhóm tạo qua xác minh người thật. Nhóm của người đã xác minh có group_type là LivenessFace; các nhóm thông thường là AIGC.

Lấy một nhóm asset

curl https://api.routeapi.ai/v1/asset-groups/local_group_2c8186e6d8b44ffa73b371677bfe4af2 \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

Phản hồi chi tiết của upstream có thể trả về chuỗi status rỗng. Khi cần quyết định một nhóm có dùng được hay không, hãy dùng giá trị từ phản hồi danh sách hoặc phản hồi tạo.

Xóa một nhóm asset

curl -X DELETE https://api.routeapi.ai/v1/asset-groups/local_group_2c8186e6d8b44ffa73b371677bfe4af2 \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

{ "deleted": "local_group_2c8186e6d8b44ffa73b371677bfe4af2" }

Xóa là vĩnh viễn.

Đổi tên một nhóm asset

curl -X PUT https://api.routeapi.ai/v1/asset-groups/local_group_2c8186e6d8b44ffa73b371677bfe4af2 \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "new_group_name"}'

{ "name": "new_group_name", "updated": "local_group_2c8186e6d8b44ffa73b371677bfe4af2" }

Asset

Thêm một asset

POST /v1/assets

Mỗi yêu cầu một asset. Truyền nhóm, tên và đúng một URL nguồn.

Trường	Kiểu	Bắt buộc	Mô tả
asset_group_id	string	Có	Nhóm mà asset thuộc về
asset_name	string	Có	Tên chỉ dùng để tra cứu; không ảnh hưởng đến quá trình tạo
image_url	string	Một trong ba	URL công khai của một hình ảnh
video_url	string	Một trong ba	URL công khai của một video
audio_url	string	Một trong ba	URL công khai của một tệp âm thanh
asset_type	string	Không	Image, Video, hoặc Audio; được suy ra từ trường URL khi bỏ qua
description	string	Không	Mô tả asset

Truyền đúng một trong image_url, video_url và audio_url; dịch vụ upstream từ chối yêu cầu không có trường nào hoặc có nhiều trường. URL phải tải xuống được từ internet công khai mà không cần xác thực hay header bổ sung. Payload Base64 và địa chỉ nội bộ không được hỗ trợ, và URL phải luôn truy cập được cho đến khi xử lý xong.

curl https://api.routeapi.ai/v1/assets \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "asset_group_id": "local_group_2c8186e6d8b44ffa73b371677bfe4af2",
    "asset_name": "product-front",
    "image_url": "https://cdn.example.com/product-front.jpg"
  }'

{
  "asset_id": "local_asset_25e4d0cb018fb5802bf4e466f99707d0",
  "asset_group_id": "local_group_2c8186e6d8b44ffa73b371677bfe4af2",
  "asset_name": "product-front",
  "asset_type": "Image",
  "asset_uri": "asset://local_asset_25e4d0cb018fb5802bf4e466f99707d0",
  "status": "Processing"
}

Tạo thành công nghĩa là yêu cầu đã được chấp nhận, không phải asset đã dùng được. asset_uri là dạng cần dùng trong yêu cầu video.

Trạng thái asset

Trạng thái	Ý nghĩa	Việc cần làm
Processing	Vẫn đang được nạp	Tiếp tục thăm dò
Active	Sẵn sàng sử dụng	Tham chiếu nó trong một yêu cầu video
Failed	Nạp thất bại	Kiểm tra yêu cầu về định dạng và kích thước, sau đó thêm lại

Lấy một asset

Dùng endpoint này để thăm dò, mỗi 5–10 giây, kèm một thời hạn tổng. Quá trình xử lý thường mất vài giây đến vài chục giây; asset video và các giai đoạn cao điểm sẽ lâu hơn.

curl https://api.routeapi.ai/v1/assets/local_asset_25e4d0cb018fb5802bf4e466f99707d0 \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

{
  "asset_id": "local_asset_25e4d0cb018fb5802bf4e466f99707d0",
  "asset_group_id": "local_group_2c8186e6d8b44ffa73b371677bfe4af2",
  "status": "Active",
  "asset_uri": "asset://local_asset_25e4d0cb018fb5802bf4e466f99707d0",
  "url": "https://..."
}

url là địa chỉ tải xuống có chữ ký tạm thời. Đừng lưu nó; hãy dùng asset_uri cho việc tạo nội dung.

Asset không tồn tại hoặc đã bị xóa trả về 404 từ dịch vụ upstream, ví dụ:

{ "details": "record not found", "error": "asset not found in database" }

Liệt kê và xóa asset

# List — asset_group_id is required
curl "https://api.routeapi.ai/v1/assets?asset_group_id=local_group_2c8186e6d8b44ffa73b371677bfe4af2" \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

# Delete
curl -X DELETE https://api.routeapi.ai/v1/assets/local_asset_25e4d0cb018fb5802bf4e466f99707d0 \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

{ "deleted": "local_asset_25e4d0cb018fb5802bf4e466f99707d0" }

Xóa một asset sẽ làm hỏng mọi yêu cầu video mới tham chiếu đến nó.

Đổi tên một asset

curl -X PUT https://api.routeapi.ai/v1/assets/local_asset_25e4d0cb018fb5802bf4e466f99707d0 \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "new_asset_name"}'

{ "updated": "local_asset_25e4d0cb018fb5802bf4e466f99707d0" }

Sau khi đổi tên, phản hồi chi tiết và danh sách asset trả về tên mới.

Phiên xác minh người thật

Tư liệu tham chiếu chứa khuôn mặt của một người thật trước hết cần có sự đồng ý của chính người đó. Một phiên xác minh tạo ra một nhóm riêng cho tư liệu của người đó; các asset được thêm vào nhóm này sẽ được kiểm tra tính nhất quán khuôn mặt.

Tạo một phiên

POST /v1/assets/verify-sessions

Body có thể rỗng ({} hoặc không có body). callback_url được chấp nhận nhưng không dùng để chuyển hướng.

curl https://api.routeapi.ai/v1/assets/verify-sessions \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "session_id": "asset_sess_5e7860e76613dd51a4867bdcbea6076b",
  "status": "pending",
  "h5_link": "https://...one-time-link...",
  "callback_url": ""
}

Chỉ gửi h5_link cho người sẽ được xác minh. Nó chứa thông tin xác thực dùng một lần và cấp quyền truy cập trang xác minh; đừng đưa nó vào nhật ký công khai, ảnh chụp màn hình hay nhóm chat.

Lấy một phiên

curl https://api.routeapi.ai/v1/assets/verify-sessions/asset_sess_5e7860e76613dd51a4867bdcbea6076b \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

status	Ý nghĩa
pending	Đang chờ người dùng, hoặc vẫn đang được xử lý
succeeded	Đã xác minh; asset_group_id đã được điền
failed	Xác minh thất bại; hãy đọc trường error

{
  "session_id": "asset_sess_a8af6fab34f694ada40c22521448f579",
  "status": "succeeded",
  "result_code": "",
  "error": "",
  "asset_group_id": "group-20261015202316-4t5jt",
  "project_name": "default",
  "created_at": 1792066965,
  "updated_at": 1792067203
}

Không có webhook hay chuyển hướng nào về dịch vụ của bạn — trình duyệt của người dùng kết thúc ở một trang kết quả do upstream sở hữu. Hãy thăm dò phiên cho đến khi status trở thành succeeded (thường trong vài phút), sau đó thêm tư liệu của người đó vào asset_group_id được trả về. Hiện tại result_code luôn rỗng; hãy dùng status. Một phiên failed với error như verification expired phải được tạo lại.

Sử dụng asset trong yêu cầu Seedance

Tham chiếu asset bên trong metadata.content của yêu cầu tạo video, bằng asset_uri do API asset trả về:

curl https://api.routeapi.ai/v1/video/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-fast-260128",
    "prompt": "The product in image 1 rotates slowly",
    "metadata": {
      "content": [
        { "type": "text", "text": "The product in image 1 rotates slowly" },
        {
          "type": "image_url",
          "image_url": { "url": "asset://local_asset_25e4d0cb018fb5802bf4e466f99707d0" },
          "role": "reference_image"
        }
      ],
      "duration": 4,
      "resolution": "480p",
      "ratio": "1:1"
    }
  }'

Hãy dùng một ID mô hình Seedance từ GET /v1/models có hỗ trợ tạo video; xem Models. Định dạng yêu cầu cho Seedance, bao gồm các role trong metadata.content và giới hạn riêng của từng mô hình, được mô tả trong Seedance.

Các quy tắc xuất phát từ hợp đồng của dịch vụ asset:

• Cặp type/role phải khớp với loại asset: image_url đi với reference_image, video_url đi với reference_video, audio_url đi với reference_audio.
• Chỉ có thể tham chiếu asset ở trạng thái Active.
• Văn bản prompt tham chiếu tư liệu bằng số thứ tự (“image 1”, “video 1”), được đếm trong từng loại theo thứ tự trong content. Đừng đưa ID asset vào prompt.
• Tư liệu của người thật phải đến từ một nhóm đã xác minh; nếu không upstream có thể từ chối hoặc làm tác vụ thất bại.

RouteAPI phát hiện tham chiếu bằng cách tìm mọi giá trị chuỗi JSON bắt đầu bằng asset:// (không phân biệt chữ hoa chữ thường). Yêu cầu như vậy được ghim vào kênh asset của bạn và chỉ gửi một lần, không thử lại và không chuyển sang kênh khác. Yêu cầu bị từ chối cục bộ trong các trường hợp sau:

Mã trạng thái	Mã	Nguyên nhân
400	asset_key_required	Body tham chiếu asset://, nhưng tài khoản chưa có không gian asset. Hãy tạo nhóm và asset trước
400	asset_remix_conflict	Một bản remix của tác vụ không dùng asset cố tham chiếu asset asset://
400	asset_channel_conflict	API Key bị ghim vào một kênh cụ thể không phải kênh asset của bạn
400	asset_model_unsupported	Kênh asset của bạn không hỗ trợ mô hình này
503	asset_key_unavailable	Thông tin xác thực upstream gắn với tài khoản bị lỗi hoặc bị tắt

Các lỗi này dùng dạng lỗi của tác vụ {"code": ..., "message": ..., "data": ...}.

Giới hạn và lỗi

• Body yêu cầu — Body POST và PUT được đọc với giới hạn 1 MiB. Body lớn hơn trả về 413 trước khi gửi bất cứ thứ gì đến upstream. Bản thân tư liệu không bao giờ được tải lên qua body; hãy truyền một URL.
• Hình dạng body — một body POST hoặc PUT không rỗng phải là đối tượng JSON. Mảng, chuỗi trần, null và JSON không hợp lệ trả về 400 mà không chạm tới dịch vụ upstream. Body của GET và DELETE bị bỏ qua.
• Body đổi tên — body PUT phải có trường chuỗi không rỗng name (khóa viết thường). Thiếu name, name rỗng hoặc không phải chuỗi sẽ trả về 400 mà không chạm tới dịch vụ upstream.
• Body phản hồi — phản hồi upstream vượt quá 10 MiB, hoặc phản hồi không đọc được, trả về 502.
• Thời gian chờ — lệnh gọi upstream có thời gian chờ cố định 60 giây; hết hạn được báo là 502.
• project_name — nếu có trong body POST hoặc PUT, trường này bị loại bỏ trước khi chuyển tiếp, bất kể chữ hoa chữ thường.
• Lỗi quyền sở hữu — nếu upstream trả 403 với lý do từ chối quyền sở hữu (“you do not own” / “access denied”), RouteAPI trả về 404 {"error": "not found"} thay vào đó, để tài nguyên trông như không tồn tại thay vì bị cấm.
• Lỗi thông tin xác thực upstream — 401 từ upstream trở thành 503 asset_key_unavailable và đánh dấu liên kết của tài khoản là bị lỗi (xem ở trên). 402 từ upstream, hoặc một lỗi upstream có body giống vấn đề thanh toán, trở thành 503 asset_service_unavailable.

Các mã trạng thái và body khác của upstream được truyền nguyên vẹn, kể cả lỗi xác thực tham số của upstream. Lỗi của chính RouteAPI dùng một trong ba dạng:

{ "error": "not found" }

{ "error": "<message>", "code": "asset_pool_busy" }

{
  "error": {
    "message": "token.invalid (request id: ...)",
    "type": "error",
    "code": ""
  }
}

Dạng thứ ba đến từ middleware xác thực và giới hạn tần suất dùng chung, nên hãy kiểm tra error là chuỗi hay đối tượng. Văn bản message cục bộ hiện đang là tiếng Trung — với hai dạng đầu, hãy rẽ nhánh theo mã trạng thái HTTP và trường code thay vì theo message.

Mã trạng thái	Mã	Ý nghĩa	Cách xử lý
400	—	Body không phải đối tượng JSON, hoặc upstream từ chối tham số	Sửa yêu cầu; đừng thử lại nguyên trạng
401	—	Thiếu API Key, Key không hợp lệ hoặc đã bị xóa	Kiểm tra Authorization
404	—	Asset, nhóm hoặc phiên không tồn tại; hoặc tài khoản này chưa có không gian asset	Kiểm tra ID; tạo nhóm trước nếu tài khoản còn mới
413	—	Body yêu cầu vượt quá 1 MiB	Gửi URL thay vì dữ liệu nội tuyến
429	—	Đã kích hoạt giới hạn tần suất	Giảm tốc độ thăm dò và thử lại sau
500	asset_pool_internal_error	RouteAPI không đọc hoặc ghi được trạng thái asset của chính nó	Thử lại sau
500	—	RouteAPI gặp lỗi khi đọc trạng thái asset của tài khoản	Thử lại sau
502	—	Không kết nối được upstream, quá thời gian chờ, hoặc upstream trả về phản hồi không đọc được hay quá lớn	Thử lại sau
503	asset_key_unavailable	Thông tin xác thực upstream của tài khoản bị lỗi hoặc bị tắt	Liên hệ bộ phận hỗ trợ; thử lại không giúp ích
503	asset_pool_exhausted	Nhóm của bạn không có kênh asset, hoặc không có thông tin xác thực nào để cấp phát	Thử lại sau hoặc liên hệ bộ phận hỗ trợ
503	asset_pool_busy	Có thông tin xác thực nhưng hiện không thể cấp phát cái nào	Thử lại sau
503	asset_pool_misconfigured	Nhóm của bạn ánh xạ tới nhiều hơn một kênh asset	Liên hệ bộ phận hỗ trợ
503	asset_channel_unavailable	Bản thân kênh asset bị tắt hoặc cấu hình sai	Thử lại sau hoặc liên hệ bộ phận hỗ trợ
503	asset_service_unavailable	Số dư tài khoản upstream hoặc lỗi cứng	Thử lại sau hoặc liên hệ bộ phận hỗ trợ

Các lệnh gọi asset không tốn chi phí mô hình, nhưng khi giới hạn tần suất yêu cầu mô hình của nền tảng được bật, chúng vẫn được tính vào giới hạn đó như mọi yêu cầu /v1 khác. Xem Lỗi và gỡ lỗi để biết mô hình lỗi tổng quát, và Giá mô hình để biết cách tính phí phần tạo video sử dụng các asset này.

Tiếp theo

• Tạo tác vụ video — khung yêu cầu dùng chung cho mọi mô hình video.
• Seedance — định dạng yêu cầu Seedance và các role trong metadata.content.
• Models — tìm một ID mô hình video được hỗ trợ.
• Lỗi và gỡ lỗi — mã trạng thái và thứ tự xử lý sự cố.