Bắt đầu nhanh

LocoPal hiện có hai cách sử dụng phổ biến: sáng tạo trực tiếp trên LocoPal Creation, hoặc dùng API của LocoPal Ai để tích hợp vào nghiệp vụ của bạn.

Hai cách dùng chung một tài khoản LocoPal, danh mục mô hình và hệ thống tính phí. Trang này tập trung trình bày LocoPal Ai và LocoPal Creation.

Bước 1: Đăng ký hoặc đăng nhập LocoPal Ai

1. Mở LocoPal Ai. Nếu đã có tài khoản thì đăng nhập trực tiếp; nếu chưa có thì vào trang đăng ký.
2. Trang đăng ký hiện tại yêu cầu đặt tên người dùng và mật khẩu, đồng thời hoàn tất xác minh SMS bằng số điện thoại. Cách xác minh có thể thay đổi theo chính sách bảo mật, hãy làm theo hướng dẫn thực tế trên trang đăng ký.
3. Sau khi đăng nhập, xác nhận số dư tài khoản, hạn mức gói hoặc điểm khả dụng. Trước khi dùng Creation hoặc API đều nên xác nhận trạng thái khả dụng của tài khoản.

Bước 2: Sử dụng trực tiếp LocoPal Creation

Nếu mục tiêu là tạo nội dung trực tiếp, nên dùng Creation trước, không cần viết mã cũng không cần tạo API Key.

1. Mở LocoPal Creation.
2. Creation không có tài khoản riêng. Khi chưa đăng nhập, trang sẽ chuyển đến trang đăng nhập LocoPal, sau khi hoàn tất ủy quyền sẽ tự động quay lại Creation, không cần nhập lại mật khẩu.
3. Trên trang chủ chọn chế độ thông minh, Vẽ AI, Video AI hoặc Âm thanh AI và nhập yêu cầu; sau khi vào bảng làm việc còn có thể dùng các lối vào phim ngắn, tác phẩm, tư liệu, prompt, kho từ và quảng trường tác phẩm.
4. Khi cần giữ nhất quán nhân vật, sản phẩm hoặc phong cách, hãy tải ảnh tham chiếu lên hoặc chọn tư liệu có sẵn trước khi gửi.
5. Sau khi gửi, xem trạng thái tác vụ, xem trước kết quả và tải xuống hoặc tiếp tục tham chiếu ngay trên trang hiện tại. Làm mới trang sẽ không tạo lại tác vụ, đừng gửi lặp lại với tác vụ đang thực thi.

Phạm vi mô hình khả dụng của Creation đồng bộ với danh mục mô hình hiện tại của LocoPal Ai, chi phí gọi được tính thống nhất vào tài khoản LocoPal hiện tại. Khi mô hình không khả dụng, trước tiên hãy vào chợ mô hình của LocoPal Ai để xác nhận mô hình đó đã nằm trong nhóm khả dụng hiện tại hay chưa.

Bước 3: Tích hợp API và tạo API Key

Vào mục 「Khóa API」 trong bảng điều khiển LocoPal Ai và nhấn tạo. Nên tạo khóa riêng cho 「dịch vụ sản xuất / môi trường kiểm thử / ứng dụng khách hàng」 để dễ xem nhật ký theo ứng dụng, giới hạn hạn mức và kịp thời vô hiệu hóa khóa bị lộ.

Khi tạo cần xác nhận trọng tâm:

• Tên Key dùng để phân biệt bên gọi;
• Nhóm gọi quyết định Key này nhìn thấy và gọi được những mô hình nào;
• Hạn mức và thời hạn hiệu lực dùng để hạn chế tiêu dùng bất thường;
• Một Key có thể gọi API mô hình, hình ảnh, video, âm thanh và tư liệu, không cần tạo Key khác cho từng API.

API Key chỉ lưu trong biến môi trường phía máy chủ hoặc dịch vụ quản lý khóa, không được ghi vào mã nguồn trang web, gói cài đặt di động, kho công khai, nhật ký hoặc ảnh chụp màn hình.

Bước 4: Chuẩn bị địa chỉ cơ sở

Địa chỉ cơ sở mặc định:

export LOCOPAL_API_KEY="sk-你的APIKey"
export LOCOPAL_BASE_URL="https://locopalai.com"

Bảng điều khiển nền tảng còn có thể hiển thị địa chỉ tích hợp dành cho mô hình hải ngoại hoặc môi trường mạng cụ thể, ví dụ:

https://us-api.locopalai.com

Khi tích hợp thực tế nên dùng địa chỉ bảng điều khiển hiển thị hiện tại. LOCOPAL_BASE_URL chỉ ghi đến tên miền, không lặp lại thêm /v1; bản thân đường dẫn API đã bao gồm /v1 hoặc /api/v1.

Bước 5: Truy vấn mô hình khả dụng của Key hiện tại

curl "$LOCOPAL_BASE_URL/v1/models" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

{
  "object": "list",
  "success": true,
  "data": [
    {
      "id": "doubao-seedance-2.0",
      "object": "model",
      "created": 1626777600,
      "owned_by": "doubaovideo",
      "supported_endpoint_types": ["openai"]
    }
  ]
}

• model trong yêu cầu phải dùng data[].id, không dùng tên hiển thị trên trang;
• Trả về "data": [] nghĩa là nhóm gọi của Key hiện tại không có mô hình khả dụng, hãy xác nhận cấu hình nhóm hoặc liên hệ hỗ trợ nền tảng;
• Danh mục mô hình sẽ thay đổi theo quyền tài khoản, địa chỉ tích hợp và tính khả dụng của nền tảng, nên truy vấn lại khi khởi động dịch vụ, khi người dùng chuyển mô hình hoặc khi nhận được 「mô hình không khả dụng」;
• Cùng một Key có thể thấy tập mô hình khác nhau trên locopalai.com và us-api.locopalai.com, dùng địa chỉ nào thì lấy /v1/models của địa chỉ đó làm chuẩn;
• Mô hình có gọi được hay không lấy kết quả /v1/models của Key hiện tại làm chuẩn, không viết cứng tên mô hình.

Dùng supported_endpoint_types để xác định nên dùng ví dụ nào

data[].supported_endpoint_types cho bạn biết trực tiếp mô hình này đi theo loại API nào, từ đó chọn ví dụ tương ứng:

supported_endpoint_types của một mô hình có thể chứa đồng thời nhiều mục, nghĩa là nó có thể được gọi bằng nhiều loại API.

Bước 6: Lệnh gọi văn bản đầu tiên

curl -X POST "$LOCOPAL_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "从 /v1/models 选择的文本模型 ID",
    "messages": [{ "role": "user", "content": "用三句话介绍这个产品" }],
    "stream": false
  }'

Khi thành công, đọc văn bản từ choices[0].message.content và lưu usage trong phản hồi để đối soát. Mô hình suy luận có thể tiêu hết max_tokens vào completion_tokens_details.reasoning_tokens, khi đó message.content rỗng và finish_reason là length; hãy tăng giới hạn đầu ra hoặc đổi sang mô hình không suy luận rồi thử lại. Sau khi bật stream: true, đọc từng đoạn theo SSE và kết thúc khi gặp [DONE].

Bước 7: Lệnh gọi hình ảnh đầu tiên

curl -X POST "$LOCOPAL_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "从 /v1/models 选择的图片模型 ID",
    "prompt": "白色桌面上的一个红苹果，柔和自然光，产品摄影",
    "size": "1024x1024",
    "n": 1
  }'

Kết quả phản hồi thường trả về url hoặc b64_json trong data[]. URL trả về có thể là địa chỉ ngắn hạn, nên chuyển lưu càng sớm càng tốt; size, quality và response_format đều phụ thuộc mô hình hình ảnh hiện tại, một số mô hình GPT Image sẽ từ chối response_format và trả về unknown_parameter, khi đó nên bỏ trường này. Khi dùng hình ảnh làm tham chiếu cho video sau này, trước tiên hãy nhập vào thư viện bằng API thư viện tư liệu và chờ trạng thái là Active, rồi tham chiếu bằng asset://<asset_id>.

Bước 8: Lệnh gọi video đầu tiên

Video là tác vụ bất đồng bộ: API tạo trả về ID tác vụ, API truy vấn trả về tiến độ và kết quả.

POST /v1/video/generations và POST /v1/videos dùng cùng một bộ thân yêu cầu và định dạng phản hồi, chọn một trong hai là được; đường dẫn gọi cũ sẽ được nền tảng tự động xử lý theo plugin tác vụ video.

curl -X POST "$LOCOPAL_BASE_URL/v1/video/generations" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "从 /v1/models 选择的视频模型 ID",
  "content": [
    { "type": "text", "text": "清晨的湖边，镜头缓慢向前推进" }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5
}
JSON

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

Phản hồi tạo chỉ nên dựa vào id / task_id, status, model và created_at; các trường như object, progress có thể chỉ xuất hiện sau lần truy vấn đầu tiên, không được coi chúng là điều kiện bắt buộc để tạo thành công.

Lưu id trong phản hồi tạo, rồi truy vấn cùng tác vụ:

export LOCOPAL_TASK_ID="创建响应里的 id"

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

Sau khi tác vụ thành công, đọc metadata.url để tải xuống hoặc phát kết quả. Nền tảng ưu tiên trả về URL video gốc từ thượng nguồn; chỉ khi thượng nguồn không trả về địa chỉ đọc được mới dùng địa chỉ sản phẩm của nền tảng để dự phòng. Tham số video thượng nguồn trả về có thể bao gồm:

{
  "metadata": {
    "url": "https://上游原始视频地址",
    "upstream_created": true
  },
  "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
}

Trong các trường trên, duration_secs là thời lượng; expires_at chỉ xuất hiện khi thượng nguồn tương ứng trả về; các tham số video khác cũng chỉ xuất hiện khi mô hình và thượng nguồn thực tế trả về. Sau khi có ID tác vụ, dù thời gian chờ cục bộ hết hạn cũng chỉ được tiếp tục truy vấn tác vụ gốc, không được tạo lại, nếu không sẽ phát sinh tác vụ trùng lặp và chi phí.

Nếu status của kết quả truy vấn là failed, hãy đọc error.code và error.message trong cùng phản hồi. Lỗi trạng thái cuối của tác vụ video thường dùng video_generation_failed, error.message là lý do dễ đọc sau khi nền tảng đã làm sạch, không cần phân tích JSON bên trong nữa:

{
  "id": "task-public-id",
  "status": "failed",
  "error": {
    "code": "video_generation_failed",
    "message": "音频素材缓冲失败: 音频地址必须是 http(s)"
  }
}

Bước 9: Lệnh gọi chuyển văn bản thành giọng nói đầu tiên

Nền tảng cung cấp API POST /v1/audio/speech tương thích OpenAI. Khả dụng hay không phụ thuộc nhóm và danh mục mô hình của API Key hiện tại; giọng đọc, định dạng và tham số tốc độ được hỗ trợ lấy mô hình thực tế làm chuẩn.

curl -X POST "$LOCOPAL_BASE_URL/v1/audio/speech" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "从 /v1/models 选择的音频模型 ID",
    "input": "欢迎使用 LocoPal Ai。",
    "voice": "alloy",
    "response_format": "mp3"
  }' \
  --output speech.mp3

Thân phản hồi thành công là âm thanh nhị phân, không phải JSON; ví dụ dùng --output để lưu thành speech.mp3. Trạng thái bất đồng bộ và sản phẩm của các tác vụ âm thanh khác có thể tra cứu trong 「Nhật ký tác vụ」.

Bước 10: Lệnh gọi tư liệu đầu tiên

curl -X POST "$LOCOPAL_BASE_URL/api/v1/materials/groups" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "name": "我的角色素材",
  "description": "视频参考图",
  "type": "virtual"
}
JSON

{
  "code": 0,
  "data": {
    "group": {
      "id": "group-1789069780-5762d1",
      "platform_group_id": "group-1789069780-5762d1",
      "name": "我的角色素材",
      "type": "virtual",
      "description": "视频参考图",
      "created_at": 1789069780,
      "updated_at": 1789069780
    }
  },
  "msg": "素材分组已创建"
}

Lưu data.group.id, gửi hình ảnh và thăm dò trạng thái:

curl -X POST "$LOCOPAL_BASE_URL/api/v1/materials/assets" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"group_id":"group-id","title":"角色正面图","image_url":"https://你的对象存储域名/person.png"}'

curl "$LOCOPAL_BASE_URL/api/v1/materials/assets/asset-id" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

image_url dùng địa chỉ http(s) có thể tải trực tiếp từ Internet công cộng, cũng có thể gửi data_url theo giới hạn của API. Khi data.asset.status chuyển thành Active, có thể tham chiếu bằng asset://<asset_id> trong yêu cầu video. Tham số đầy đủ và mô tả lỗi xem API thư viện tư liệu.

Bước 11: Tư liệu người thật (tùy chọn)

Tư liệu người thật phải do chính người đó dùng điện thoại quét mã QR để hoàn tất thu thập và ủy quyền, không thể thay thế bằng tải ảnh thông thường. Quy trình trên bảng điều khiển là 「Quản lý thư viện tư liệu → Tạo nhóm mới → Tư liệu người thật → Tạo mã QR → Người đó quét mã → Đã quét mã, bắt đầu đồng bộ」; quy trình API xem Tạo phiên quét mã người thật.

Bước tiếp theo