Magick API ユーザーガイド

統一動画タスク API から Wan 2.7 のテキスト動画生成、画像動画生成、参照動画生成、動画編集モデルを呼び出す方法を説明します。

送信ルート: POST /v1/videos
タスク照会: GET /v1/videos/{task_id}
コンテンツダウンロード: GET /v1/videos/{task_id}/content

動画生成は非同期タスクです。まずタスクを送信し、返された task_id で状態をポーリングしてください。タスク成功後は、生成動画を早めにダウンロードしてください。Wan 2.7 の上流結果 URL は通常 24 時間有効です。

対応モデル

モデル	用途	主な入力
`wan2.7-t2v`	テキストから動画	`prompt`
`wan2.7-i2v`	画像から動画、首尾フレーム、動画続き生成	`prompt`、`media` または `image`/`images`
`wan2.7-r2v`	参照から動画、複数主体の参照、参照音色	`prompt`、`media`
`wan2.7-videoedit`	動画編集	`prompt`、`media` 内の `video`

共通リクエストフィールド

フィールド	型	説明
`model`	string	必須。参照動画生成では `wan2.7-r2v` を指定します。
`prompt`	string	`wan2.7-r2v` では必須、最大 5000 文字です。素材は順番で参照します。英語では `Image 1`、`Video 1`、中国語では「图1」「视频1」のように指定します。画像と動画は別々に番号付けされます。
`media`	array	`wan2.7-r2v` では必須です。少なくとも 1 つの `reference_image` または `reference_video` が必要です。
`negative_prompt`	string	ネガティブプロンプト、最大 500 文字です。
`resolution`	string	解像度ランク。`720P` または `1080P`。デフォルトは `1080P` です。解像度によりコストが変わります。
`ratio`	string	出力アスペクト比。`16:9`、`9:16`、`1:1`、`4:3`、`3:4` をサポートし、デフォルトは `16:9` です。`wan2.7-r2v` で `first_frame` を指定した場合、この値は無視されます。
`duration`	number	動画の長さ（秒）。デフォルトは `5` です。`wan2.7-r2v` では、参照動画を含む場合は `2` から `10`、参照動画を含まない場合は `2` から `15` です。
`seconds`	string	`duration` の文字列形式。新規連携では `duration` を優先してください。
`metadata`	object	追加パラメータ。`wan2.7-r2v` でよく使うキーは `prompt_extend`、`watermark`、`seed` です。

`wan2.7-r2v` の `media`

各 media 要素には少なくとも type と url が必要です。配列の順番がプロンプト内の参照番号になります。最初の reference_image が Image 1、最初の reference_video が Video 1 です。画像と動画は独立して数えます。

type	利用条件	説明
`reference_image`	必須参照タイプの 1 つ	人物、動物、物体、シーンの参照画像。公開 URL、OSS 一時 URL、Base64 Data URL を指定できます。
`reference_video`	必須参照タイプの 1 つ	参照動画。主体が含まれる素材を使ってください。音声を含む場合は音色参照にもなります。公開 URL と OSS 一時 URL を指定できます。
`first_frame`	任意	先頭フレーム画像。最大 1 枚です。指定すると `ratio` は無視され、出力は先頭フレームの比率に従います。

reference_image と reference_video は合計 5 個まで指定できます。参照素材が主体を表す場合、公式では 1 素材 1 役を推奨しています。reference_image と reference_video には、その主体の音色を指定する reference_voice も設定できます。

メディア制限

メディア	形式	制限
`reference_image` / `first_frame`	JPEG, JPG, PNG, BMP, WEBP	幅と高さ `[240, 8000]`、アスペクト比 `1:8` から `8:1`、最大 20MB。PNG の透過はサポートされません。
`reference_video`	MP4, MOV	長さ `1` から `30` 秒、幅と高さ `[240, 4096]`、アスペクト比 `1:8` から `8:1`、最大 100MB。
`reference_voice`	WAV, MP3	長さ `1` から `10` 秒、最大 15MB。音色だけを参照し、話す内容は決めません。

参照から動画

参照画像、参照動画、参照音色を含む複数主体の例です。

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 is holding Image 3 while playing a gentle country song on the chair from Image 4, and says: The sunshine is lovely today. Image 1 walks past Video 1 holding Image 2, puts Image 2 on the nearby table, and says: That sounds great, can you sing it again?",
    "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
    }
  }'

1 枚のストーリーボード画像だけを渡す場合も reference_image を使います。

{
  "model": "wan2.7-r2v",
  "prompt": "Reference image, 3D cartoon adventure film style, keep the characters and forest scene consistent. Story beats: wide shot of the forest, the boy opens vines, the robot scans ahead, and they finally find a treasure chest.",
  "media": [
    {
      "type": "reference_image",
      "url": "https://example.com/storyboard.png"
    }
  ],
  "resolution": "720P",
  "duration": 10,
  "metadata": {
    "prompt_extend": false,
    "watermark": false
  }
}

先頭フレームを固定したい場合は first_frame を追加します。

{
  "model": "wan2.7-r2v",
  "prompt": "Video 1 enters from the doorway of the room in Image 1 and talks with the character in 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
}

その他の Wan 2.7 モード

テキストから動画:

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": "紙飛行機が日差しの中で机の上をゆっくり飛ぶ。カメラは安定し、画面はシンプル。",
    "resolution": "720P",
    "ratio": "16:9",
    "duration": 5
  }'

画像から動画:

{
  "model": "wan2.7-i2v",
  "prompt": "画像の猫がカメラを見上げ、カメラが少し寄っていく。",
  "image": "https://example.com/first-frame.png",
  "resolution": "720P",
  "duration": 5
}

動画編集:

{
  "model": "wan2.7-videoedit",
  "prompt": "主体の動きは保持し、背景を夜のサイバーパンクな街並みに置き換える。",
  "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
  }
}

レスポンス、照会、ダウンロード

送信に成功するとタスクオブジェクトが返ります。

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

タスク状態を照会します。

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

状態は queued、in_progress、completed、failed のいずれかです。成功時は metadata.url に上流の一時動画 URL が入ります。ファイル保存にはコンテンツダウンロードルートの利用を推奨します。

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

ポーリング例

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 sits by the cafe window playing guitar. Video 1 walks into the frame and talks with 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));
}

Wan 2.7 動画生成