APIドキュメント

オープンプラットフォーム API ドキュメント (v1)

このドキュメントでは、音子AIオープンプラットフォーム API の使用方法について説明します。開発者は、API を介して注文の作成やクエリなどの操作を行うことができます。

認証 (Authentication)

すべてのインターフェースは apiKey による認証が必要です。システムは apiKey に基づいてユーザーを識別し、セッションやトークンには依存しません。 「マイページ」->「API Key」でキーを取得できます。

認証方法は以下の2種類をサポートしています：

1. ヘッダー認証 (推奨)

   Authorization: Bearer <your_api_key>
   

2. クエリパラメータ認証

   ?apiKey=<your_api_key>
   

ベース URL

https://api.yinziai.com

---

インターフェース一覧

1. 注文作成 (Create Order)

非同期処理の注文を作成します。システムは自動的に注文番号を生成して返します。

• URL: /api/open/v1/order/create
• Method: POST
• Content-Type: application/json

リクエストパラメータ

パラメータ名	タイプ	必須	説明
orderType	string	はい	注文タイプ、下記の列挙を参照
stuff	object	はい	素材情報
stuff.pathKey	string	はい	リソースアドレス（HTTP リンクをサポート）

リクエスト例

トラック分離 (track-separation)

音声をボーカルと伴奏の2つのトラックに分離します。

{
  "orderType": "track-separation",
  "stuff": {
    "pathKey": "https://example.com/audio.mp3"
  }
}

ボーカル抽出 (extract-voice)

音声からボーカル部分を抽出します。

{
  "orderType": "extract-voice",
  "stuff": {
    "pathKey": "https://example.com/audio.mp3"
  }
}

伴奏抽出 (extract-music)

音声から伴奏/BGM部分を抽出します。

{
  "orderType": "extract-music",
  "stuff": {
    "pathKey": "https://example.com/audio.mp3"
  }
}

テキスト抽出 (extract-text)

動画または音声からテキスト内容を抽出します。

{
  "orderType": "extract-text",
  "stuff": {
    "pathKey": "https://example.com/video.mp4"
  }
}

レスポンス例

{
  "code": 0,
  "data": {
    "orderNo": "abc123XYZ789defGHI",
    "orderType": "track-separation",
    "orderStatus": "processing",
    "payStatus": "waiting",
    "messageId": "task-id-123"
  },
  "msg": "success"
}

レスポンスフィールド説明

フィールド	タイプ	説明
orderNo	string	注文番号、後のクエリに使用
orderType	string	注文タイプ
orderStatus	string	注文ステータス
payStatus	string	支払いステータス
messageId	string	タスクメッセージID

---

2. 注文クエリ (Query Order)

注文の処理状態と結果をクエリします。注文処理が完了すると、処理結果のダウンロードリンクが返されます。

注意: 注文完了後の初回クエリで自動的にクレジットが消費されます。

• URL: /api/open/v1/order/query
• Method: GET

リクエストパラメータ

パラメータ名	タイプ	必須	説明
orderNo	string	はい	注文番号

リクエスト例

GET /api/open/v1/order/query?orderNo=abc123XYZ789defGHI
Authorization: Bearer <your_api_key>

レスポンス例 (処理中)

{
  "code": 0,
  "data": {
    "orderNo": "abc123XYZ789defGHI",
    "orderType": "track-separation",
    "status": "processing",
    "cost": 0,
    "reason": null,
    "stuffs": [],
    "balance": 1000
  },
  "msg": "success"
}

レスポンス例 (処理完了)

{
  "code": 0,
  "data": {
    "orderNo": "abc123XYZ789defGHI",
    "orderType": "track-separation",
    "status": "finish",
    "cost": 10,
    "reason": null,
    "stuffs": [
      {
        "name": "vocals.mp3",
        "business": "vocals",
        "url": "https://cdn.example.com/result/vocals.mp3"
      },
      {
        "name": "accompaniment.mp3",
        "business": "accompaniment",
        "url": "https://cdn.example.com/result/accompaniment.mp3"
      }
    ],
    "balance": 990
  },
  "msg": "success"
}

レスポンスフィールド説明

フィールド	タイプ	説明
orderNo	string	注文番号
orderType	string	注文タイプ
status	string	注文ステータス
cost	number	消費クレジット
reason	string	失敗理由（失敗時のみ値あり）
stuffs	array	処理結果リスト
stuffs[].name	string	ファイル名
stuffs[].business	string	業務タイプ (vocals/accompaniment/caption等)
stuffs[].url	string	ダウンロードリンク（有効期限 1 時間）
balance	number	現在のユーザーの利用可能クレジット残高

---

3. ショート動画解析 (Short Video Analyze)

ショート動画の共有リンクをリアルタイムで解析し、動画情報と透かしなしのダウンロードアドレスを取得します。

注意: このインターフェースはリアルタイムインターフェースであり、即座にクレジットが差し引かれ、結果が返されます。

• URL: /api/open/v1/short-video/analyze
• Method: POST
• Content-Type: application/json

リクエストパラメータ

パラメータ名	タイプ	必須	説明
link	string	はい	ショート動画共有リンク

リクエスト例

{
  "link": "https://v.douyin.com/ixxxxxx/"
}

レスポンス例

{
  "code": 0,
  "data": {
    "title": "動画タイトル",
    "author": "作者ニックネーム",
    "cover": "https://cdn.example.com/cover.jpg",
    "videoUrl": "https://cdn.example.com/video.mp4",
    "musicUrl": "https://cdn.example.com/music.mp3",
    "balance": 990
  },
  "msg": "success"
}

レスポンスフィールド説明

フィールド	タイプ	説明
title	string	動画タイトル
author	string	作者ニックネーム
cover	string	カバー画像アドレス
videoUrl	string	透かしなし動画ダウンロードアドレス
musicUrl	string	背景音楽ダウンロードアドレス（ある場合）
balance	number	現在のユーザーの利用可能クレジット残高

---

エラーコード説明

エラーコード	説明
0	成功
400	リクエストパラメータエラー
401	認証失敗 (API Key 無効または欠落)
500	サーバー内部エラー

一般的なエラーメッセージ

エラーメッセージ	説明
API Key is required	API Key が必要です
Invalid API Key	API Key が無効です
pathKey is required	リソースアドレスが必要です
Order not found	注文が存在しないか、現在のユーザーに属していません
ErrorCode.USER_BLANCE_NOT_ENOUGH	クレジット残高不足

---

付録

OrderType (注文タイプ)

値	説明
track-separation	トラック分離（ボーカルと伴奏を分離）
extract-voice	ボーカル抽出
extract-music	伴奏抽出
extract-text	テキスト抽出

OrderStatus (注文ステータス)

値	説明
pending	待機中
processing	処理中
finish	完了
failed	失敗
timeout	タイムアウト

サポートされているショート動画プラットフォーム

• Douyin (抖音)
• Kuaishou (快手)
• Xiaohongshu (小紅書)
• Weibo (微博)
• その他主流のショート動画プラットフォーム