text-to-video

# text-to-video

A Hybrid Gene that turns a text prompt into an OpenAI video generation job and can poll that job until completion.

## Environment

- `ROTIFER_OPENAI_API_KEY` or `OPENAI_API_KEY`: required
- `ROTIFER_OPENAI_BASE_URL`: optional, defaults to `https://api.openai.com/v1`

On macOS, Rotifer can auto-load the OpenAI key from Keychain after you store it with:

```bash
rotifer secret set-openai
```

## Features

- Create text-to-video jobs with `sora-2` or `sora-2-pro`
- Preview the optimized prompt with `operation: "prepare"`
- Optional image/file reference input
- Poll job status until `completed` or `failed`
- Auto-infer a prompt profile from the user's text and inject continuity / negative constraints
- Return stable metadata including `videoId`, `statusUrl`, `downloadUrl`, `optimizedPrompt`, and `shotPlan`

## Usage

Create a job:

```ts
await express({
prompt: "A cinematic drone shot flying through a neon rainy city at night",
model: "sora-2",
seconds: "8",
size: "1280x720"
}, { gatewayFetch });
```

Preview how the gene will optimize a raw prompt before generating:

```ts
await express({
operation: "prepare",
prompt: "A lone traveler walking through a neon rainy alley at night"
});
```

Use structured fields for better prompt adherence:

```ts
await express({
subject: "一位穿白色长裙的年轻女子",
action: "在森林溪流边俯身洗手",
scene: "清晨薄雾中的树林与浅溪",
style: "写实电影感",
camera: "中景，慢速推镜",
lighting: "柔和晨光",
mood: "安静、梦幻",
avoid: ["字幕", "水印", "额外人物", "肢体畸变"],
model: "sora-2",
seconds: "4",
size: "720x1280",
pollUntilComplete: true
}, { gatewayFetch });
```

Create and poll until done:

```ts
await express({
prompt: "A paper boat sailing across a glowing galaxy river",
pollUntilComplete: true,
pollIntervalMs: 5000,
maxPollAttempts: 12
}, { gatewayFetch });
```

Fetch an existing job:

```ts
await express({
operation: "status",
videoId: "video_123"
}, { gatewayFetch });
```

## Notes

- This gene returns the OpenAI content endpoint as `downloadUrl` when a job is completed.
- The current Rotifer network gateway reads response bodies as text, so this gene tracks jobs and exposes the content URL rather than downloading MP4 bytes directly.
- For short prompts, the gene now auto-expands the instruction with consistency constraints unless `enhancePrompt` is set to `false`.
- Prompt enhancement now stays in the same language as the input prompt and adds a `shotPlan`, inferred `optimizationProfile`, and `negativePrompt`.