fix(media): send image_urls to Fal Seedream edit endpoints

Author: ergs0204Created Sep 13, 2026Updated Sep 17, 2026
Labelsbuggood first issuehelp wanted

Summary

Fal image-to-image requests fail for fal-ai/bytedance/seedream/v4/edit because Open Design sends the reference image as singular image_url. The Seedream edit endpoint requires an image_urls array.

Environment

  • Open Design packaged app on Windows x64
  • Provider: Fal.ai (BYOK)
  • Model endpoint: fal-ai/bytedance/seedream/v4/edit
  • Invocation path: media generate

Steps to reproduce

  1. Configure a working Fal.ai API key in Open Design.
  2. Put a reference image in the project directory.
  3. Run:
& $env:OD_NODE_BIN $env:OD_BIN media generate `
  --surface image `
  --model 'fal-ai/bytedance/seedream/v4/edit' `
  --prompt 'Create a refined variation of this reference image.' `
  --image 'reference.jpg' `
  --output 'seedream-edit.png' `
  --workspace $env:OD_WORKSPACE_ID `
  --workspace-member $env:OD_WORKSPACE_MEMBER_ID
  1. Fal accepts the queued request, but the generation fails with HTTP 422 because image_urls is missing.

Current behavior

On current main, renderFalImage() uses one request shape for arbitrary Fal image endpoints:

if (ctx.imageRef?.dataUrl) {
  input.image_url = ctx.imageRef.dataUrl;
}

This produces a payload shaped like:

{
  "prompt": "...",
  "image_url": "data:image/jpeg;base64,..."
}

That shape works for Fal models that accept singular image_url, but Seedream's edit endpoint rejects it.

Expected behavior

Open Design should send Seedream edit references using the endpoint's required array field:

{
  "prompt": "...",
  "image_urls": ["data:image/jpeg;base64,..."]
}

Multiple project references should map to the same array when supplied through --image / --images.

Suggested implementation

  • Add endpoint-specific Fal input mapping rather than changing every Fal model globally.
  • For fal-ai/bytedance/seedream/v4/edit, populate image_urls from ctx.imageRefs.
  • Preserve singular image_url for endpoints whose schema requires it.
  • Add a regression test that captures the Fal submit body and asserts the Seedream endpoint receives image_urls without image_url.
  • Keep the existing project-path validation and reference-image resolution behavior.

Impact

This blocks Seedream reference-image editing through the otherwise supported arbitrary fal-ai/* model path. Text-to-image generation through Fal continues to work.

Related work

  • #1606 added the generic Fal renderer and arbitrary fal-ai/* endpoint support.
  • #3322 discussed broader reference-based remix UX but did not cover this provider payload bug.
  • #5315 concerned Seedream through Volcengine rather than Fal.

Would you be willing to contribute a PR?

Yes.