API tạo sinh

API tạo sinh APIClaw cho tác vụ ảnh và video bất đồng bộ

Dùng API tạo sinh khi sản phẩm cần quy trình ổn định để gửi tác vụ ảnh hoặc video, kiểm tra trạng thái và tải lên tài nguyên nguồn.

Tổng quan API

URL cơ sở: https://www.apiclaw.net — Dùng origin APIClaw đã triển khai hoặc server address hiển thị trong tài khoản.
Xác thực: Authorization: Bearer $YOUR_API_KEY — Tạo API key trong console và gửi dưới dạng Bearer token.
Khung response: { code, message, data } — Response thành công trả về code, message và data payload có kiểu.

Endpoint API

Mỗi quy trình tạo sinh đều có cùng dạng: gửi tác vụ, kiểm tra trạng thái và tải lên tài nguyên khi mô hình cần đầu vào hình ảnh.

POST /v2/images/generations — Gửi tác vụ hình ảnh. Tạo tác vụ tạo hình ảnh bất đồng bộ.
POST /v2/videos/generations — Gửi tác vụ video. Tạo tác vụ tạo video bất đồng bộ.
GET /v2/tasks/{task_id} — Truy vấn tác vụ. Poll cho đến khi tác vụ đạt trạng thái cuối.
POST /v2/upload — Upload tệp. Upload asset hình ảnh và dùng URL trả về trong request tạo.

Bước 1

Gửi tác vụ tạo hình ảnh hoặc video

Gửi JSON tới endpoint tạo ảnh hoặc video. Phản hồi trả về task_id để kiểm tra tiến độ. Mô hình video có thể dùng văn bản, ảnh, video và tùy chọn extra tùy theo nhóm mô hình.

POST /v2/images/generations POST /v2/videos/generations

Trường

Trường	Kiểu	Bắt buộc	Mô tả
`model`	string	Bắt buộc	Tên mô hình được chọn từ thư mục mô hình.
`prompt`	string	Bắt buộc	Chỉ dẫn dạng văn bản cho tác vụ tạo hình ảnh hoặc video.
`images`	array	Tùy chọn	URL hình ảnh cho workflow image-to-video, first/last-frame hoặc reference.
`videos`	array	Tùy chọn	URL video cho workflow reference hoặc chỉnh sửa base-video thực tế khi mô hình đã chọn hỗ trợ.
`duration`	number	Tùy chọn	Thời lượng video yêu cầu khi mô hình có điều khiển duration.
`extra`	object	Tùy chọn	Các điều khiển mô hình tùy chọn như Kling referType, keep_original_sound, sound hoặc mode.

Ví dụ

curl https://www.apiclaw.net/v2/videos/generations \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling/kling-v3-omni",
    "prompt": "Put the jewelry from the reference image on the person in the video",
    "videos": ["https://cdn.example.com/source.mp4"],
    "images": ["https://cdn.example.com/ref.png"],
    "duration": 8,
    "resolution": "std",
    "extra": {
      "referType": "base"
    }
  }'

Request gửi tác vụ

{
  "model": "kling/kling-v3-omni",
  "prompt": "Put the jewelry from the reference image on the person in the video",
  "videos": [
    "https://cdn.example.com/source.mp4"
  ],
  "images": [
    "https://cdn.example.com/ref.png"
  ],
  "duration": 8,
  "resolution": "std",
  "extra": {
    "referType": "base"
  }
}

Response gửi tác vụ

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "task_01JXYZ9Y8K6G3R4S5T6V7W8X9Y",
    "status": "submitted"
  }
}

Ghi chú

Mở trang chi tiết mô hình để xem tham số yêu cầu của mô hình đó.
Tạo ảnh và video là tác vụ bất đồng bộ, ngay cả khi kết quả được tạo nhanh.
Để chỉnh sửa video nguồn với Kling, gửi videos cùng extra.referType = "base"; với tham chiếu ảnh thông thường, chỉ gửi images.

Bước 2

Truy vấn trạng thái tác vụ tới trạng thái cuối

Poll endpoint tác vụ bằng task_id từ submit. Dừng khi status là completed, failed, cancelled hoặc canceled.

GET /v2/tasks/{task_id}

Trường

Trường	Kiểu	Bắt buộc	Mô tả
`task_id`	string	Bắt buộc	Định danh tác vụ được endpoint submit trả về.
`status`	string	Bắt buộc	Trạng thái tác vụ như submitted, processing, completed, failed hoặc cancelled.
`progress`	number	Tùy chọn	Phần trăm tiến độ khi provider có trả progress.
`result`	object	Tùy chọn	URL hình ảnh hoặc video sau khi tác vụ hoàn tất.
`error`	object	Tùy chọn	Chi tiết lỗi provider hoặc gateway khi tác vụ thất bại.

Ví dụ

curl https://www.apiclaw.net/v2/tasks/task_01JXYZ9Y8K6G3R4S5T6V7W8X9Y \
  -H "Authorization: Bearer $YOUR_API_KEY"

Request truy vấn

{
  "method": "GET",
  "path": "/v2/tasks/task_01JXYZ9Y8K6G3R4S5T6V7W8X9Y"
}

Response hoàn tất

{
  "code": 200,
  "message": "success",
  "data": {
    "id": "task_01JXYZ9Y8K6G3R4S5T6V7W8X9Y",
    "task_id": "task_01JXYZ9Y8K6G3R4S5T6V7W8X9Y",
    "status": "completed",
    "progress": 100,
    "result": {
      "videos": [
        {
          "url": "https://cdn.example.com/result.mp4",
          "thumbnail_url": "https://cdn.example.com/cover.jpg"
        }
      ],
      "images": [
        {
          "url": "https://cdn.example.com/result.png"
        }
      ]
    },
    "error": null
  }
}

Ghi chú

Dùng exponential backoff hoặc khoảng cố định ngắn để tránh polling không cần thiết.
Xem failed, cancelled và canceled là trạng thái cuối.

Bước 3

Upload asset nguồn cho workflow đầu vào hình ảnh

Upload file hình ảnh trước khi gửi workflow image-to-video hoặc reference. Dùng URL trả về trong image_url hoặc field riêng của mô hình.

POST /v2/upload

Trường

Trường	Kiểu	Bắt buộc	Mô tả
`file`	File	Bắt buộc	Field multipart form chứa file hình ảnh.
`url`	string	Bắt buộc	Asset URL có thể truy cập công khai để truyền vào request tạo.
`cosKey`	string	Bắt buộc	Storage key dùng cho truy vết và tra cứu nội bộ.
`mimeType`	string	Bắt buộc	MIME type được phát hiện từ file upload.
`fileSize`	number	Bắt buộc	Kích thước file upload tính bằng byte.

Ví dụ

curl https://www.apiclaw.net/v2/upload \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -F "file=@./source.png"

Request upload

{
  "content_type": "multipart/form-data",
  "field": "file"
}

Response upload

{
  "cosKey": "uploads/2026/06/source.png",
  "url": "https://cdn.example.com/source.png",
  "mimeType": "image/png",
  "fileSize": 245760
}

Ghi chú

Không đặt Content-Type thủ công cho multipart uploads trong browser; hãy để FormData đặt boundary.
Dùng URL đã tải lên với các mô hình chấp nhận đầu vào hình ảnh.

Tham số mô hình

API tạo sinh dùng cùng luồng tác vụ cho các mô hình, nhưng mỗi mô hình có thể có tham số yêu cầu khác nhau. Hãy mở trang chi tiết mô hình trước khi dùng production để xác nhận trường, giới hạn và ví dụ.

APIClaw