# 動画生成タスクを送信

**API:** Model API

**Endpoint:** `POST /api/v1/videos/generations`

OpenRouter 形式のフラットな動画入力です。Felo のモデル ID、チャンネル、タスク ID、レスポンスの形式は変わりません。旧来の input ラッパーとプロバイダー固有のフィールドは拒否されます。コールバック、続きの生成、プロバイダーオプション、動画のアップスケールには対応していません。モデルやチャンネルの機能によって、これらのパラメータがさらに制限される場合があります。HTTP 202 と Felo の task_id を返します。GET /api/v1/videos/generations/{task_id} をポーリングしてください。サポートされていないフィールドは HTTP 400 を返します。

## Base URL

- `https://openapi.felo.ai` — 本番環境

## Authentication

- `FeloBearerAuth` (http bearer) — Felo APIキーを `Authorization: Bearer <key>` として送信します。
- `FeloApiKey` (apiKey in header `X-API-Key`) — Felo APIキーを `X-API-Key: <key>` として送信します。

## Parameters

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `X-Request-Id` | header | no | string | 任意の呼び出し元リクエスト ID。診断用にそのまま返されます。 |
| `X-Felo-Channel` | header | no | string, default: "default" | カンマ区切りの公開チャンネルコード（順序どおり）。このヘッダーを省略すると default が使われ、default は単独でのみ使用できます。ウォレットモードでは、default はモデルの有効な公開チャンネル順を逆から走査し、未公開または利用不可のチャンネルをスキップして、最初に利用可能なチャンネルのプロバイダーを選択します。そのプロバイダーから、同じ上流モデル ID とサービスティアを持つ利用可能なエンドポイントを含めます。明示的なチャンネルはクライアントが指定した順序で検証され、最初のチャンネルのプロバイダーグループのみが送信されます。他のプロバイダーへの自動フォールバックはありません。従来のプロバイダーヘッダーでチャンネルルーティングを上書きすることはできません。 |

## Request body

Required: **yes**

### application/json

Schema: `VideoGenerationRequest` (`#/components/schemas/VideoGenerationRequest`)

```json
{
  "type": "object",
  "required": [
    "model"
  ],
  "additionalProperties": false,
  "description": "OpenRouter 形式のフラットな動画入力です。Felo のモデル ID、チャンネル、タスク ID、レスポンスの形式は変わりません。旧来の input ラッパーとプロバイダー固有のフィールドは拒否されます。コールバック、続きの生成、プロバイダーオプション、動画のアップスケールには対応していません。モデルやチャンネルの機能によって、これらのパラメータがさらに制限される場合があります。",
  "properties": {
    "model": {
      "type": "string",
      "minLength": 1,
      "pattern": "\\S"
    },
    "prompt": {
      "type": "string"
    },
    "duration": {
      "type": "integer",
      "minimum": 1
    },
    "resolution": {
      "type": "string",
      "enum": [
        "360p",
        "480p",
        "720p",
        "768p",
        "1080p",
        "1K",
        "2K",
        "4K"
      ]
    },
    "aspect_ratio": {
      "type": "string",
      "enum": [
        "16:9",
        "9:16",
        "1:1",
        "4:3",
        "3:4",
        "3:2",
        "2:3",
        "21:9",
        "9:21"
      ]
    },
    "generate_audio": {
      "type": "boolean"
    },
    "character_orientation": {
      "type": "string",
      "enum": [
        "image",
        "video"
      ],
      "description": "Required by supported Kling motion-control models: orientation source."
    },
    "seed": {
      "type": "integer"
    },
    "size": {
      "type": "string",
      "pattern": "^[1-9][0-9]*x[1-9][0-9]*$"
    },
    "frame_images": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "image_url"
            ]
          },
          "image_url": {
            "type": "object",
            "additionalProperties": false,
            "oneOf": [
              {
                "required": [
                  "url"
                ]
              },
              {
                "required": [
                  "file_id"
                ]
              }
            ],
            "properties": {
              "url": {
                "type": "string",
                "minLength": 1,
                "pattern": "\\S",
                "not": {
                  "pattern": "^\\s*felo_file_"
                }
              },
              "file_id": {
                "type": "string",
                "maxLength": 80,
                "pattern": "^felo_file_[A-Za-z0-9_-]{1,70}$",
                "description": "Uploaded Felo file owned by the authenticated user."
              }
            }
          },
          "frame_type": {
            "type": "string",
            "enum": [
              "first_frame",
              "last_frame"
            ]
          }
        },
        "required": [
          "type",
          "image_url",
          "frame_type"
        ]
      }
    },
    "input_references": {
      "type": "array",
      "items": {
        "oneOf": [
          {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "image_url"
                ]
              },
              "image_url": {
                "type": "object",
                "additionalProperties": false,
                "oneOf": [
                  {
                    "required": [
                      "url"
                    ]
                  },
                  {
                    "required": [
                      "file_id"
                    ]
                  }
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "minLength": 1,
                    "pattern": "\\S",
                    "not": {
                      "pattern": "^\\s*felo_file_"
                    }
                  },
                  "file_id": {
                    "type": "string",
                    "maxLength": 80,
                    "pattern": "^felo_file_[A-Za-z0-9_-]{1,70}$",
                    "description": "Uploaded Felo file owned by the authenticated user."
                  }
                }
              }
            },
            "required": [
              "type",
              "image_url"
            ]
          },
          {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "video_url"
                ]
              },
              "video_url": {
                "type": "object",
                "additionalProperties": false,
                "oneOf": [
                  {
                    "required": [
                      "url"
                    ]
                  },
                  {
                    "required": [
                      "file_id"
                    ]
                  }
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "minLength": 1,
                    "pattern": "\\S",
                    "not": {
                      "pattern": "^\\s*felo_file_"
                    }
                  },
                  "file_id": {
                    "type": "string",
                    "maxLength": 80,
                    "pattern": "^felo_file_[A-Za-z0-9_-]{1,70}$",
                    "description": "Uploaded Felo file owned by the authenticated user."
                  }
                }
              }
            },
            "required": [
              "type",
              "video_url"
            ]
          },
          {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "audio_url"
                ]
              },
              "audio_url": {
                "type": "object",
                "additionalProperties": false,
                "oneOf": [
                  {
                    "required": [
                      "url"
                    ]
                  },
                  {
                    "required": [
                      "file_id"
                    ]
                  }
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "minLength": 1,
                    "pattern": "\\S",
                    "not": {
                      "pattern": "^\\s*felo_file_"
                    }
                  },
                  "file_id": {
                    "type": "string",
                    "maxLength": 80,
                    "pattern": "^felo_file_[A-Za-z0-9_-]{1,70}$",
                    "description": "Uploaded Felo file owned by the authenticated user."
                  }
                }
              }
            },
            "required": [
              "type",
              "audio_url"
            ]
          }
        ]
      }
    },
    "user": {
      "type": "string",
      "maxLength": 256
    },
    "session_id": {
      "type": "string",
      "maxLength": 256
    },
    "trace": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "trace_id": {
          "type": "string"
        },
        "trace_name": {
          "type": "string"
        },
        "span_name": {
          "type": "string"
        },
        "generation_name": {
          "type": "string"
        },
        "parent_span_id": {
          "type": "string"
        }
      }
    },
    "provider": {
      "type": "object",
      "required": [
        "options"
      ],
      "additionalProperties": false,
      "properties": {
        "options": {
          "type": "object",
          "minProperties": 1,
          "maxProperties": 1,
          "additionalProperties": {
            "type": "object"
          },
          "description": "Options keyed by the slug published in the model catalog provider_options."
        }
      }
    }
  }
}
```

Example:

```json
{
  "model": "veo-3.1-lite",
  "prompt": "A cinematic camera move",
  "duration": 4,
  "resolution": "720p",
  "generate_audio": false,
  "frame_images": [
    {
      "type": "image_url",
      "frame_type": "first_frame",
      "image_url": {
        "url": "https://example.com/first.png"
      }
    }
  ]
}
```

## Responses

### 202 — タスクを受け付けました

**application/json**

Schema: `VideoGenerationAccepted` (`#/components/schemas/VideoGenerationAccepted`)

### 400 — 無効なリクエスト（不明なモデル、入力モードの混在、無効なフィールド）

**application/json**

Schema: `GenerationError` (`#/components/schemas/GenerationError`)

### 401 — Felo APIキーが無効または未指定です

**application/json**

Schema: `GenerationError` (`#/components/schemas/GenerationError`)

### 402 — 残高不足、または請求要件を満たしていません

**application/json**

Schema: `GenerationError` (`#/components/schemas/GenerationError`)

### 403 — アカウントに権限がありません（サブスクリプションが必要、またはユーザーが禁止されています）。無効化されたモデルも上流呼び出しの前に拒否されます。既に受け付けたリクエストとタスクは継続します。

**application/json**

Schema: `GenerationError` (`#/components/schemas/GenerationError`)

### 429 — リクエスト数または支出上限に達しました

**application/json**

Schema: `GenerationError` (`#/components/schemas/GenerationError`)

### 502 — 上流プロバイダーでエラーが発生しました

**application/json**

Schema: `GenerationError` (`#/components/schemas/GenerationError`)

### 503 — 生成サービスまたは請求サービスが一時的に利用できません

**application/json**

Schema: `GenerationError` (`#/components/schemas/GenerationError`)

## Schema definitions

### GenerationError

`#/components/schemas/GenerationError`

```json
{
  "type": "object",
  "description": "OpenAI 互換のエラーエンベロープ。",
  "properties": {
    "error": {
      "type": "object",
      "required": [
        "message",
        "type"
      ],
      "properties": {
        "message": {
          "type": "string"
        },
        "type": {
          "type": "string",
          "enum": [
            "invalid_request_error",
            "server_error"
          ]
        },
        "param": {
          "type": "string",
          "nullable": true
        },
        "code": {
          "type": "string"
        }
      }
    }
  }
}
```

### VideoGenerationAccepted

`#/components/schemas/VideoGenerationAccepted`

```json
{
  "type": "object",
  "required": [
    "task_id",
    "status",
    "kind",
    "outputs"
  ],
  "properties": {
    "task_id": {
      "type": "string",
      "description": "ポーリングに使用するタスク ID。"
    },
    "status": {
      "type": "string",
      "enum": [
        "queued"
      ]
    },
    "kind": {
      "type": "string",
      "enum": [
        "video"
      ]
    },
    "outputs": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "タスクが成功するまでは空です。"
    }
  }
}
```
