Hướng dẫn nhiều ảnh và video tham chiếu

Trang này trả lời các câu hỏi tích hợp chương trình cho「nhiều ảnh tham chiếu + một video tham chiếu」, bao gồm giới hạn năng lực, quy tắc thứ tự, video độ sâu, âm thanh, khôi phục tác vụ và tính phí. Bảng trường đầy đủ của phần thân yêu cầu và ví dụ có thể sao chép xem API tạo video, việc nhập tư liệu vào thư viện xem Tổng quan API thư viện tư liệu.

Kết luận trước

• Nhiều hình ảnh và một video tham chiếu dùng cùng một mảng content: mỗi hình ảnh chiếm một phần tử image_url, video chiếm một phần tử video_url.
• 「Video độ sâu」không có trường deep_video riêng, hãy gửi như video tham chiếu thông thường với role là reference_video.
• Thứ tự mảng chính là thứ tự tư liệu. Khuyến nghị ghi rõ trong câu lệnh gợi ý「ảnh 1, ảnh 2, ảnh 3, video tham chiếu」, không nên phụ thuộc vào việc máy chủ đoán thứ tự theo tên tệp.
• generate_audio: false nghĩa là tắt đầu ra âm thanh của kết quả tạo sinh, nó không đồng nghĩa với việc giữ lại rãnh âm thanh gốc của video tham chiếu đầu vào, cũng không đồng nghĩa với việc sao chép âm thanh đầu vào vào thành phẩm.
• Số lượng ảnh chính xác, số lượng video, kích thước tệp, mã hóa và giới hạn đồng thời căn cứ vào danh mục mô hình và phản hồi API thực tế; nền tảng không cam kết một bộ giới hạn thống nhất cho tất cả biến thể Seedance.
• Nếu bắt buộc phải giữ động tác, vị trí máy quay và chuyển cảnh của video gốc, video tham chiếu chỉ có thể dùng làm tham chiếu cho mô hình. Yêu cầu công khai hiện tại không có tham số chung để「buộc chuyển cảnh ở giây thứ N」, không thể chỉ dựa vào trường API để đảm bảo thời điểm chính xác.

Một, xác nhận năng lực mô hình hiện tại

Trước tiên đọc danh mục mô hình mà Key hiện tại có thể thấy:

curl "https://locopalai.com/v1/models" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

Danh mục chỉ xác nhận「mô hình có hiển thị không, dùng được cho những API nào」, data[].id mới là model cần điền khi yêu cầu. Các giới hạn cụ thể như số lượng ảnh tham chiếu, video tham chiếu, âm thanh tham chiếu, tỷ lệ đầu ra, thời lượng và độ phân giải căn cứ vào trang chi tiết mô hình và lỗi tham số do API trả về; với các giới hạn không được liệt kê trong danh mục, nền tảng sẽ không đoán thay mô hình.

Hai, nhập thư viện và tham chiếu tư liệu tham chiếu

Ảnh thiết lập nhân vật hư cấu, ảnh nhiều góc nhìn nhân vật và ảnh bối cảnh không có người đều không phải tư liệu ủy quyền người thật, hãy nhập thư viện như tư liệu ảo thông thường:

POST /api/v1/materials/groups
POST /api/v1/materials/assets
GET  /api/v1/materials/assets/{asset_id}

Sau khi trạng thái tư liệu chuyển thành Active, URL ảnh trong yêu cầu video có thể đổi thành:

asset://asset-20260911035115-etexu

Khi nhập từng ảnh vào thư viện, mỗi ảnh sẽ nhận một asset_id riêng. Ảnh nhân vật và ảnh bối cảnh có thể đặt trong cùng một nhóm ảo, cũng có thể tạo nhóm riêng; khi gửi video thì tham chiếu qua các phần tử content khác nhau. Việc nhập thư viện, truy vấn lặp và phản hồi lỗi xem API thư viện tư liệu.

Khi gửi thành công, status thường là Processing, sau khi xử lý xong chuyển thành Active; khi thất bại status là Failed và error_message cho biết nguyên nhân. Kiểm duyệt là xử lý bất đồng bộ, nền tảng không cam kết thời lượng thống nhất cho tất cả hình ảnh; chương trình nên truy vấn cùng một asset_id, không gửi lặp lại khi đang Processing.

Ba, nhiều ảnh + một video tham chiếu

Yêu cầu dưới đây biểu đạt「1 ảnh nhân vật + 2 ảnh bối cảnh + 1 video tham chiếu」. Chỉ số mảng được giải thích bắt đầu từ 1:

1. content[1] là ảnh 1, ảnh nhân vật;
2. content[2] là ảnh 2, ảnh bối cảnh 1;
3. content[3] là ảnh 3, ảnh bối cảnh 2;
4. content[4] là video tham chiếu.

content[0] là câu lệnh gợi ý văn bản, không tính vào số thứ tự ảnh.

{
  "model": "从 /v1/models 选择的视频模型 ID",
  "content": [
    {
      "type": "text",
      "text": "图片1是人物身份参考，图片2和图片3是场景参考。参考视频用于动作、机位和镜头节奏参考；保持人物身份和场景关系一致。"
    },
    { "type": "image_url", "role": "reference_image", "image_url": { "url": "asset://人物素材ID" } },
    { "type": "image_url", "role": "reference_image", "image_url": { "url": "asset://场景素材ID1" } },
    { "type": "image_url", "role": "reference_image", "image_url": { "url": "asset://场景素材ID2" } },
    { "type": "video_url", "role": "reference_video", "video_url": { "url": "https://你的对象存储域名/reference-depth.mp4" } }
  ],
  "duration": 7,
  "resolution": "720p",
  "ratio": "9:16",
  "generate_audio": false,
  "watermark": false
}

Sau khi tạo thành công sẽ trả về ID tác vụ, sau đó chỉ truy vấn tác vụ này:

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

Nếu phản hồi thông báo rõ ràng mô hình hiện tại không hỗ trợ thư viện tư liệu, nên đổi sang địa chỉ ảnh HTTPS công khai mà mô hình đó hỗ trợ hoặc đổi mô hình, không được vượt qua kiểm duyệt tư liệu. Ví dụ phản hồi tạo và truy vấn đầy đủ xem API tạo video.

Bốn, ranh giới của video tham chiếu, âm thanh và video độ sâu

Video tham chiếu không phải rãnh điều khiển chính xác

Video độ sâu dạng thử nghiệm trong cấu trúc API công khai vẫn là reference_video thông thường. Trừ khi chi tiết mô hình hiện tại tuyên bố riêng khả năng điều khiển độ sâu, nền tảng sẽ không diễn giải giá trị độ sâu thành ràng buộc độ sâu, cũng không đảm bảo sao chép nghiêm ngặt độ sâu, quỹ đạo động tác hoặc chuyển cảnh của video gốc.

Video tham chiếu có thể giúp mô hình hiểu động tác, vị trí máy quay, bố cục và nhịp điệu, nhưng thành phẩm vẫn do mô hình tạo lại. Yêu cầu công khai hiện tại không có rãnh mã thời gian chung hoặc trường buộc chuyển cảnh; khi cần chuyển cảnh gần một thời điểm nào đó, chỉ có thể mô tả trong câu lệnh gợi ý và kiểm tra thành phẩm sau khi tạo; nếu bắt buộc chính xác đến từng khung hình, nên thực hiện ở giai đoạn dựng hoặc tổng hợp bên ngoài.

Rãnh âm thanh đầu vào và generate_audio

Khi video tham chiếu có rãnh âm thanh gốc, việc mô hình có đọc rãnh âm thanh đó hay không phụ thuộc vào cách triển khai video tham chiếu của mô hình hiện tại. Ý nghĩa xác định của generate_audio: false là tắt đầu ra âm thanh của kết quả tạo sinh, nó không cam kết sao chép rãnh âm thanh video đầu vào, cũng không cam kết dùng rãnh âm thanh đầu vào làm âm thanh tham chiếu độc lập.

• Khi mục tiêu là「tạo video không tiếng」, có thể truyền generate_audio: false;
• Khi mục tiêu là「giữ âm thanh video gốc」, đừng chỉ dựa vào trường này, mà nên xử lý bằng quy trình tổng hợp âm thanh-video của riêng bạn sau khi tải thành phẩm, hoặc chọn cấu hình mà chi tiết mô hình hỗ trợ rõ ràng âm thanh tham chiếu và âm thanh đầu ra;
• Khi chi tiết mô hình không tuyên bố hỗ trợ âm thanh tham chiếu, không gửi thêm reference_audio.

Năm, các giới hạn hiện chưa thể cam kết thống nhất

Về việc「nhóm hiện tại có hỗ trợ nhóm yêu cầu này không」

Nhóm gọi và nhóm thư viện tư liệu là hai khái niệm khác nhau, không thể chỉ dựa vào tên nhóm trong bảng điều khiển để xác định có hỗ trợ nhiều ảnh hoặc video tham chiếu hay không. Thứ tự xác định thực tế là:

1. Mô hình đã chọn tồn tại trong /v1/models;
2. Chi tiết mô hình cho phép rõ ràng ảnh tham chiếu và video tham chiếu;
3. Trạng thái tư liệu được tham chiếu là Active;
4. API tạo trả về queued, nghĩa là yêu cầu đã được tiếp nhận;
5. Nếu cuối cùng failed, đọc error.code và error.message để xác định vấn đề về tổ hợp hay tư liệu.

Nền tảng sẽ không âm thầm chuyển một mô hình không hỗ trợ video tham chiếu sang mô hình khác, để tránh phát sinh chi phí và kết quả không lường trước.

Sáu, khôi phục tác vụ, giới hạn tần suất, idempotent và tính phí

Truy vấn và khôi phục

Sau khi API tạo trả về id phải lưu ngay; khi mạng gián đoạn nhưng đã có ID tác vụ thì chỉ truy vấn tác vụ gốc. API công khai hiện tại không có cách chung để tra ngược tác vụ theo「câu lệnh gợi ý + tư liệu + tham số」; nếu kết nối bị gián đoạn trước khi phản hồi tạo trả về và không có ID tác vụ, nền tảng không thể đảm bảo tìm lại tác vụ gốc chỉ dựa vào nội dung yêu cầu. Vì vậy bên gọi nên lưu yêu cầu nghiệp vụ trong cơ sở dữ liệu của mình, và lưu ID tác vụ ngay khi nhận được phản hồi tiếp nhận.

Truy vấn lặp, giới hạn tần suất và lưu giữ

Nền tảng không công bố thống nhất số lượng đồng thời và tần suất truy vấn của mỗi khóa API cho tất cả nhóm gọi; máy khách nên tuân theo phản hồi 429 và dùng truy vấn lặp có giãn cách, khuyến nghị truy vấn mỗi 5～15 giây. Sau khi thành phẩm được tạo nên tải xuống hoặc chuyển lưu càng sớm càng tốt, không được coi URL trả về là địa chỉ vĩnh viễn; nếu tác vụ vẫn có thể truy vấn nhưng metadata.url đã hết hạn, hãy truy vấn lại tác vụ gốc trước; khi liên kết không thể khôi phục, API công khai không đảm bảo tạo lại được cùng một địa chỉ.

Idempotent và số yêu cầu phía máy khách

API video công khai hiện tại không cam kết trường idempotent chính thức do người dùng kiểm soát, cũng không cam kết số yêu cầu tùy chỉnh có thể khử trùng theo nội dung yêu cầu. Bên gọi có thể dùng số yêu cầu nghiệp vụ của mình để ghi liên kết, nhưng đừng coi nó là khóa idempotent mà nền tảng chắc chắn nhận diện; phía nền tảng chỉ có căn cứ khôi phục đáng tin cậy sau khi trả về ID tác vụ.

Đổi khóa API

Quyền sở hữu tác vụ và tư liệu dựa trên tài khoản nền tảng; trong cùng một tài khoản, sau khi đổi Key vẫn có thể tiếp tục truy vấn tác vụ gốc, chỉ cần dùng Key khi tạo tác vụ để thử lại truy vấn. Nếu Key sau khi đổi không thuộc cùng một tài khoản, truy vấn sẽ trả về 401 hoặc 404; khi đó không được tạo lại tác vụ để né tránh truy vấn thất bại.

Tính phí, thất bại và hoàn tiền

Việc nhập tư liệu, kiểm duyệt, tải video tham chiếu và tạo video có tính phí hay không phụ thuộc vào mô hình hiện tại và cấu hình giá của nền tảng. Tác vụ video thanh toán theo mức sử dụng thực tế khi hoàn thành, tạo thành công không trừ phí trước, sau khi hoàn thành hóa đơn chỉ xuất hiện một bản ghi trừ phí thực tế; trước khi gửi sẽ kiểm tra số dư có đủ cho ước tính hay không, nếu không đủ sẽ trả về trực tiếp thông báo có thể đọc được và không tạo tác vụ. Dữ liệu chi phí chỉ xuất hiện trong phản hồi truy vấn sau khi thanh toán hoàn tất:

• Phản hồi tạo chỉ có nghĩa là tác vụ đã được tiếp nhận, lúc này không có dữ liệu thanh toán nào, vì vậy không trả về trường trừ phí, đừng dựa vào phản hồi tạo để đánh giá chi phí lần này;
• Phản hồi truy vấn trả về usage sau khi tác vụ hoàn thành thanh toán: usage.total_tokens là số token video được tính phí lần này (thượng nguồn chỉ báo cáo một số token, theo quy ước hóa đơn của nền tảng ghi ở usage.prompt_tokens, usage.completion_tokens là 0), usage.quota là điểm đã tiêu hao, usage.amount là số tiền nhân dân tệ quy đổi từ cùng số điểm đó (usage.currency cố định là CNY);
• Kiểm tra tham số thất bại (HTTP 400 / 403) nghĩa là yêu cầu chưa được tiếp nhận, sẽ không phát sinh chi phí tác vụ tạo sinh;
• Sau khi đã trả về ID tác vụ, việc có thu phí và hoàn tiền khi thất bại được xử lý theo quy tắc tính phí của mô hình đó và nền tảng;
• Quy tắc trừ phí và hoàn tiền khi kiểm duyệt thất bại, tạo thất bại, hủy tác vụ không thể chỉ suy ra từ trạng thái tác vụ;
• Khi cần đối chiếu chi phí, lưu ID tác vụ, ID mô hình, thời gian tạo và tài khoản sở hữu khóa API, dùng usage.quota / usage.amount trong phản hồi truy vấn để đối chiếu với hóa đơn trong bảng điều khiển, hoặc liên hệ hỗ trợ nền tảng.

Bảy, phản hồi lỗi thường gặp

{
  "error": {
    "code": "invalid_parameter",
    "message": "当前模型不支持参考视频，或参考素材数量超出限制",
    "type": "invalid_request_error",
    "param": "content"
  }
}