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

> ## Agent Instructions
> Send API requests to https://api.ttapi.io with the TT-API-KEY header. Midjourney account hosting uses https://hold.ttapi.io. Claude Code uses https://cc.ttapi.io.
> Most generation endpoints are asynchronous. The submit response returns a job id. Poll that product's fetch endpoint, or pass a webhook on the submit request. A fetch call does not start a new generation.
> 1 USD = 100 quota. Check the pricing page for that product before estimating cost.
> This file lists the English docs. Follow every /_llms/ link recursively for the API reference, Chinese, and Russian. Open a page's .md URL for the endpoint schema.

# Suno 视频任务查询 API

> 查询 Suno 视频任务状态，获取生成结果和失败信息。

使用[视频生成](https://docs.ttapi.io/api/cn/suno/suno_video_generate.md)或[视频延伸](https://docs.ttapi.io/api/cn/suno/suno_video_extend.md)返回的 `data.jobId` 查询任务结果。


## OpenAPI

````yaml openapi/cn/suno-video-fetch.json GET /suno/v2/fetch
openapi: 3.1.0
info:
  title: TTAPI Suno 视频查询
  version: 1.0.0
  description: 查询已提交的 Suno 视频任务。
servers:
  - url: https://api.ttapi.io
security: []
paths:
  /suno/v2/fetch:
    get:
      summary: 查询视频任务
      description: 查询已提交的 Suno 视频任务。API 密钥须具备 Suno Video 权限，任务须属于当前用户。
      parameters:
        - name: jobId
          in: query
          required: false
          schema:
            type: string
          description: 提交接口返回的 data.jobId
          example: video-9c64b7e1-f00d-456e-8c56-a0227f5128fb
      responses:
        '200':
          description: 查询成功。视频任务进度和结果由响应中的 status 表示。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SunoVideoFetchResult'
              examples:
                video_success:
                  summary: 视频任务成功
                  value:
                    status: SUCCESS
                    message: success
                    jobId: video-9c64b7e1-f00d-456e-8c56-a0227f5128fb
                    data:
                      quota: '75.00000000'
                      request_body:
                        prompt: 纸灯笼缓缓升入星空，镜头随灯笼向上移动。
                        duration: 5
                        resolution: 480p
                        aspect_ratio: '9:16'
                      videos:
                        - creation_id: crt_0187b131-a1c0-7151-a92e-cd8645e4bb01
                          status: succeeded
                          video_url: https://cdn.ttapi.io/suno/example-1.mp4
                          asset:
                            poster_url: https://example.com/poster-1.jpg
                            thumbnail_url: https://example.com/thumbnail-1.jpg
                            last_frame_url: https://example.com/last-frame-1.jpg
                            width: 480
                            height: 854
                            duration_s: 5.167
                            content_type: video/mp4
                            status: ready
                          error: null
                          error_code: null
                        - creation_id: crt_0187b131-a1c0-7151-a92e-cd8645e4bb02
                          status: succeeded
                          video_url: https://cdn.ttapi.io/suno/example-2.mp4
                          asset:
                            poster_url: https://example.com/poster-2.jpg
                            thumbnail_url: https://example.com/thumbnail-2.jpg
                            last_frame_url: https://example.com/last-frame-2.jpg
                            width: 480
                            height: 854
                            duration_s: 5.167
                            content_type: video/mp4
                            status: ready
                          error: null
                          error_code: null
                video_queued:
                  summary: 视频任务处理中
                  value:
                    status: ON_QUEUE
                    message: null
                    jobId: video-9c64b7e1-f00d-456e-8c56-a0227f5128fb
                    data:
                      quota: '75.00000000'
                      request_body:
                        prompt: 纸灯笼缓缓升入星空，镜头随灯笼向上移动。
                        duration: 5
                        resolution: 480p
                        aspect_ratio: '9:16'
                      videos: []
                video_failed:
                  summary: 视频任务失败
                  value:
                    status: FAILED
                    message: nudity_sexual
                    jobId: video-9c64b7e1-f00d-456e-8c56-a0227f5128fb
                    data:
                      quota: '0'
                      request_body:
                        prompt: 纸灯笼缓缓升入星空，镜头随灯笼向上移动。
                        duration: 5
                        resolution: 480p
                        aspect_ratio: '9:16'
                      videos:
                        - creation_id: crt_0187b131-a1c0-7151-a92e-cd8645e4bb01
                          status: failed
                          video_url: null
                          asset: null
                          error: nudity_sexual
                          error_code: moderated
                          moderation_reason: nudity_sexual
                        - creation_id: crt_0187b131-a1c0-7151-a92e-cd8645e4bb02
                          status: failed
                          video_url: null
                          asset: null
                          error: nudity_sexual
                          error_code: moderated
                          moderation_reason: nudity_sexual
        '400':
          $ref: '#/components/responses/400Response'
        '401':
          $ref: '#/components/responses/401Response'
        '403':
          description: API 密钥缺少对应产品权限，或请求不符合账号访问限制。
      security:
        - CustomApiKey: []
components:
  schemas:
    SunoVideoFetchResult:
      title: 视频任务结果
      type: object
      required:
        - status
        - message
        - jobId
        - data
      properties:
        status:
          type: string
          enum:
            - ON_QUEUE
            - SUCCESS
            - FAILED
        message:
          type:
            - string
            - 'null'
          description: 任务提示。生成失败时可返回首条失败视频的上游错误。
        jobId:
          type: string
          description: 提交接口返回的 data.jobId。
        data:
          type: object
          required:
            - quota
            - request_body
            - videos
          properties:
            quota:
              type: string
              description: 任务消耗配额。
            request_body:
              description: 请求参数信息
              allOf:
                - $ref: '#/components/schemas/SunoVideoGenerateRequest'
                - type: object
                  required:
                    - resolution
                    - model
                    - aspect_ratio
            videos:
              type: array
              maxItems: 2
              items:
                $ref: '#/components/schemas/SunoVideoTake'
              description: 生成视频集合
    SunoVideoGenerateRequest:
      title: 视频生成参数
      type: object
      required:
        - prompt
        - duration
      properties:
        prompt:
          type: string
          description: 描述画面、镜头运动和风格。
          minLength: 1
          maxLength: 30000
        duration:
          type: integer
          minimum: 5
          maximum: 15
          description: 生成时长，单位为秒。
        resolution:
          type:
            - string
            - 'null'
          description: 输出分辨率。480p 对应 fast，720p 对应 standard。
          enum:
            - 480p
            - 720p
          default: 480p
        aspect_ratio:
          type:
            - string
            - 'null'
          description: 画面宽高比
          enum:
            - '1:1'
            - '9:16'
            - '16:9'
            - '4:3'
            - '3:4'
          default: '9:16'
        first_frame_url:
          type: string
          description: 首帧图的公网 HTTP(S) URL。可单独使用、与尾帧组合或与参考图组合。
          format: uri
        last_frame_url:
          type: string
          description: 尾帧图的公网 HTTP(S) URL。需要同时传首帧；首尾帧组合不支持参考图。
          format: uri
        reference_image_urls:
          type: array
          maxItems: 9
          items:
            type: string
            description: 参考图的公网 HTTP(S) URL。
            format: uri
          description: 最多 9 张，可单独使用或与首帧组合。
        song_id:
          type: string
          description: 参考音频的 Suno 歌曲 ID，可与图片输入组合。
        song_window:
          type: object
          description: 参考音频区间，使用时须传 song_id。省略时使用从第 0 秒起、长度与视频相同的片段。
          properties:
            start_s:
              type: number
              minimum: 0
              default: 0
              description: 起始时间，单位为秒，可为小数。
            end_s:
              type: number
              minimum: 0
              description: 结束时间，单位为秒。省略时取 start_s + duration，显式填写时区间长度须等于 duration。
        lip_sync:
          type: boolean
          default: false
          description: 开启口型同步。设为 true 时须传 song_id。
        hookUrl:
          type: string
          format: uri
          description: 可选的 Webhook 回调地址。任务结束后通过 HTTP POST 发送，正文与视频任务 Fetch V2 响应一致。
    SunoVideoTake:
      type: object
      required:
        - creation_id
        - status
        - video_url
        - asset
        - error
        - error_code
      properties:
        creation_id:
          type: string
          description: 视频ID
        status:
          type: string
          description: 单条结果状态，例如 pending、succeeded 或 failed。
        video_url:
          type:
            - string
            - 'null'
          description: 任务成功后返回可播放的 MP4 地址。
          format: uri
        asset:
          type:
            - object
            - 'null'
          description: 素材元数据，尚未取得素材时为 null。
          properties:
            poster_url:
              type: string
              description: 封面图 URL。
              format: uri
            thumbnail_url:
              type: string
              description: 缩略图 URL。
              format: uri
            last_frame_url:
              type: string
              description: 末帧图 URL。
              format: uri
            width:
              type: integer
              description: 宽度，单位为像素。
            height:
              type: integer
              description: 高度，单位为像素。
            duration_s:
              type: number
              description: 视频实际时长，单位为秒。
            content_type:
              type: string
              description: 媒体类型，例如 video/mp4。
            status:
              type: string
              description: 素材状态，例如 ready。
        error:
          type:
            - string
            - 'null'
          description: 错误信息
        error_code:
          type:
            - string
            - 'null'
          description: 错误代码
        moderation_reason:
          type: string
          description: 审核未通过原因
  responses:
    400Response:
      description: 参数错误
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                example: FAILED
              message:
                type: string
              data:
                type: object
            required:
              - status
              - message
    401Response:
      description: 授权失败
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                example: FAILED
              message:
                type: string
                example: Wrong TT-API-KEY or email is not activated.
            required:
              - status
              - message
  securitySchemes:
    CustomApiKey:
      type: apiKey
      in: header
      name: TT-API-KEY
      description: >-
        请前往 <a href='https://dashboard.ttapi.io' target='_blank'>TTAPI 控制台</a>
        获取 API 密钥。

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.