Replicate откатила data URL в синхронном API: что сломалось и что будет дальше

Что произошло

В начале октября Replicate запустила синхронный режим своего API. Идея была простая: сократить время ожидания и упростить работу с выводом моделей.

Механика выглядела так:

• клиент отправляет HTTP‑заголовок Prefer: wait;
• Replicate ждёт до 60 секунд, пока модель закончит работу;
• если успевает — сразу отдаёт результат в ответе, без отдельного запроса за статусом;
• для файлов (картинки, аудио и т.п.) Replicate начала возвращать не только https://‑ссылки, но и data URL с base64‑данными, чтобы убрать ещё один HTTP‑запрос.

Синхронный режим стал доступен всем клиентам уже в начале октября — любой мог включить его через Prefer: wait. Поддержка в официальных библиотеках появилась в версиях 1.0.0 для JavaScript и Python. В этих релизах методы replicate.run по умолчанию начали использовать синхронный API.

Data URL Replicate включала постепенно, в течение всего октября. До этого большинство моделей возвращали только https://‑ссылки. Когда компания начала поэтапно включать data URL (вторая часть обновления), у части пользователей приложения просто перестали работать.

29 октября 2024 года Replicate приняла решение откатить ответы с data URL в синхронном API. Команда понимала, что это тоже кого‑то поломает, но посчитала, что так ущерб будет меньше.

Кого это могло задеть:

• разработчики на JavaScript и Python, которые обновились до 1.x‑версий клиентских библиотек и использовали replicate.run с моделями, у которых data URL ещё не были включены на момент релиза;
• разработчики, которые ходили в sync API напрямую (через HTTP) к моделям без включённых data URL;
• те, кто уже получил ответы в формате data URL, а потом столкнулся с откатом обратно к https://.

Не пострадали:

• все, кто сидит на версиях библиотек до 1.x;
• все, кто не отправлял заголовок Prefer: wait;
• те, кто использовал replicate.predictions.create, а не replicate.run.

Контекст

Replicate — это про API для генеративных моделей, где ломать продакшн‑код особенно больно. Компания хотела сделать жизнь разработчиков проще: меньше запросов, быстрее ответы, меньше обвязки.

Синхронный режим с Prefer: wait решал понятную задачу: не нужно опрашивать статус предсказания, можно один раз дернуть API и сразу получить результат. Data URL поверх этого казались логичным следующим шагом: модель сгенерировала картинку до 5 МБ — Replicate сразу вшивает её в ответ, без отдельного скачивания по https://.

На бумаге это выглядело обратно совместимо: API обещал, что если размер ответа меньше 5 МБ, он вернёт data URL, а если больше — обычную https://‑ссылку. Но в реальности почти весь октябрь большинство моделей продолжали отдавать только https://. Разработчики писали код под это фактическое поведение.

Параллельно Replicate добавила новый тип FileOutput в клиентские библиотеки. Идея была — абстрагировать разработчика от того, что именно пришло: https:// или data URL. На практике многие просто доставали url и ждали там обычный HTTP‑адрес. Когда в этот же url внезапно прилетел data URL с base64, код падал.

Сверху добавился ещё один неприятный эффект: примеры с curl из документации. Разработчики копировали команды, запускали в терминале и получали на экране огромные простыни base64‑данных. Опции «отключить data URL» в API не было.

В итоге Replicate поймала волну жалоб ещё до того, как успела включить data URL для всех моделей. Стало понятно, что продолжать rollout — значит гарантированно ломать всё больше продакшна.

Что это значит для вас

Если вы работаете с Replicate, особенно через JavaScript или Python‑клиенты, это обновление напрямую касается вашего кода.

Что важно проверить прямо сейчас:

1. Версии библиотек.

   • Если вы используете версии до 1.x — текущее поведение для вас не менялось: никакого синхронного режима по умолчанию, никаких data URL.
   • Если вы уже на 1.x, ваши replicate.run по умолчанию ходят в sync API с Prefer: wait. Сейчас он снова возвращает только https://‑ссылки, но в будущем это может измениться.

2. Работа с файлами.

   • Если ваш код явно полагается на то, что url — это HTTP‑ссылка, лучше заложить поддержку обоих вариантов: https:// и data:.
   • Проверьте, как вы обрабатываете тип FileOutput в новых библиотеках Replicate. Не опирайтесь на внутреннюю структуру объекта, работайте через официальные поля и методы.

3. CLI и отладка.

   • Если вы часто копируете curl‑примеры из документации и запускаете их в терминале, будьте готовы к тому, что позже Replicate снова вернёт data URL. Заранее продумайте, куда вы будете писать такие ответы: в файл, пайп или лог.

4. Ожидания от API.

   • Replicate честно признаёт, что промахнулась с коммуникацией и тестированием связки «API + клиенты». Компания обещает пересмотреть версионирование и прозрачность изменений.
   • Практический вывод: не полагайтесь только на формальное описание API. Смотрите на фактическое поведение, следите за changelog и не обновляйте клиентские библиотеки до 1.x в продакшене без тестов.

Плюс ситуации в том, что Replicate быстро откатила спорное изменение и признала ошибку. Минус — пользователи получили ломающее обновление, хотя по идее всё должно было быть «опциональным».

Если вы строите свой продукт вокруг Replicate, сейчас разумная стратегия — зафиксировать версии библиотек, добавить тесты на формат вывода (особенно файлов) и внимательно следить за следующими анонсами по синхронному API и data URL.