API tạo hình ảnh

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) xem Xác thực và quy chuẩn cơ bản.

Tạo hình ảnh

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

Các mô hình hình ảnh có giới hạn về kích thước, số lượng, định dạng trả về khác nhau, trước tiên hãy xác nhận bằng /v1/models, và lấy lỗi kiểm tra tham số trả về từ API làm chuẩn.

Ví dụ yêu cầu

curl -X POST "https://locopalai.com/v1/images/generations" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "从 /v1/models 选择的图片模型 ID",
  "prompt": "白色桌面上的一个红苹果，柔和自然光，产品摄影",
  "size": "当前模型支持的尺寸",
  "n": 1
}
JSON

Tham số phản hồi

Một yêu cầu có thể chỉ trả về url hoặc chỉ trả về b64_json, tùy mô hình và kênh; hãy lấy trường thực tế trả về làm chuẩn, khi cả hai đều tồn tại ưu tiên dùng url.

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

Trả về địa chỉ (dạng url):

{
  "created": 1789567052,
  "data": [
    {
      "size": "2048x2048",
      "url": "https://media.example.com/image-public-id.jpeg"
    }
  ],
  "model": "Doubao-Seedream-4.5"
}

Trả về Base64 (dạng b64_json, trích đoạn):

{
  "background": "auto",
  "created": 1789071752,
  "data": [
    { "b64_json": "iVBORw0KGgoAAAANSUhEUgAABAAAAAQACAIAAADwf7zU..." }
  ]
}

Địa chỉ trả về ở dạng url có thể là địa chỉ ký tạm thời, vui lòng chuyển lưu hoặc ghi nhận kịp thời; dạng b64_json vui lòng tự giải mã và lưu trữ cẩn thận. Đừng giả định mọi mô hình hình ảnh đều chấp nhận response_format hoặc cùng kích thước. Thực tế gpt-image-1-mini sẽ từ chối response_format, Doubao-Seedream-4.5 hiện yêu cầu hình ảnh tối thiểu 3686400 pixel, 2048x2048 được tiếp nhận còn 1024x1024 sẽ trả về lỗi tham số.

Phản hồi lỗi

{
  "error": {
    "message": "当前图片模型不支持请求的尺寸",
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "param": "size"
  }
}

Giải thích đầy đủ xem Mã lỗi và khắc phục.

Tạo ảnh từ ảnh (chỉnh sửa hình ảnh)

Tạo hình ảnh mới dựa trên hình ảnh có sẵn: tải lên một hoặc nhiều ảnh tham chiếu, mô hình theo prompt viết lại khung hình, thay đổi phong cách hoặc vẽ lại cục bộ.

Phần thân yêu cầu · multipart/form-data

Yêu cầu phải mang theo ảnh tham chiếu, khi thiếu API trả về lỗi tham số trực tiếp, không đi vào mô hình.

Ví dụ yêu cầu

curl -X POST "https://locopalai.com/v1/images/edits" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -F "model=从 /v1/models 选择的图片模型 ID" \
  -F "prompt=把这张照片改成柔和的水彩画风格" \
  -F "size=1024x1024" \
  -F "image=@./reference.png"

  -F "image[]=@./reference-a.png" \
  -F "image[]=@./reference-b.png"

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

Cùng cấu trúc với Tạo hình ảnh, hình ảnh trả về dưới dạng b64_json hoặc url:

{
  "background": "opaque",
  "created": 1789651524,
  "data": [
    { "b64_json": "iVBORw0KGgoAAAANSUhEUgAABAAAAAQACAIAAADwf7zU..." }
  ],
  "output_format": "png",
  "quality": "low",
  "size": "1024x1024",
  "usage": {
    "input_tokens": 1041,
    "input_tokens_details": { "image_tokens": 1032, "text_tokens": 9 },
    "output_tokens": 439,
    "total_tokens": 1480
  }
}

usage.input_tokens_details.image_tokens phản ánh mức tiêu hao của ảnh tham chiếu: ảnh tham chiếu càng nhiều hoặc kích thước càng lớn, token đầu vào càng cao.

Truyền ảnh tham chiếu bằng địa chỉ công khai

Mô hình hỗ trợ đầu vào ảnh tham chiếu cũng có thể truyền bằng images trong phần thân yêu cầu JSON của POST /v1/images/generations, phần tử là địa chỉ hình ảnh https:// công khai:

curl -X POST "https://locopalai.com/v1/images/generations" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "从 /v1/models 选择的图片模型 ID",
  "prompt": "把这张照片改成柔和的水彩画风格",
  "images": ["https://example.com/reference.png"]
}
JSON

Ảnh tham chiếu phải có thể được máy chủ tải trực tiếp; khi địa chỉ hết hiệu lực hoặc cần đăng nhập, yêu cầu sẽ kết thúc bằng lỗi tải xuống từ thượng nguồn. Cấu trúc phản hồi giống với Tạo hình ảnh.

Mối quan hệ với thư viện tư liệu

Tạo hình ảnh sẽ không tự động vào thư viện tư liệu. Nếu tác vụ video sau đó muốn dùng hình ảnh làm ảnh tham chiếu, trước tiên hãy dùng API thư viện tư liệu để đưa vào thư viện và poll đến Active, rồi mới tham chiếu bằng asset://<asset_id>.