Grok 動画フォーマット（Video）¶

本文書では、New-API を介して xAI の Grok シリーズモデルを呼び出す方法について説明します。現在、動画生成がサポートされており、課金ロジックは動的パラメータを完全にサポートしています。

1. 全般的なリクエスト情報¶

ベース URL: https://api-cs-al.naci-tech.com/v1
認証方法: Authorization: Bearer $API_KEY ヘッダーを付与
コンテンツタイプ: Content-Type: application/json

metadata の透過転送について

New-API は、リクエストボディ内の metadata オブジェクトを**完全に透過的に転送**します。xAI がネイティブにサポートしているが、標準フィールドリストに記載されていない高度なパラメータ（seed、negative_prompt、aspect_ratio、fps など）は、metadata 内に直接含めて渡すことができます。

2. 動画生成モデル（grok-imagine-video）¶

テキストからの動画生成（Text-to-Video）、画像からの動画生成（Image-to-Video）、動画からの動画生成（Video-to-Video / Remix）などの機能をサポートしています。

透過転送（重要）

New-API は metadata オブジェクトを**完全に透過的に転送**します。多くの xAI ネイティブパラメータ（例：aspect_ratio、seed、fps）や、本文書内の「モード切り替え」フィールドの一部（例：resolution、video）は、metadata に含めることが推奨されます。

API エンドポイント¶

動画タスクの作成：POST /v1/video/generations

基本リクエストパラメータ¶

パラメータ名	型	必須	説明
`model`	string	はい	`grok-imagine-video` に固定
`prompt`	string	はい	動画内容のテキスト説明
`duration`	integer	いいえ	動画の長さ（秒）。テキスト/画像からの動画生成のみ有効で、範囲は 1–15、デフォルトは `5` です。動画編集（Remix）モードでは使用不可で、出力の長さは入力動画と同じになり、上限は 8.7 秒です。
`metadata`	object	いいえ	追加のメタデータ（透過転送オブジェクト）。下表のフィールドをサポートします。
`images`	array	いいえ	入力画像配列。Image-to-Video モードで使用します。
`image`	string	いいえ	単一の入力画像：公開 URL、または base64 データ URI（例：`data:image/jpeg;base64,...`）。`images` とのいずれか一方を指定してください。

Metadata フィールド¶

フィールド名	型	説明
`resolution`	string	出力解像度：`720p`（高画質）、`480p`（標準画質、デフォルト、処理が高速）。テキスト/画像からの動画生成のみ有効です。動画編集モードではサポートされておらず、出力解像度は入力動画と同じになり、上限は 720p です。
`aspect_ratio`	string	画面比率。テキスト/画像からの動画生成のみ有効です。選択肢：`1:1`、`16:9`（デフォルト）、`9:16`、`4:3`、`3:4`、`3:2`、`2:3`。Image-to-Video で指定しない場合は入力画像に従います。動画編集モードではサポートされておらず、出力は入力動画に従います。
`video`	string	入力動画 URL。このフィールドを指定すると Video-to-Video (Remix) モードがトリガーされます。

リクエスト例 1：テキスト + 画像から動画生成¶

curl -X POST https://api-cs-al.naci-tech.com/v1/video/generations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "雲の上にあるサイバーパンクな都市",
    "duration": 5,
    "image": "https://example.com/init_frame.png",
    "metadata": {
      "resolution": "720p"
    }
  }'

リクエスト例 2：動画から動画生成（Video-to-Video / Remix）¶

既存の動画をベースに描き直しや修正を行うには、metadata に video パラメータを渡します。

curl -X POST https://api-cs-al.naci-tech.com/v1/video/generations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "動画のスタイルをゴッホの油絵風に変更して",
    "metadata": {
      "video": "https://example.com/original_video.mp4"
    }
  }'

3. 動画タスクステータスの照会¶

送信に成功すると id（すなわち task_id）が返されます。以下のインターフェースを使用して、生成の進行状況と結果を照会できます。

GET /v1/videos/<id>
GET /v1/video/generations/<id>

照会例（curl）¶

例 1：`GET /v1/videos/<id>` による照会（OpenAI スタイル）¶

curl -X GET "https://api-cs-al.naci-tech.com/v1/videos/xai-task-12345" \
  -H "Authorization: Bearer $API_KEY"

例 2：`GET /v1/video/generations/<id>` による照会（agtcloud スタイル）¶

curl -X GET "https://api-cs-al.naci-tech.com/v1/video/generations/xai-task-12345" \
  -H "Authorization: Bearer $API_KEY"

返り値の説明（標準 OpenAI 動画フォーマット）¶

status: queued（待機中）、in_progress（生成中）、completed（成功）、failed（失敗）
progress: タスクの完了状況（0-100）
metadata.url: 生成完了後の動画への直リンクアドレス
error: タスク失敗時のエラー情報オブジェクト

典型的なレスポンス例¶

{
  "id": "xai-task-12345",
  "object": "video",
  "model": "grok-imagine-video",
  "status": "completed",
  "progress": 100,
  "created_at": 1718300000,
  "metadata": {
    "url": "https://api-cs-al.naci-tech.com/v1/videos/xai-task-12345/content"
  }
}

4. 動画ファイル内容の取得（プロキシ）¶

動画ファイルストリームを直接取得する必要がある場合（フロントエンドの <video> タグでの再生など）、以下のプロキシインターフェースを使用できます。

リクエストパス: GET /v1/videos/<id>/content

リクエスト例（curl）¶

curl -X GET "https://api-cs-al.naci-tech.com/v1/videos/xai-task-12345/content" \
  -H "Authorization: Bearer $API_KEY" \
  --output "output_video.mp4"

説明¶

このインターフェースは、アップストリームの動画ファイルのバイナリストリームを直接透過的に転送します。
正しい Content-Type（例：video/mp4）およびキャッシュ制御ヘッダーが含まれます。
権限: 同様に有効な Authorization トークンが必要です。

5. 課金ロジックの説明（透明化された課金）¶

New-API は、アップロードされたパラメータ（metadata で透過的に転送された一部のパラメータを含む）に基づいて、消費されるクレジットを動的に計算します。そのため、照合や再現のために、ビジネス側で metadata も併せて記録しておくことを推奨します。