Tạo tác vụ video

Tạo video là tác vụ bất đồng bộ: tạo thành công chỉ nghĩa là tác vụ đã được tiếp nhận, cần lưu id trong phản hồi rồi truy vấn tác vụ để đọc tiến độ và kết quả. Một yêu cầu tạo tương ứng một tác vụ, việc truy vấn và làm mới trang sẽ không tạo trùng hoặc tính phí trùng.

Quy ước chung (địa chỉ cơ sở, xác thực, cấu trúc phản hồi, giới hạn tần suất, tính idempotent) xem Xác thực và quy chuẩn cơ bản.

Tổng quan API

Hai cách viết có phần thân yêu cầu, phần thân phản hồi và ID tác vụ hoàn toàn giống nhau, chọn một trong hai là được; cùng một ID tác vụ đều có thể truy vấn dưới hai nhóm đường dẫn.

Client cũ tiếp tục dùng /v1/video/generations là được, nền tảng sẽ xử lý nó ở lớp cổng vào như plugin tác vụ video của /v1/videos, không cần đổi trường hay đường dẫn.

Chuẩn bị biến

export LOCOPAL_API_KEY="sk-你的APIKey"
export LOCOPAL_API_ORIGIN="https://locopalai.com"
export LOCOPAL_VIDEO_MODEL_ID="从 /v1/models 返回的视频模型 ID"
export LOCOPAL_IMAGE_URL="https://你的对象存储域名/reference.png"
export LOCOPAL_VIDEO_URL="https://你的对象存储域名/reference.mp4"
export LOCOPAL_AUDIO_URL="https://你的对象存储域名/reference.mp3"
export LOCOPAL_TASK_ID="创建视频后响应中的 id"

Tạo tác vụ video

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

Authorization: Bearer <API_KEY>, dùng khóa API nền tảng được tạo tại trang "Khóa API" trong bảng điều khiển.

Phần thân yêu cầu · application/json

prompt và content phải cung cấp ít nhất một loại đầu vào văn bản: khi chỉ gửi content, nền tảng sẽ lấy text của phần tử type: "text" đầu tiên làm câu lệnh gợi ý. Khi thiếu model trả về HTTP 400, đừng truyền cho mô hình những tham số mà trang chi tiết không tuyên bố hỗ trợ.

Phần tử content

Tư liệu công khai phải dùng URL HTTPS có thể tải trực tiếp, không được phụ thuộc Cookie, Referer hoặc trang đăng nhập; hình ảnh cũng có thể dùng data:image/...;base64,... tùy theo mô hình hỗ trợ. Tư liệu có trạng thái Active trong thư viện tư liệu dùng asset://<asset_id>; tư liệu người thật chỉ có thể gửi tới mô hình hỗ trợ thư viện tư liệu người thật.

image_url, video_url, audio_url trong mảng content sẽ được truyền cho thượng nguồn theo nguyên kiểu; các tham số cấp cao nhất như duration, ratio, resolution, seed, watermark, generate_audio cũng sẽ được gửi kèm tác vụ, không cần bọc thêm vào metadata.

Nếu chỉ cần một ảnh tham chiếu thường, cũng có thể dùng cách viết tắt image_url cấp cao nhất:

{
  "model": "$LOCOPAL_VIDEO_MODEL_ID",
  "prompt": "镜头缓慢推进",
  "image_url": "https://your-object-storage.example/reference.png",
  "duration": 5,
  "ratio": "9:16",
  "resolution": "480p",
  "seed": 20260409,
  "watermark": false
}

Nền tảng sẽ chuyển image_url cấp cao nhất thành một mục nội dung ảnh tham chiếu duy nhất. Khi cần nhiều ảnh, khung đầu cuối, video tham chiếu hoặc âm thanh tham chiếu, vui lòng dùng mảng content.

Ví dụ yêu cầu

Tạo video từ văn bản

curl -X POST "$LOCOPAL_API_ORIGIN/v1/video/generations" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<JSON
{
  "model": "$LOCOPAL_VIDEO_MODEL_ID",
  "content": [
    { "type": "text", "text": "雨后的城市街道，镜头从水面倒影缓慢抬升，电影感" }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "generate_audio": true,
  "watermark": false
}
JSON

Tạo video từ một ảnh

{
  "model": "从 /v1/models 选择的视频模型 ID",
  "content": [
    { "type": "text", "text": "人物自然转身，衣摆随风摆动，镜头轻微环绕" },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": { "url": "https://你的对象存储域名/reference.png" }
    }
  ],
  "resolution": "720p",
  "ratio": "9:16",
  "duration": 5
}

Khung đầu và khung cuối

Khung đầu và khung cuối phải lần lượt đánh dấu first_frame và last_frame, và dùng hai ảnh khác nhau.

{
  "model": "从 /v1/models 选择的视频模型 ID",
  "content": [
    { "type": "text", "text": "镜头从室内平滑移动到窗外城市夜景" },
    {
      "type": "image_url",
      "role": "first_frame",
      "image_url": { "url": "https://你的对象存储域名/first.png" }
    },
    {
      "type": "image_url",
      "role": "last_frame",
      "image_url": { "url": "https://你的对象存储域名/last.png" }
    }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5
}

Nhiều ảnh và video tham chiếu

Cái thường được gọi là "video sâu" trong nghiệp vụ không có trường deep_video riêng trong API công khai, nó được gửi như video tham chiếu: type dùng video_url, role dùng reference_video. Mỗi ảnh tham chiếu chiếm một phần tử content, không thể đặt nhiều URL vào một image_url.url.

curl -X POST "$LOCOPAL_API_ORIGIN/v1/video/generations" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<JSON
{
  "model": "$LOCOPAL_VIDEO_MODEL_ID",
  "content": [
    {
      "type": "text",
      "text": "以图片1的人物为主体，沿用图片2的服装，参考视频的动作节奏和运镜，保持人物身份与产品外观一致。"
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": { "url": "$LOCOPAL_IMAGE_URL" }
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": { "url": "asset://你的素材ID" }
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": { "url": "https://你的对象存储域名/scene.png" }
    },
    {
      "type": "video_url",
      "role": "reference_video",
      "video_url": { "url": "$LOCOPAL_VIDEO_URL" }
    }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 7,
  "generate_audio": false,
  "watermark": false
}
JSON

Thứ tự mảng chính là thứ tự tư liệu. Khuyến nghị ghi rõ trong câu lệnh gợi ý "ảnh1, ảnh2, ảnh3, video tham chiếu", đừng để máy chủ đoán thứ tự theo tên tệp. Số lượng ảnh tham chiếu, video tham chiếu, âm thanh tham chiếu, độ phân giải và thời lượng đầu ra do năng lực mô hình quyết định, chi tiết xem Hướng dẫn nhiều ảnh và video tham chiếu.

Nhiều ảnh, âm thanh tham chiếu và hạt giống cố định

seed có thể cố định kết quả lấy mẫu; reference_audio làm tham chiếu âm thanh hoặc nhịp điệu; duration, generate_audio, ratio, resolution, watermark đều là tham số cấp cao nhất. Ví dụ dưới đây tương ứng bộ tham số video 9:16 khách hàng thường dùng:

{
  "model": "doubao-seedance-2.0-D",
  "content": [
    {
      "type": "text",
      "text": "以图片1的人物和服装为主体，参考图片2的另一名角色，参考音频的情绪和节奏生成电影感画面，保持角色身份一致。"
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": { "url": "asset://asset-20260917114312-cyele" }
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": { "url": "asset://asset-20260917111324-mquys" }
    },
    {
      "type": "audio_url",
      "role": "reference_audio",
      "audio_url": { "url": "https://your-object-storage.example/reference.mp3" }
    }
  ],
  "duration": 9,
  "generate_audio": true,
  "ratio": "9:16",
  "resolution": "480p",
  "seed": 20260409,
  "watermark": false
}

Sau khi tạo thành công, id / task_id trong phản hồi vẫn được truy vấn theo quy trình tác vụ bất đồng bộ; âm thanh tham chiếu phải là địa chỉ HTTPS mà nền tảng có thể truy cập, tư liệu asset:// trước tiên phải ở trạng thái Active.

Tham số phản hồi

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

{
  "created_at": 1789567067,
  "id": "task_QH33zpW2IRHEnrmBbZFvtPzodyXvevWu",
  "model": "seedance-2.0-mini",
  "status": "queued",
  "task_id": "task_QH33zpW2IRHEnrmBbZFvtPzodyXvevWu"
}

Phản hồi tạo không phải là tập trường cố định đầy đủ. Client nên dựa vào việc id / task_id có khác rỗng hay không, đừng coi việc có object hoặc progress là điều kiện bắt buộc để tiếp nhận thành công.

Sau khi nhận HTTP 200 và ID tác vụ, kể cả khi chờ đợi cục bộ quá thời gian, cũng chỉ truy vấn tác vụ gốc, đừng tự động tạo lại.

Phản hồi lỗi

Khi kiểm tra tham số không qua, trả về HTTP 400, code là invalid_request, message nói trực tiếp nội dung thiếu hoặc viết sai:

{
  "code": "invalid_request",
  "message": "缺少提示词：请在 prompt 或 content 的 text 元素中提供文本描述",
  "data": null
}

Khi số dư hoặc hạn mức khóa API hiện tại không đủ chi trả chi phí ước tính lần này, trả về HTTP 403, sẽ không tạo tác vụ, không phát sinh chi phí:

{
  "code": "insufficient_user_quota",
  "message": "余额不足：本次预计需要 ＄11.500000，当前可用 ＄0.002000，请充值或调整参数后重试",
  "data": null
}

Đồng thời và nhịp độ gửi

Tác vụ tạo sinh được thực thi đồng thời ở chế độ nền, việc gửi và tải kết quả đều chiếm băng thông lối ra của nền tảng, vì vậy nền tảng đặt giới hạn trên cho số tác vụ đang xử lý đồng thời: mỗi tài khoản tối đa 2000 tác vụ cùng lúc. Gửi thêm khi đã đạt giới hạn sẽ trả về:

{
  "code": "task_concurrency_exceeded",
  "message": "当前账号有 2000 个生成任务正在处理中，已达到并发上限 2000，请等待任务完成后再提交",
  "data": null
}

Khuyến nghị tổ chức tác vụ hàng loạt như sau:

• Trước tiên gửi một lô, chờ tác vụ vào trạng thái cuối completed / failed rồi mới gửi lô tiếp theo, đừng dùng vòng lặp thử lại liên tục cùng một yêu cầu;
• Một lần gửi càng nhiều ảnh tham chiếu, độ phân giải càng cao thì chiếm băng thông lối ra càng lâu, số tác vụ gửi đồng thời phải giảm tương ứng;
• Khi cần đồng thời tạo nhiều video, ghi tiến độ theo ID tác vụ, chờ lô trước hoàn tất rồi tiếp tục, tránh gửi trùng gây tính phí trùng.

Tính phí và kiểm tra tham số

• Tác vụ video được quyết toán theo lượng dùng thực tế khi hoàn thành: tạo thành công chỉ nghĩa là tác vụ đã được tiếp nhận, giai đoạn gửi sẽ không trừ phí trước, cũng không phát sinh bất kỳ bản ghi hóa đơn nào; sau khi tác vụ hoàn thành trong hóa đơn chỉ xuất hiện một bản ghi trừ phí thực tế.
• Khi gửi sẽ kiểm tra số dư tài khoản (hoặc hạn mức khóa API hiện tại) có chi trả hạn mức ước tính lần này hay không. Khi không đủ trả về HTTP 403 và insufficient_user_quota, thông tin lỗi sẽ đưa ra "mức dự kiến cần lần này …, hiện có khả dụng …", bổ sung số dư hoặc điều chỉnh tham số rồi gửi lại là được; lúc này sẽ không tạo tác vụ, cũng không phát sinh chi phí.
• Trước khi gửi sẽ kiểm tra phần thân yêu cầu, khi thiếu nội dung trả về trực tiếp thông báo dễ đọc, không cần dựa vào lỗi thượng nguồn để định vị: