yikart/AiToEarn · error · BadRequestException

reference_audio requires at least one reference image or ref

Error message

reference_audio requires at least one reference image or reference video

What it means

Reference audio on Volcengine only works as part of a reference-based generation that also includes at least one reference image or reference video. validateContent throws this BadRequestException when reference_audio items exist but no reference image and no reference video are present.

Source

Thrown at project/aitoearn-backend/apps/aitoearn-ai/src/core/ai/video/volcengine/volcengine.service.ts:179

    if (firstFrameImages.length > 1) {
      throw new BadRequestException('Only one first frame image is allowed')
    }

    if (lastFrameImages.length > 1) {
      throw new BadRequestException('Only one last frame image is allowed')
    }

    if (lastFrameImages.length > 0 && firstFrameImages.length === 0) {
      throw new BadRequestException('last_frame requires first_frame')
    }

    if (hasFrameScene && hasReferenceScene) {
      throw new BadRequestException('first_frame/last_frame and reference media cannot be mixed')
    }

    if (referenceAudios.length > 0 && referenceImages.length === 0 && referenceVideos.length === 0) {
      throw new BadRequestException('reference_audio requires at least one reference image or reference video')
    }
  }

  private normalizeRequest(request: UserVolcengineGenerationRequestDto) {
    let prompt = ''
    let inlineResolution: string | undefined
    let inlineRatio: string | undefined
    let inlineDuration: number | undefined
    let inlineSeed: number | undefined
    let inlineWatermark: boolean | undefined

    const normalizedContent = request.content.map((item) => {
      if (item.type !== ContentType.Text) {
        return item
      }

      const parsed = parseModelTextCommand(item.text)
      if (!prompt && parsed.prompt) {

View on GitHub (pinned to d3aa8bea5b)

Solutions

1. Add at least one reference_image or reference_video content item alongside the audio
2. Remove the reference_audio if audio-driven generation is not intended
3. Check the current Volcengine model capabilities — standalone audio input is not accepted

Example fix

// before
content: [{ type:'audio_url', role:'reference_audio', url: wav }]
// after
content: [{ type:'image_url', role:'reference_image', url: img }, { type:'audio_url', role:'reference_audio', url: wav }]

const hasAudio = content.some(c => c.role === 'reference_audio'); const hasVisualRef = content.some(c => c.role === 'reference_image' || c.role === 'reference_video'); if (hasAudio && !hasVisualRef) throw new Error('reference_audio requires a reference image or video')

const audioHasVisualRef = (c: Content[]) => !c.some(i => i.role === 'reference_audio') || c.some(i => i.role === 'reference_image' || i.role === 'reference_video')

try { await generate(req) } catch (e) { if (e instanceof BadRequestException && e.message.includes('reference_audio')) { /* attach a reference image/video or drop the audio */ } else throw e }

When it happens

Trigger: Content array containing only reference_audio items (with other frame-scene items absent), i.e. audio without any visual reference.

Common situations: Client sends a voice/ narration clip expecting audio-driven video; UI uploads audio alone; code assumed standalone audio-to-video was supported.

Related errors

• Only one first frame image is allowed
• Only one last frame image is allowed
• last_frame requires first_frame
• image_tail requires a single first frame image
• content is required

AI-assisted analysis of yikart/AiToEarn@d3aa8bea5b (2026-08-31). Data as JSON: /api/errors/c7bfeb9c8845a67a. Report an issue: GitHub.