生成 API

非同期の画像・動画タスク向け APIClaw 生成 API

画像または動画ジョブの送信、タスク状態の確認、素材アップロードを安定して行いたい場合は、生成 API を使用します。

API概要

ベースURL: https://www.apiclaw.net — デプロイ済みのAPIClaw origin、またはアカウントに表示されるserver addressを使用します。
認証: Authorization: Bearer $YOUR_API_KEY — コンソールでAPI keyを作成し、Bearer tokenとして送信します。
レスポンス形式: { code, message, data } — 成功レスポンスはcode、message、型付きdata payloadを返します。

API エンドポイント

生成ワークフローは共通して、タスクを送信し、状態を確認し、モデルが画像入力を必要とする場合は素材をアップロードします。

POST /v2/images/generations — 画像タスクを送信. 非同期の画像生成タスクを作成します。
POST /v2/videos/generations — 動画タスクを送信. 非同期の動画生成タスクを作成します。
GET /v2/tasks/{task_id} — タスクを照会. タスクが最終状態になるまでポーリングします。
POST /v2/upload — ファイルをアップロード. 画像assetをアップロードし、返されたURLを生成リクエストで使用します。

ステップ1

画像または動画生成タスクを送信する

画像または動画生成エンドポイントに JSON を送信します。レスポンスの task_id で進行状況を確認できます。動画モデルでは、選択したファミリーに応じてテキスト、画像、動画、extra オプションを使用できます。

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

フィールド

フィールド	型	必須	説明
`model`	string	必須	モデルディレクトリで選択したモデル名です。
`prompt`	string	必須	画像または動画生成タスクへのテキスト指示です。
`images`	array	任意	image-to-video、first/last-frame、reference workflowで使う画像URLです。
`videos`	array	任意	選択したモデルが対応する場合、reference workflowまたは実用的なbase-video編集で使う動画URLです。
`duration`	number	任意	選択したモデルがduration制御を公開している場合の要求動画長です。
`extra`	object	任意	Kling referType、keep_original_sound、sound、mode などの任意のモデル制御項目です。

例

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"
    }
  }'

送信リクエスト

{
  "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"
  }
}

送信レスポンス

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

注意

モデル詳細ページで、そのモデルのリクエストパラメータを確認してください。
画像と動画の生成は、結果がすぐに返る場合でも非同期タスクです。
Kling で元動画を編集する場合は videos と extra.referType = "base" を送信します。通常の画像参照では images のみを送信します。

ステップ2

最終状態までタスク状態を照会する

送信時に返されたtask_idでタスクendpointをポーリングします。statusがcompleted、failed、cancelled、canceledになったら停止します。

GET /v2/tasks/{task_id}

フィールド

フィールド	型	必須	説明
`task_id`	string	必須	送信endpointが返すタスク識別子です。
`status`	string	必須	submitted、processing、completed、failed、cancelledなどのタスク状態です。
`progress`	number	任意	providerが進捗を公開する場合の進捗率です。
`result`	object	任意	タスク完了後の生成画像または動画URLです。
`error`	object	任意	タスク失敗時のproviderまたはgatewayのエラー詳細です。

例

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

照会リクエスト

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

完了レスポンス

{
  "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
  }
}

注意

不要なポーリングを避けるため、指数バックオフまたは短い固定間隔を使用します。
failed、cancelled、canceledは終端状態として扱います。

ステップ3

画像入力workflow用のソースassetをアップロードする

image-to-videoまたはreference workflowを送信する前に画像ファイルをアップロードします。返されたURLをimage_urlまたはモデル固有の入力フィールドで使用します。

POST /v2/upload

フィールド

フィールド	型	必須	説明
`file`	File	必須	画像ファイルを含むmultipartフォームフィールドです。
`url`	string	必須	生成リクエストに渡せる公開到達可能なasset URLです。
`cosKey`	string	必須	追跡性と内部参照のために返されるstorage keyです。
`mimeType`	string	必須	アップロードファイルから検出されたMIME typeです。
`fileSize`	number	必須	アップロードファイルサイズをbytesで表します。

例

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

アップロードリクエスト

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

アップロードレスポンス

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

注意

ブラウザのmultipart uploadではContent-Typeを手動設定せず、FormDataにboundaryを設定させます。
アップロード後の URL は、画像入力に対応するモデルで使用します。

モデルパラメータ

生成 API はモデル間で同じタスクフローを使いますが、モデルごとにリクエストパラメータは異なります。本番利用前にモデル詳細ページでフィールド、制限、例を確認してください。

APIClaw