yikart/AiToEarn · error · BadRequestException

Only one first frame image is allowed

Error message

Only one first frame image is allowed

What it means

Volcengine first-frame/last-frame (first_frame) video generation accepts at most one first frame image. validateContent counts image contents with the first-frame role and throws this BadRequestException when more than one is supplied.

Source

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

    if (content.length === 0) {
      throw new BadRequestException('content is required')
    }

    const imageContents = content.filter((item): item is Extract<Content, { type: ContentType.ImageUrl }> => item.type === ContentType.ImageUrl)
    const videoContents = content.filter((item): item is Extract<Content, { type: ContentType.VideoUrl }> => item.type === ContentType.VideoUrl)
    const audioContents = content.filter((item): item is Extract<Content, { type: ContentType.AudioUrl }> => item.type === ContentType.AudioUrl)

    const firstFrameImages = imageContents.filter(item => !item.role || item.role === ImageRole.FirstFrame)
    const lastFrameImages = imageContents.filter(item => item.role === ImageRole.LastFrame)
    const referenceImages = imageContents.filter(item => item.role === ImageRole.ReferenceImage)
    const referenceVideos = videoContents.filter(item => item.role === VideoRole.ReferenceVideo)
    const referenceAudios = audioContents.filter(item => item.role === AudioRole.ReferenceAudio)

    const hasFrameScene = firstFrameImages.length > 0 || lastFrameImages.length > 0
    const hasReferenceScene = referenceImages.length > 0 || referenceVideos.length > 0 || referenceAudios.length > 0

    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')
    }
  }

View on GitHub (pinned to d3aa8bea5b)

Solutions

1. Keep exactly one first-frame image content item
2. Move extra images to reference roles or remove them
3. Validate/deduplicate first-frame images client-side before sending

Example fix

// before
content: [{ type:'image_url', role:'first_frame', url: a }, { type:'image_url', role:'first_frame', url: b }]
// after
content: [{ type:'image_url', role:'first_frame', url: a }]

const firstFrames = content.filter(c => c.type === 'image_url' && c.role === 'first_frame'); if (firstFrames.length > 1) throw new Error('Only one first frame image is allowed')

const isSingleFirstFrame = (c: Content[]) => c.filter(i => i.type === ContentType.ImageUrl && i.role === 'first_frame').length <= 1

try { await generate(req) } catch (e) { if (e instanceof BadRequestException && e.message.includes('first frame')) { /* dedupe first-frame images and retry once */ } else throw e }

When it happens

Trigger: Passing 2+ content items of type ImageUrl with the first-frame role in the content array of a Volcengine generation request.

Common situations: Client UI letting users pick multiple start frames; bulk-upload code mapping an image list to first-frame roles; copy-paste duplicating a frame entry.

Related errors

• Only one last frame image is allowed
• last_frame requires first_frame
• reference_audio requires at least one reference image or ref
• 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/0d21e27074c6ad6a. Report an issue: GitHub.