API de génération

API de génération APIClaw pour les tâches image et vidéo asynchrones

Utilisez l’API de génération lorsque votre produit doit soumettre des tâches image ou vidéo, vérifier leur état et téléverser des ressources source de façon fiable.

Vue d’ensemble de l’API

• URL de base: https://www.apiclaw.net — Utilisez l’origine APIClaw déployée ou l’adresse serveur affichée dans votre compte.
• Authentification: Authorization: Bearer $YOUR_API_KEY — Créez une clé API dans la console et envoyez-la comme token Bearer.
• Enveloppe de réponse: { code, message, data } — Les réponses réussies renvoient un code, un message et un payload data typé.

Points d’accès API

Chaque workflow de génération suit la même logique : soumettre une tâche, vérifier son état et téléverser des ressources lorsqu’un modèle nécessite une image.

• POST /v2/images/generations — Soumettre une tâche image. Crée une tâche asynchrone de génération d’image.
• POST /v2/videos/generations — Soumettre une tâche vidéo. Crée une tâche asynchrone de génération vidéo.
• GET /v2/tasks/{task_id} — Interroger la tâche. Interrogez jusqu’à ce que la tâche atteigne un état final.
• POST /v2/upload — Téléverser un fichier. Téléversez un asset image et utilisez l’URL retournée dans une requête de génération.

Étape 1

Soumettre une tâche de génération image ou vidéo

Envoyez du JSON au point d’accès de génération image ou vidéo. La réponse renvoie un task_id à utiliser pour suivre la progression. Les modèles vidéo peuvent utiliser du texte, des images, des vidéos et des options extra selon la famille choisie.

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

Champ

Exemple

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

Requête de soumission

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

Réponse de soumission

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

Remarques

• Ouvrez la page de détail du modèle pour voir ses paramètres de requête.
• La génération d’images et de vidéos est asynchrone, même lorsque les résultats arrivent rapidement.
• Pour éditer une vidéo source avec Kling, envoyez videos avec extra.referType = "base" ; pour des références image simples, envoyez seulement images.

Étape 2

Interroger l’état de la tâche jusqu’à un état final

Interrogez l’endpoint de tâche avec le task_id retourné. Arrêtez lorsque le statut devient completed, failed, cancelled ou canceled.

GET /v2/tasks/{task_id}

Champ

Exemple

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

Requête de consultation

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

Réponse terminée

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

Remarques

• Utilisez un backoff exponentiel ou un court intervalle fixe pour éviter le polling inutile.
• Traitez failed, cancelled et canceled comme des états terminaux.

Étape 3

Téléverser des assets source pour les workflows avec image en entrée

Téléversez les fichiers image avant les workflows image-vers-vidéo ou de référence. Utilisez l’URL retournée dans image_url ou un autre champ propre au modèle.

POST /v2/upload

Champ

Exemple

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

Requête de téléversement

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

Réponse de téléversement

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

Remarques

• Ne définissez pas Content-Type manuellement pour les uploads multipart dans le navigateur ; laissez FormData définir la boundary.
• Utilisez l’URL téléversée avec les modèles qui acceptent une image en entrée.

Paramètres du modèle

L’API de génération utilise le même flux de tâches pour tous les modèles, mais chaque modèle peut proposer des paramètres différents. Consultez la page de détail du modèle avant la production pour confirmer les champs, limites et exemples.

APIClaw