Freepik / API

Movie — Freepik Automation Scaffold

Зафиксировать первый API-first automation scaffold проекта `movie` вокруг `Freepik API`, чтобы следующий слой работы строился не на ручных копипастах ключей в браузер, а на серверном provider-контуре с понятными route contracts. Этот документ фиксирует: - какие env-переменные нужны; - какие routes уже доступны; - как безопасно вызывать automation снаружи; - как использовать `Flux Kontext Pro` для still refs и `Runway 4.5` для image-to-video.

6 мин чтения1,183 слов0 пунктов checklist

Цель#

Зафиксировать первый API-first automation scaffold проекта movie вокруг Freepik API, чтобы следующий слой работы строился не на ручных копипастах ключей в браузер, а на серверном provider-контуре с понятными route contracts.

Этот документ фиксирует:

  • какие env-переменные нужны;
  • какие routes уже доступны;
  • как безопасно вызывать automation снаружи;
  • как использовать Flux Kontext Pro для still refs и Runway 4.5 для image-to-video.

1) Почему этот scaffold появился сейчас#

Для movie уже стало ясно:

  • ручной Adobe Boards полезен как UI-инструмент;
  • но automation нельзя строить вокруг UI-only слоя;
  • у Freepik API есть официальный image и video API;
  • значит первый automation contour проекта разумно строить вокруг Freepik API, а не вокруг ручного board-canvas.

Важно:

  • Boards остаётся как manual previsualization tool;
  • automation first идёт через Freepik API;
  • секреты не уходят в браузер напрямую.

2) Env configuration#

Канонический локальный шаблон:

Локальный рабочий файл:

Нужные переменные:

OPENAI_API_KEY=
FREEPIK_API_KEY=
MOVIE_AUTOMATION_TOKEN=

Что означает каждая переменная

  • OPENAI_API_KEY: для ref-pack / image workflow / будущих OpenAI adapters
  • FREEPIK_API_KEY: для text-to-image и image-to-video запросов в Freepik API
  • MOVIE_AUTOMATION_TOKEN: bearer-token для безопасного вызова automation routes извне

Если MOVIE_AUTOMATION_TOKEN не задан:

  • automation routes работают только с localhost
  • внешний вызов через dev-домен блокируется

Это сделано специально, чтобы не превратить dev.movie.designcorp.eu в открытый proxy к платному API.

3) Доступные routes#

Health

GET /api/automation/freepik/health

Назначение:

  • проверить, что provider-слой собран;
  • увидеть auth mode;
  • увидеть default model/ration settings.

Text-to-image task create

POST /api/automation/freepik/text-to-image/tasks

Current default model:

  • flux-kontext-pro

Назначение:

  • создавать async text-to-image task для still refs

Text-to-image task list

GET /api/automation/freepik/text-to-image/tasks

Назначение:

  • смотреть список image tasks без расхода новых генераций

Text-to-image task status

GET /api/automation/freepik/text-to-image/tasks/{taskId}

Назначение:

  • получить статус и generated URLs по конкретному task id

Image-to-video task create

POST /api/automation/freepik/image-to-video/tasks

Current default model:

  • runway-4-5

Назначение:

  • создавать async I2V task на основе still ref

Image-to-video task list

GET /api/automation/freepik/image-to-video/tasks

Назначение:

  • смотреть список video tasks

Image-to-video task status

GET /api/automation/freepik/image-to-video/tasks/{taskId}

Назначение:

  • получить статус и generated URLs по конкретному video task id

Episode manifest

GET /api/automation/episodes/{episodeId}/manifest
POST /api/automation/episodes/{episodeId}/manifest

Назначение:

  • читать текущий episode manifest
  • писать notes в manifest

Episode import from Freepik

POST /api/automation/episodes/{episodeId}/imports/freepik

Назначение:

  • взять completed task по taskId
  • скачать generated files в episode folder
  • записать generated URLs и downloaded files в episode manifest

Episode asset proxy

GET /api/automation/episodes/{episodeId}/assets/{path}?token=<MOVIE_AUTOMATION_TOKEN>

Назначение:

  • отдать approved local ref как публично доступный URL для Freepik image-to-video
  • использовать token в query, потому что внешний provider не сможет прислать bearer header

Public refs

GET /api/automation/episodes/{episodeId}/refs/{fileName}

Назначение:

  • открыть canonical ref из 02_refs без bearer token
  • использовать для быстрого визуального debug/smoke по HTTPS

Public previews

GET /api/automation/episodes/{episodeId}/previews/{fileName}

Назначение:

  • открыть готовый mp4 из 04_generations прямо через dev-домен
  • быстро проверять первые generated shots

4) Security model#

Automation routes работают так:

  • если задан MOVIE_AUTOMATION_TOKEN, route требует header: Authorization: Bearer <MOVIE_AUTOMATION_TOKEN>
  • если token не задан, route доступен только с localhost

Это означает:

  • локальный development можно запускать сразу;
  • внешний automation client надо подключать уже с bearer token.

Episode routes используют ту же модель защиты.

5) Request body: text-to-image#

Минимальный body:

{
  "prompt": "Stylized 2D cartoon lemur and sloth in Depot 17",
  "aspectRatio": "social_story_9_16"
}

Поддерживаемые поля:

{
  "prompt": "string",
  "inputImage": "https://example.com/ref.png",
  "promptUpsampling": false,
  "seed": 123,
  "guidance": 3,
  "steps": 50,
  "aspectRatio": "social_story_9_16",
  "safetyTolerance": 2,
  "outputFormat": "jpeg",
  "webhookUrl": "https://example.com/webhook",
  "model": "flux-kontext-pro"
}

6) Request body: image-to-video#

Минимальный body:

{
  "prompt": "The box slowly starts to slip while the shelf trembles",
  "imageUrl": "https://example.com/approved-ref.png",
  "ratio": "720:1280",
  "duration": 5
}

Или через base64:

{
  "prompt": "The box slowly starts to slip while the shelf trembles",
  "imageBase64": "<base64>",
  "ratio": "720:1280",
  "duration": 5
}

Или через локальный ref файла эпизода:

{
  "prompt": "The box slowly starts to slip while the shelf trembles",
  "episodeId": "movie_ts01_s01e01",
  "episodeRefPath": "movie_ts01_s01e01_ref_first_slip_v03_9x16.png",
  "ratio": "720:1280",
  "duration": 5
}

Поддерживаемые поля:

{
  "prompt": "string",
  "episodeId": "movie_ts01_s01e01",
  "episodeRefPath": "movie_ts01_s01e01_ref_brum_shelf_pride_v01_9x16.png",
  "imageUrl": "https://example.com/image.png",
  "imageBase64": "<base64>",
  "ratio": "720:1280",
  "duration": 5,
  "seed": 12345,
  "webhookUrl": "https://example.com/webhook",
  "model": "runway-4-5"
}

Нельзя передавать одновременно несколько image source-полей.

Рекомендуемый путь для movie сейчас:

  • брать approved ref из 02_refs;
  • передавать episodeId + episodeRefPath;
  • route сам нормализует ref в 720x1280 jpeg;
  • route сам упакует его в data:image/jpeg;base64,... перед запросом в Freepik.

Этот путь уже дал первый реальный completed shot для TS-01 / sc01.

7) Примеры вызова#

Health

curl -s \
  -H "Authorization: Bearer $MOVIE_AUTOMATION_TOKEN" \
  https://dev.movie.designcorp.eu/api/automation/freepik/health

Create still ref task

curl -s \
  -X POST \
  -H "Authorization: Bearer $MOVIE_AUTOMATION_TOKEN" \
  -H "Content-Type: application/json" \
  https://dev.movie.designcorp.eu/api/automation/freepik/text-to-image/tasks \
  -d '{
    "prompt": "Stylized 2D cartoon frame of a small lemur and a large sloth in Depot 17, clean silhouettes, social story vertical composition",
    "aspectRatio": "social_story_9_16",
    "guidance": 3,
    "steps": 50
  }'

Poll still ref task

curl -s \
  -H "Authorization: Bearer $MOVIE_AUTOMATION_TOKEN" \
  "https://dev.movie.designcorp.eu/api/automation/freepik/text-to-image/tasks/<task-id>"

Create I2V task

curl -s \
  -X POST \
  -H "Authorization: Bearer $MOVIE_AUTOMATION_TOKEN" \
  -H "Content-Type: application/json" \
  https://dev.movie.designcorp.eu/api/automation/freepik/image-to-video/tasks \
  -d '{
    "prompt": "The upper box slowly begins to slip and the shelf starts to tremble",
    "imageUrl": "https://example.com/movie_ts01_s01e01_ref_first_slip_v03_9x16.png",
    "ratio": "720:1280",
    "duration": 5
  }'

Use local approved ref as external image URL

https://dev.movie.designcorp.eu/api/automation/episodes/movie_ts01_s01e01/assets/02_refs/movie_ts01_s01e01_ref_brum_shelf_pride_v01_9x16.png?token=<MOVIE_AUTOMATION_TOKEN>

Create I2V task from local episode ref

curl -s \
  -X POST \
  -H "Authorization: Bearer $MOVIE_AUTOMATION_TOKEN" \
  -H "Content-Type: application/json" \
  https://dev.movie.designcorp.eu/api/automation/freepik/image-to-video/tasks \
  -d '{
    "episodeId": "movie_ts01_s01e01",
    "episodeRefPath": "movie_ts01_s01e01_ref_brum_shelf_pride_v01_9x16.png",
    "prompt": "Slow gentle push-in on Brum standing proudly beside a perfectly organized emergency shelf in Depot 17.",
    "ratio": "720:1280",
    "duration": 5
  }'

Read episode manifest

curl -s \
  -H "Authorization: Bearer $MOVIE_AUTOMATION_TOKEN" \
  https://dev.movie.designcorp.eu/api/automation/episodes/movie_ts01_s01e01/manifest

Import completed task into 04_generations

curl -s \
  -X POST \
  -H "Authorization: Bearer $MOVIE_AUTOMATION_TOKEN" \
  -H "Content-Type: application/json" \
  https://dev.movie.designcorp.eu/api/automation/episodes/movie_ts01_s01e01/imports/freepik \
  -d '{
    "kind": "image-to-video",
    "taskId": "<task-id>",
    "model": "runway-4-5",
    "shotId": "sc01",
    "assetPrefix": "movie_ts01_s01e01_sc01_rw45_v01_9x16",
    "targetDir": "04_generations"
  }'

Open generated preview in browser

https://dev.movie.designcorp.eu/api/automation/episodes/movie_ts01_s01e01/previews/movie_ts01_s01e01_sc01_rw45_v01_9x16.mp4

8) Как это использовать в movie#

Для still refs

Используем:

  • text-to-image/tasks
  • потом text-to-image/tasks/{taskId}

Подходит для:

  • новые character refs
  • prop refs
  • backup variations
  • prompt-driven batch generation

Для первых video shots

Используем:

  • image-to-video/tasks
  • потом image-to-video/tasks/{taskId}

Подходит для:

  • sc01
  • sc02
  • sc03

То есть для первого Runway Pass 1 этот scaffold уже годится.

9) Что этот scaffold пока не делает#

  • не пишет task registry в базу
  • не строит orchestration graph по episode shot list
  • не заменяет manual board-layer

Это intentional. Сейчас нужен рабочий API contour, а не premature platform.

10) Следующий шаг#

Следующий разумный automation шаг после этого scaffolding:

  1. prompt templates на уровне TS-01
  2. batch runner для sc01-sc03
  3. selects/manifest review layer
  4. second/third shot assembly into rough animatic
НазадMovie — Video Stack DecisionДальшеMovie — Production SOP для batch 01