Guide utilisateur Magick API

Appeler les modeles Wan 2.7 texte-vers-video, image-vers-video, reference-vers-video et edition video via l'API unifiee de taches video.

Route de soumission : POST /v1/videos
Requete de tache : GET /v1/videos/{task_id}
Telechargement du contenu : GET /v1/videos/{task_id}/content

La generation video est asynchrone. Soumettez d'abord une tache, puis interrogez son etat avec le task_id retourne. Une fois la tache terminee, telechargez rapidement la video generee. Les URL de resultat amont Wan 2.7 sont generalement valides 24 heures.

Modeles pris en charge

Modele	Cas d'utilisation	Entree principale
`wan2.7-t2v`	Texte vers video	`prompt`
`wan2.7-i2v`	Image vers video, premiere/derniere image, continuation video	`prompt`, `media` ou `image`/`images`
`wan2.7-r2v`	Reference vers video, references multi-sujets, voix de reference	`prompt`, `media`
`wan2.7-videoedit`	Edition video	`prompt`, element `video` dans `media`

Champs de requete communs

Champ	Type	Description
`model`	string	Obligatoire. Utilisez `wan2.7-r2v` pour la generation reference-vers-video.
`prompt`	string	Obligatoire pour `wan2.7-r2v`, jusqu'a 5000 caracteres. Referencez les medias par ordre, par exemple `Image 1` et `Video 1`; les images et les videos sont numerotees separement.
`media`	array	Obligatoire pour `wan2.7-r2v`. Doit contenir au moins un `reference_image` ou `reference_video`.
`negative_prompt`	string	Prompt negatif, jusqu'a 500 caracteres.
`resolution`	string	Palier de resolution. `720P` ou `1080P`; valeur par defaut `1080P`. Le cout change selon la resolution.
`ratio`	string	Rapport d'image de sortie. Valeurs prises en charge : `16:9`, `9:16`, `1:1`, `4:3`, `3:4`; valeur par defaut `16:9`. Pour `wan2.7-r2v`, ce champ est ignore quand `first_frame` est fourni.
`duration`	number	Duree en secondes; valeur par defaut `5`. Pour `wan2.7-r2v`, la plage est `2` a `10` si une video de reference est fournie, et `2` a `15` sans video de reference.
`seconds`	string	Forme chaine de `duration`; preferez `duration` pour les nouvelles integrations.
`metadata`	object	Parametres supplementaires. Cles courantes pour `wan2.7-r2v` : `prompt_extend`, `watermark`, `seed`.

`media` pour `wan2.7-r2v`

Chaque element media doit contenir au minimum type et url. L'ordre du tableau definit les references dans le prompt : la premiere reference_image est Image 1, et la premiere reference_video est Video 1. Les images et les videos sont comptees independamment.

type	Disponibilite	Description
`reference_image`	Un des types de reference requis	Image de reference pour une personne, un animal, un objet ou une scene. Accepte les URL publiques, les URL temporaires OSS et les Data URL Base64.
`reference_video`	Un des types de reference requis	Video de reference. Utilisez un contenu qui contient le sujet; elle peut aussi fournir une reference de voix si elle contient de l'audio. Accepte les URL publiques et les URL temporaires OSS.
`first_frame`	Optionnel	Image de premiere frame, maximum 1. Quand elle est fournie, `ratio` est ignore et la sortie suit le ratio de cette image.

reference_image plus reference_video accepte jusqu'a 5 elements au total. Si un media de reference represente un sujet, la recommandation officielle est de garder un seul role par media. reference_image et reference_video peuvent inclure reference_voice pour definir la voix de ce sujet.

Limites des medias

Media	Formats	Limites
`reference_image` / `first_frame`	JPEG, JPG, PNG, BMP, WEBP	Largeur et hauteur `[240, 8000]`, ratio `1:8` a `8:1`, taille jusqu'a 20MB. La transparence PNG n'est pas prise en charge.
`reference_video`	MP4, MOV	Duree `1` a `30` secondes, largeur et hauteur `[240, 4096]`, ratio `1:8` a `8:1`, taille jusqu'a 100MB.
`reference_voice`	WAV, MP3	Duree `1` a `10` secondes, taille jusqu'a 15MB. Elle controle uniquement le timbre de voix, pas le contenu parle.

Reference vers video

Exemple multi-sujets avec images de reference, video de reference et voix de reference :

curl --request POST \
  --url https://api.magickapi.com/v1/videos \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "wan2.7-r2v",
    "prompt": "Video 1 tient Image 3 tout en jouant une chanson country douce sur la chaise de Image 4, puis dit : Le soleil est agreable aujourd'hui. Image 1 passe devant Video 1 avec Image 2, pose Image 2 sur la table proche, puis dit : C'est tres joli, peux-tu la rejouer ?",
    "media": [
      {
        "type": "reference_image",
        "url": "https://example.com/girl.jpg",
        "reference_voice": "https://example.com/girl-voice.mp3"
      },
      {
        "type": "reference_video",
        "url": "https://example.com/boy-role.mp4",
        "reference_voice": "https://example.com/boy-voice.mp3"
      },
      {
        "type": "reference_image",
        "url": "https://example.com/prop.png"
      },
      {
        "type": "reference_image",
        "url": "https://example.com/chair.png"
      }
    ],
    "resolution": "720P",
    "ratio": "16:9",
    "duration": 10,
    "metadata": {
      "prompt_extend": false,
      "watermark": false,
      "seed": 7
    }
  }'

Pour une seule image storyboard, utilisez aussi reference_image :

{
  "model": "wan2.7-r2v",
  "prompt": "Reference image, style film d'aventure cartoon 3D, conserver les personnages et la foret. Sequence : plan large de la foret, le garcon ouvre les lianes, le robot scanne devant lui, puis ils trouvent un coffre.",
  "media": [
    {
      "type": "reference_image",
      "url": "https://example.com/storyboard.png"
    }
  ],
  "resolution": "720P",
  "duration": 10,
  "metadata": {
    "prompt_extend": false,
    "watermark": false
  }
}

Pour contraindre la premiere frame, ajoutez first_frame :

{
  "model": "wan2.7-r2v",
  "prompt": "Video 1 entre par la porte de la piece dans Image 1 et parle avec le personnage de Image 2.",
  "media": [
    {
      "type": "first_frame",
      "url": "https://example.com/first-frame.png"
    },
    {
      "type": "reference_video",
      "url": "https://example.com/role.mp4"
    },
    {
      "type": "reference_image",
      "url": "https://example.com/second-role.png"
    }
  ],
  "resolution": "720P",
  "duration": 8
}

Autres modes Wan 2.7

Texte vers video :

curl --request POST \
  --url https://api.magickapi.com/v1/videos \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "wan2.7-t2v",
    "prompt": "Un avion en papier glisse lentement au-dessus d'un bureau au soleil, camera stable, composition nette.",
    "resolution": "720P",
    "ratio": "16:9",
    "duration": 5
  }'

Image vers video :

{
  "model": "wan2.7-i2v",
  "prompt": "Faire lever les yeux du chat vers la camera, avec un leger travelling avant.",
  "image": "https://example.com/first-frame.png",
  "resolution": "720P",
  "duration": 5
}

Edition video :

{
  "model": "wan2.7-videoedit",
  "prompt": "Conserver le mouvement du sujet et remplacer l'arriere-plan par une rue cyberpunk de nuit.",
  "media": [
    {
      "type": "video",
      "url": "https://example.com/source.mp4"
    },
    {
      "type": "reference_image",
      "url": "https://example.com/style-reference.png"
    }
  ],
  "resolution": "720P",
  "duration": 5,
  "metadata": {
    "audio_setting": "origin",
    "watermark": false
  }
}

Reponse, requete et telechargement

Une soumission reussie retourne un objet de tache :

{
  "id": "task_01KXYZ1234567890ABCDE",
  "task_id": "task_01KXYZ1234567890ABCDE",
  "object": "video",
  "model": "wan2.7-r2v",
  "status": "queued",
  "progress": 0,
  "created_at": 1712345678
}

Interroger l'etat de la tache :

curl https://api.magickapi.com/v1/videos/task_01KXYZ1234567890ABCDE \
  -H 'Authorization: Bearer YOUR_API_KEY'

L'etat peut etre queued, in_progress, completed ou failed. Quand la tache reussit, metadata.url contient l'URL temporaire amont. Preferez la route de telechargement du contenu pour enregistrer le fichier :

curl -L https://api.magickapi.com/v1/videos/task_01KXYZ1234567890ABCDE/content \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --output wan2-7-r2v-output.mp4

Exemple de polling

import { writeFile } from "node:fs/promises";

const baseUrl = "https://api.magickapi.com";
const apiKey = "YOUR_API_KEY";

const submitResp = await fetch(`${baseUrl}/v1/videos`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "wan2.7-r2v",
    prompt: "Image 1 est assise pres de la fenetre du cafe et joue de la guitare. Video 1 entre dans le cadre et parle avec Image 1.",
    media: [
      {
        type: "reference_image",
        url: "https://example.com/character.png",
        reference_voice: "https://example.com/voice.mp3",
      },
      {
        type: "reference_video",
        url: "https://example.com/action.mp4",
      },
    ],
    resolution: "720P",
    ratio: "16:9",
    duration: 10,
    metadata: {
      prompt_extend: false,
      watermark: false,
    },
  }),
});

if (!submitResp.ok) {
  throw new Error(await submitResp.text());
}

const task = await submitResp.json();
const taskId = task.id || task.task_id;

while (true) {
  const queryResp = await fetch(`${baseUrl}/v1/videos/${taskId}`, {
    headers: {
      Authorization: `Bearer ${apiKey}`,
    },
  });

  if (!queryResp.ok) {
    throw new Error(await queryResp.text());
  }

  const status = await queryResp.json();
  console.log(status);

  if (status.status === "completed") {
    const downloadResp = await fetch(`${baseUrl}/v1/videos/${taskId}/content`, {
      headers: {
        Authorization: `Bearer ${apiKey}`,
      },
    });
    const buffer = Buffer.from(await downloadResp.arrayBuffer());
    await writeFile("wan2-7-r2v-output.mp4", buffer);
    break;
  }

  if (status.status === "failed") {
    throw new Error(status.error?.message || "video generation failed");
  }

  await new Promise((resolve) => setTimeout(resolve, 15000));
}

Generation video Wan 2.7