Magick API ユーザーガイド

統一動画タスクインターフェースを通じて Doubao 動画モデルを呼び出す；現在のプロジェクトで利用可能なモデル、リクエストフィールド、およびクエリ方法について説明します。

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

旧互換ルート POST /v1/video/generations と GET /v1/video/generations/{task_id} も残っています。新規接続では、プレイグラウンドおよびモデル endpoint メタデータと一致する /v1/videos を使用してください。

リクエスト送信例

cURL

curl --request POST \
  --url https://api.magickapi.com/v1/videos \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "doubao-seedance-2-0-260128",
    "prompt": "子犬が歌っている",
    "seconds": "5",
    "metadata": {
      "resolution": "720p",
      "ratio": "16:9",
      "generate_audio": true
    }
  }'

送信成功レスポンス例

{
  "id": "task_01KXYZ1234567890ABCDE",
  "task_id": "task_01KXYZ1234567890ABCDE",
  "object": "video",
  "model": "doubao-seedance-2-0-260128",
  "status": "queued",
  "progress": 0,
  "created_at": 1712345678
}

クエリとダウンロード

cURL タスク状態クエリ

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

cURL 動画ファイルダウンロード

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

Python ポーリングとダウンロード

import time
import requests

base_url = "https://api.magickapi.com"
api_key = "YOUR_API_KEY"
headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json",
}

submit_payload = {
    "model": "doubao-seedance-2-0-260128",
    "prompt": "子犬が歌っている",
    "seconds": "5",
    "metadata": {
        "resolution": "720p",
        "ratio": "16:9",
        "generate_audio": True,
    },
}

submit_resp = requests.post(
    f"{base_url}/v1/videos",
    headers=headers,
    json=submit_payload,
    timeout=300,
)
submit_resp.raise_for_status()
task = submit_resp.json()
task_id = task.get("id") or task.get("task_id")
print("task_id:", task_id)

while True:
    query_resp = requests.get(
        f"{base_url}/v1/videos/{task_id}",
        headers={"Authorization": f"Bearer {api_key}"},
        timeout=300,
    )
    query_resp.raise_for_status()
    status = query_resp.json()
    print(status)

    if status["status"] == "completed":
        download_resp = requests.get(
            f"{base_url}/v1/videos/{task_id}/content",
            headers={"Authorization": f"Bearer {api_key}"},
            timeout=600,
        )
        download_resp.raise_for_status()
        with open("doubao-output.mp4", "wb") as f:
            f.write(download_resp.content)
        print("saved: doubao-output.mp4")
        break

    if status["status"] == "failed":
        message = (status.get("error") or {}).get("message", "video generation failed")
        raise RuntimeError(message)

    time.sleep(10)

Node.js ポーリングとダウンロード

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

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

const submitPayload = {
  model: "doubao-seedance-2-0-260128",
  prompt: "子犬が歌っている",
  seconds: "5",
  metadata: {
    resolution: "720p",
    ratio: "16:9",
    generate_audio: true,
  },
};

const submitResp = await fetch(`${baseUrl}/v1/videos`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(submitPayload),
});

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

const task = await submitResp.json();
const taskId = task.id || task.task_id;
console.log("task_id:", taskId);

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}`,
      },
    });
    if (!downloadResp.ok) {
      throw new Error(await downloadResp.text());
    }
    const buffer = Buffer.from(await downloadResp.arrayBuffer());
    await writeFile("doubao-output.mp4", buffer);
    console.log("saved: doubao-output.mp4");
    break;
  }

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

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

OpenAI スタイルクエリ例

{
  "id": "task_01KXYZ1234567890ABCDE",
  "object": "video",
  "model": "doubao-seedance-2-0-260128",
  "status": "completed",
  "progress": 100,
  "created_at": 1712345678,
  "completed_at": 1712345720,
  "metadata": {
    "url": "https://example.com/generated-video.mp4"
  }
}

現在のプロジェクトが実際に解析する公開トップレベルフィールド

model
prompt
mode
image
images
input_reference
size
duration
seconds
metadata

Doubao 関連パラメータの記述方法

テキストのみから動画生成

最小推奨フィールド：

model
prompt
seconds
metadata.resolution
metadata.ratio

画像から動画生成

最初のフレーム入力のみが必要な場合、トップレベルの images を使用できます：

{
  "model": "doubao-seedance-2-0-fast-260128",
  "prompt": "人物をカメラに向かって近づける",
  "images": ["https://example.com/first-frame.png"],
  "seconds": "5",
  "metadata": {
    "resolution": "720p",
    "ratio": "9:16"
  }
}

動画 / 音声参照

より複雑な参照入力は metadata.content に記述し、上流のフィールド名を使用します：

image_url
video_url
audio_url

その他の一般的な拡張フィールド

一般的な拡張パラメータも metadata の下に配置します。例：

generate_audio
return_last_frame
seed
camera_fixed
watermark

旧互換クエリ

旧タスク照会ルートも引き続き利用できます：

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

Doubao Seedance 2.0 動画生成