fix(video): Atlas image-to-video must select the image-to-video model

Follow-up to #13. Atlas Cloud exposes image-to-video as its own model id
(bytedance/seedance-2.0/image-to-video), and the text-to-video model's
published schema has no `image` field — so the previous default (always
text-to-video, image attached anyway) made the default-config
image-to-video path ship a video that ignores the first frame, or get
rejected, without any error naming the cause. GENERATE's
character-consistency flow (locked portrait -> i2v) rides exactly that
path.

- Default the model by task type: image_url present -> the i2v model id,
  absent -> text-to-video, explicit model/config always wins.
- Fail closed on an explicit mismatch, naming the fix in the error: a
  text-to-video model given a first frame would silently produce a
  wrong delivery, and an image-to-video model without a frame cannot
  run at all.

Verified: build green; 218 tests pass — the prior test that pinned the
broken combination (image + t2v default) now pins the i2v default, plus
new cases for the no-image default and both mismatch refusals. Model
ids and the schema difference confirmed against the Atlas model pages.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VL7mRpmEphLAbcH7YmABnV

Author: leochenpm

packages/tools/src/video/video.ts

@@ -7,6 +7,10 @@ const ARK_DEFAULT_BASE = 'https://ark.cn-beijing.volces.com/api/v3';
 const DEFAULT_MODEL = 'doubao-seedance-2-0-260128';
 const ATLAS_DEFAULT_BASE = 'https://api.atlascloud.ai/api/v1';
 const ATLAS_DEFAULT_MODEL = 'bytedance/seedance-2.0/text-to-video';
+// Atlas exposes image-to-video as its OWN model id, and the text-to-video
+// model's schema has no `image` field — a first frame sent to it is ignored
+// or rejected, never used.
+const ATLAS_DEFAULT_I2V_MODEL = 'bytedance/seedance-2.0/image-to-video';
 const POLL_INTERVAL_MS = 10_000;
 const POLL_TIMEOUT_MS = 30_000; // per-poll request timeout — one slow poll must not fail the task
 const TASK_TIMEOUT_MS = 60 * 60 * 1000;
@@ -57,11 +61,21 @@ export function buildAtlasCreateRequest(cfg: VideoProviderConfig, p: VideoParams
   if (!Number.isFinite(duration) || duration < 4 || duration > 15) {
     throw new Error('video: duration must be between 4 and 15 seconds');
   }
+  // Default the model by task type, and fail closed on an explicit mismatch:
+  // a text-to-video model given a first frame would silently produce a video
+  // that ignores the image, which is a wrong delivery, not an error.
+  const model = p.model ?? cfg.model ?? (p.image_url ? ATLAS_DEFAULT_I2V_MODEL : ATLAS_DEFAULT_MODEL);
+  if (p.image_url && /text-to-video/i.test(model)) {
+    throw new Error(`video: model "${model}" is text-to-video and has no image input; use an image-to-video model (e.g. ${ATLAS_DEFAULT_I2V_MODEL}) for a first-frame image_url`);
+  }
+  if (!p.image_url && /image-to-video/i.test(model)) {
+    throw new Error(`video: model "${model}" requires a first-frame image_url; pass one, or use a text-to-video model (e.g. ${ATLAS_DEFAULT_MODEL})`);
+  }
   return {
     url: `${atlasBase(cfg)}/model/generateVideo`,
     headers: { authorization: `Bearer ${cfg.api_key}`, 'content-type': 'application/json' },
     body: {
-      model: p.model ?? cfg.model ?? ATLAS_DEFAULT_MODEL,
+      model,
       prompt: p.prompt,
       duration,
       resolution: p.resolution ?? '720p',

packages/tools/test/gen.test.ts

@@ -324,15 +324,17 @@ describe('generateVideo (Doubao Seedance task + poll)', () => {
 });
 
 describe('generateVideo (Atlas Cloud task + poll)', () => {
-  it('builds the Atlas Cloud media request', () => {
+  it('defaults the model by task type: image-to-video when a first frame is passed', () => {
     const req = buildAtlasCreateRequest(
       { provider: 'atlas', api_key: 'atlas-key' },
       { prompt: 'a sunrise', output: 'out.mp4', image_url: 'https://example.com/first.png' },
     );
     expect(req.url).toBe('https://api.atlascloud.ai/api/v1/model/generateVideo');
     expect(req.headers.authorization).toBe('Bearer atlas-key');
     expect(req.body).toMatchObject({
-      model: 'bytedance/seedance-2.0/text-to-video',
+      // The text-to-video model's schema has no `image` field — a first frame
+      // must select the image-to-video model, or it is silently ignored.
+      model: 'bytedance/seedance-2.0/image-to-video',
       prompt: 'a sunrise',
       image: 'https://example.com/first.png',
       duration: 5,
@@ -341,6 +343,26 @@ describe('generateVideo (Atlas Cloud task + poll)', () => {
     });
   });
 
+  it('defaults to text-to-video without a first frame', () => {
+    const req = buildAtlasCreateRequest(
+      { provider: 'atlas', api_key: 'atlas-key' },
+      { prompt: 'a sunrise', output: 'out.mp4' },
+    );
+    expect(req.body).toMatchObject({ model: 'bytedance/seedance-2.0/text-to-video' });
+    expect(req.body).not.toHaveProperty('image');
+  });
+
+  it('fails closed on an explicit model/task mismatch instead of shipping the wrong video', () => {
+    expect(() => buildAtlasCreateRequest(
+      { provider: 'atlas', api_key: 'atlas-key', model: 'bytedance/seedance-2.0/text-to-video' },
+      { prompt: 'a sunrise', output: 'out.mp4', image_url: 'https://example.com/first.png' },
+    )).toThrow(/image-to-video/);
+    expect(() => buildAtlasCreateRequest(
+      { provider: 'atlas', api_key: 'atlas-key', model: 'bytedance/seedance-2.0/image-to-video' },
+      { prompt: 'a sunrise', output: 'out.mp4' },
+    )).toThrow(/requires a first-frame image_url/);
+  });
+
   it('creates, polls, and downloads an Atlas Cloud result', async () => {
     const srv = await startServer((req, res) => {
       const url = req.url ?? '';