Truy vấn tác vụ video

Sau khi tạo tác vụ, dùng id trong phản hồi tạo để truy vấn tiến độ và kết quả; cách tạo xem Tạo tác vụ video.

Truy vấn trạng thái: GET /v1/video/generations/{task_id}

Tải thành phẩm: GET /v1/videos/{task_id}/content

API truy vấn sẽ trả về địa chỉ video trong metadata.url sau khi tác vụ hoàn thành. Nền tảng ưu tiên trả về địa chỉ video gốc của thượng nguồn; chỉ khi thượng nguồn không có địa chỉ khả dụng mới lùi về địa chỉ sản phẩm nền tảng có khả năng access. Địa chỉ gốc thượng nguồn có thể kèm chữ ký và thời hạn, có thể mở trực tiếp trong trình duyệt hoặc trình phát; địa chỉ sản phẩm nền tảng cũng dùng được. Cũng có thể mang khóa API gọi /v1/videos/{task_id}/content để tải tệp video.

Phương thức xác thực

Authorization: Bearer <API_KEY>.

Tham số yêu cầu · path

Ví dụ yêu cầu

curl "$LOCOPAL_API_ORIGIN/v1/video/generations/$LOCOPAL_TASK_ID" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

Tải video

Sau khi trạng thái tác vụ chuyển thành completed, dùng trực tiếp metadata.url trong phản hồi truy vấn:

curl -L "$LOCOPAL_API_ORIGIN/v1/videos/$LOCOPAL_TASK_ID/content" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -o "$LOCOPAL_TASK_ID.mp4"

Tham số phản hồi

Phần thân phản hồi

Đang thực thi:

{
  "id": "task_XVCPphL5ZWOr2iMpGhNkV32qRTj7MSUO",
  "task_id": "task_XVCPphL5ZWOr2iMpGhNkV32qRTj7MSUO",
  "object": "video",
  "model": "doubao-seedance-2.0-A",
  "status": "in_progress",
  "progress": 50,
  "created_at": 1787299277
}

Tạo thành công:

{
  "id": "task_XVCPphL5ZWOr2iMpGhNkV32qRTj7MSUO",
  "task_id": "task_XVCPphL5ZWOr2iMpGhNkV32qRTj7MSUO",
  "object": "video",
  "model": "doubao-seedance-2.0-A",
  "status": "completed",
  "progress": 100,
  "created_at": 1787299277,
  "completed_at": 1787299581,
  "duration_secs": 5,
  "expires_at": 1790578352,
  "framespersecond": 24,
  "generate_audio": true,
  "ratio": "9:16",
  "resolution": "480p",
  "seed": 20260409,
  "output_format": "mp4",
  "execution_expires_after": 172800,
  "metadata": {
    "url": "https://upstream.example.com/task_XVCPphL5ZWOr2iMpGhNkV32qRTj7MSUO.mp4?signature=...",
    "upstream_created": true
  },
  "usage": {
    "prompt_tokens": 141034,
    "completion_tokens": 0,
    "total_tokens": 141034,
    "quota": 2789652,
    "amount": 5.579304,
    "currency": "CNY"
  }
}

usage chỉ trả về sau khi tác vụ hoàn thành quyết toán, giá trị hoàn toàn trùng khớp với khoản trừ phí của tác vụ này trong hóa đơn: usage.quota là điểm tiêu hao lần này, usage.amount là số tiền nhân dân tệ quy đổi từ cùng số điểm theo tỷ giá hiện tại của trang, usage.total_tokens là số token video tính phí lần này. Khi tác vụ còn đang xếp hàng hoặc đang tạo sẽ không trả về usage, lúc này đừng dựa vào phản hồi truy vấn để phán đoán chi phí; khi cần đối chiếu trừ phí, dùng cùng id đối chiếu usage.quota và usage.amount trong hóa đơn của bảng điều khiển.

metadata.url có thể là địa chỉ thượng nguồn có chữ ký, cũng có thể được API sản phẩm nền tảng dự phòng. Vui lòng xử lý như thông tin xác thực, đừng chia sẻ công khai. Sau khi thành phẩm được tạo, khuyến nghị tải về hoặc chuyển lưu vào lưu trữ đối tượng của riêng bạn trước expires_at.

Sản phẩm video và xem trước

Ngoài việc đọc trực tiếp metadata.url, cũng có thể truy vấn danh sách sản phẩm nền tảng:

curl "$LOCOPAL_API_ORIGIN/v1/tasks/$LOCOPAL_TASK_ID/artifacts" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

Trả về sau khi tác vụ hoàn thành:

{
  "task_id": "task_XVCPphL5ZWOr2iMpGhNkV32qRTj7MSUO",
  "artifacts": [
    {
      "key": "video",
      "type": "video",
      "content_url": "https://locopalai.com/v1/tasks/task_XVCPphL5ZWOr2iMpGhNkV32qRTj7MSUO/artifacts/video/content?access=..."
    }
  ]
}

Địa chỉ nội dung sản phẩm hỗ trợ yêu cầu Range; trình phát, xem trước trên trình duyệt và tải tiếp đều có thể dùng trực tiếp. Nếu client chỉ đọc metadata.url, hãy tiếp tục dùng logic cũ, không cần đổi sang API sản phẩm.

Tạo thất bại:

{
  "id": "task_NlersigX6rIqiOjCwTFlgNmGMTwqt39K",
  "object": "video",
  "model": "doubao-seedance-2.0-D",
  "status": "failed",
  "progress": 100,
  "created_at": 1789971935,
  "error": {
    "code": "video_generation_failed",
    "message": "音频素材缓冲失败: 音频地址必须是 http(s)"
  },
  "metadata": {
    "submission_stage": "submitting",
    "upstream_created": false
  }
}

error.message là văn bản thất bại cuối cùng đã được nền tảng xử lý. Tác vụ lịch sử kể cả ban đầu lưu JSON lồng nhau, khi truy vấn cũng sẽ trả về văn bản đã chuẩn hóa; bên gọi chỉ cần hiển thị trực tiếp trường này cho người dùng, đừng ghép hoặc phân tích JSON thượng nguồn gốc ở client.

Phản hồi lỗi

Truy vấn ID tác vụ không tồn tại (hoặc tác vụ không thuộc tài khoản hiện tại) trả về HTTP 400:

{ "code": "task_not_exist", "message": "task_not_exist", "data": null }

Xử lý trạng thái

Client đừng dùng số giây chờ cố định để phán đoán hoàn thành, cũng đừng vì một lần mạng quá thời gian mà tạo lại tác vụ; khuyến nghị truy vấn mỗi 5～15 giây.

Đọc tư liệu tham chiếu thất bại

Khi lỗi trỏ tới content[n].image_url, video_url hoặc chứa resource download failed, trước tiên định vị phần tử cụ thể theo chỉ số mảng, rồi kiểm tra:

1. URL có thể GET trực tiếp từ công cộng và trả về 200 hay không;
2. Có chuyển hướng tới trang đăng nhập hoặc phụ thuộc Cookie, Referer, danh sách IP cho phép hay không;
3. Content-Type có trùng với định dạng thật của tệp không;
4. URL ký tạm thời có còn hiệu lực trong suốt thời gian tải và xử lý không;
5. Tư liệu asset:// có thuộc tài khoản hiện tại và trạng thái là Active không;
6. Mô hình hiện tại có hỗ trợ loại và số lượng tư liệu đó không.

Sau khi sửa tư liệu hãy tạo lại tác vụ. Thông tin lỗi chỉ cần hiển thị cho người dùng một lần nguyên nhân dễ đọc, đừng ghép lặp lại nhiều lớp JSON đã thoát ký tự.

Đồng thời, thử lại và tính phí

• Các tác vụ video khác nhau có thể tạo đồng thời;
• Cùng một phản hồi tạo phải dùng cùng một ID tác vụ để truy vấn;
• Chỉ khi tác vụ thất bại rõ ràng và người dùng chủ động thử lại mới phát yêu cầu tạo mới;
• Tính phí được chia chi tiết theo mô hình, độ phân giải, thời lượng và đầu vào video tham chiếu, lấy theo chợ mô hình và hóa đơn cuối cùng làm chuẩn; kiểm tra tham số thất bại (400) nghĩa là yêu cầu chưa được tiếp nhận, thường không phát sinh phí tác vụ tạo sinh.

Tài liệu liên quan