> ## Documentation Index
> Fetch the complete documentation index at: https://docs.senseaudio.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 音效生成

> 根据文本描述同步生成 1-4 个音效变体

## 说明

根据文本描述同步生成 1-4 个音效变体，默认模型为 `senseaudio-sfx-1.0-260626`，完成媒体校验、文件上传和实际成功数量结算后返回结果。备注：单条消耗 100 积分，单次最多生成 4 条，合计消耗 400 积分。

<Info>
  至少一个变体成功时返回 HTTP 200，`status` 为 `completed` 或 `partial_success`；仅对成功变体计费。全部失败时返回业务错误并全额退款。
</Info>

<Warning>
  传入 `duration_seconds` 时会强制关闭 `smart_duration`，即使请求中 `smart_duration=true`。
</Warning>


## OpenAPI

````yaml api-reference/endpoint/sfx/sfx.openapi.json POST /v1/sound-effects/generations
openapi: 3.1.0
info:
  title: SenseAudio - Sound Effects
  version: 1.0.0
servers:
  - url: https://api.senseaudio.cn
    description: 生产环境
security:
  - bearerAuth: []
paths:
  /v1/sound-effects/generations:
    post:
      summary: 音效生成
      description: 根据文本描述同步生成 1-4 个音效变体，完成媒体校验、文件上传和实际成功数量结算后返回结果。
      operationId: soundEffectsCreateGeneration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - text
                - model
              properties:
                text:
                  type: string
                  description: 音效描述文本，去除首尾空白后不可为空。
                  maxLength: 2000
                model:
                  type: string
                  description: 已启用的音效模型 label。
                  default: senseaudio-sfx-1.0-260626
                  example: senseaudio-sfx-1.0-260626
                variants_count:
                  type: integer
                  description: 生成变体数量。备注：单条消耗 100 积分，单次最多生成 4 条，合计消耗 400 积分。
                  default: 4
                  minimum: 1
                  maximum: 4
                duration_seconds:
                  type: integer
                  description: 固定生成时长，单位秒；优先于 smart_duration。
                  minimum: 1
                  maximum: 10
                smart_duration:
                  type: boolean
                  description: 由模型根据提示词自动决定时长。
                  default: true
                prompt_influence:
                  type: number
                  description: 提示词影响权重；不传时使用模型默认值。
                  minimum: 0
                  maximum: 1
                output_format:
                  type: string
                  description: 输出音频格式。
                  default: mp3
                  enum:
                    - mp3
                    - wav
            example:
              text: 雨夜里木门被轻轻敲响三次
              model: senseaudio-sfx-1.0-260626
              variants_count: 2
              smart_duration: true
              prompt_influence: 0.7
              output_format: mp3
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  generation_id:
                    type: string
                    description: 本次同步生成批次 ID。
                  status:
                    type: string
                    description: 批次聚合状态。
                    enum:
                      - completed
                      - partial_success
                  items:
                    type: array
                    description: 按变体序号排列的生成结果。
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: 音效作品 ID。
                        name:
                          type: string
                          description: 音效名称。
                        variant_index:
                          type: integer
                          description: 变体序号，从 0 开始。
                        status:
                          type: string
                          description: 单个变体状态。
                          enum:
                            - completed
                            - failed
                        audio_file_id:
                          type: string
                          description: 成功变体对应的文件 ID。
                        audio_url:
                          type: string
                          description: 成功变体对应的音频 URL。
                        duration_seconds:
                          type: integer
                          description: 实际音频时长，单位秒。
                        output_format:
                          type: string
                          description: 实际输出格式。
                        fail_reason:
                          type: string
                          description: 失败原因，仅失败变体返回。
              example:
                generation_id: 02a2148ae11335c557441493bcdd8bcd-62a13d9385596b4c
                status: completed
                items:
                  - id: ae45b988-ab0a-4e72-ab55-24e966014f9d
                    name: 雨夜里木门被轻轻敲响三次 · 变体1
                    variant_index: 0
                    status: completed
                    audio_file_id: file-X7oNJQEki5CazZKQ76Uku6
                    audio_url: https://example.com/sfx-1.mp3
                    duration_seconds: 3
                    output_format: mp3
                    fail_reason: ''
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API_KEY
      description: 格式：`Bearer <API_KEY>`

````