Generation API

APIClaw Generation API for async image and video tasks

Use the Generation API when your product needs a stable flow for submitting image or video jobs, checking task status, and uploading source assets.

API overview

• Base URL: https://www.apiclaw.net — Use your deployed APIClaw origin or the server address shown in your account.
• Authentication: Authorization: Bearer $YOUR_API_KEY — Create an API key in the console and send it as a Bearer token.
• Response envelope: { code, message, data } — Successful responses return a code, message and typed data payload.

API endpoints

Every generation workflow follows the same shape: submit a task, check the task status, and upload assets when a model needs image input.

• POST /v2/images/generations — Submit image task. Create an async image generation task.
• POST /v2/videos/generations — Submit video task. Create an async video generation task.
• GET /v2/tasks/{task_id} — Query task. Poll until the task reaches a final status.
• POST /v2/upload — Upload file. Upload an image asset and use the returned URL in a generation request.

Step 1

Submit an image or video generation task

Send JSON to the image or video generation endpoint. The response returns a task_id that you use to check progress. Video models can use text, images, videos and extra options depending on the selected family.

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

Field

Example

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

Submit request

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

Submit response

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

Notes

• Open the model detail page to see the exact request parameters for that model.
• Image and video generation are asynchronous even when results are produced quickly.
• For Kling source-video editing, send videos plus extra.referType = "base"; for normal image references, send images only.

Step 2

Query task status until a final state

Poll the task endpoint with the task_id returned by submit. Stop polling when the status becomes completed, failed, cancelled or canceled.

GET /v2/tasks/{task_id}

Field

Example

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

Query request

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

Completed response

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

Notes

• Use exponential backoff or a short fixed interval to avoid unnecessary polling.
• Treat failed, cancelled and canceled as terminal states.

Step 3

Upload source assets for image-input workflows

Upload image files before submitting image-to-video or reference workflows. Use the returned URL in image_url or another model-specific input field.

POST /v2/upload

Field

Example

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

Upload request

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

Upload response

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

Notes

• Do not set Content-Type manually for multipart uploads in browsers; let FormData set the boundary.
• Use the uploaded URL with models that accept image input.

Model parameters

The Generation API uses the same task flow across models, while each model can offer different request parameters. Open a model detail page before production use to confirm the fields, limits and examples for that model.

APIClaw