Архитектурный рабочий процесс с Gemini API: первый текстовый запрос на Python

Чему вы научитесь в этом руководстве?

Это руководство предназначено для архитекторов, дизайнеров интерьеров и специалистов по визуализации, которые хотят отправить первый текстовый запрос в Gemini API из Python. Мы покажем, как с помощью интерфейса Interactions API от Google создать промпт, прочитать текстовый ответ и получить его в потоковом режиме. Примеры посвящены текстовым задачам, которые могут возникнуть в ходе проектирования: например, запросить идеи для небольшой гостиной или подготовиться к встрече по концепции кафе.

Примеры кода в этом руководстве предназначены для получения текстового ответа. Возможности Gemini API этим не ограничиваются: в стартовом руководстве Google среди поддерживаемых API задач также перечислены генерация текста, мультимодальное понимание, создание изображений, структурированный вывод и использование инструментов. Однако текстовые ответы из приведённых здесь примеров не заменяют чертежи, рендеры или техническую проверку; проектные решения должна проверять команда.

Что понадобится: аккаунт, ключ и ПО

Для начала получите API-ключ через Google AI Studio. Согласно руководству Google, для новых пользователей AI Studio может автоматически создать проект и ключ; существующие пользователи могут создать новую связку ключа и проекта на странице API Keys. Также указано, что для использования бесплатного уровня дополнительными проектами, импортированными из Google Cloud, может потребоваться верификация проекта.

В этом руководстве используется Python SDK. Команда установки из источника установит пакет google-genai или обновит его. В руководстве не указано конкретное требование к версии Python, поэтому здесь дополнительные ограничения по версии не вводятся. Вместо того чтобы вписывать API-ключ непосредственно в исходный код, задайте его как переменную среды:

export GEMINI_API_KEY="YOUR_API_KEY"

Замените YOUR_API_KEY своим ключом. Эта команда задаёт переменную GEMINI_API_KEY в среде, где она выполняется. Чтобы контролировать доступ, не добавляйте ключ в общедоступные репозитории кода или файлы, открытые для посторонних.

Чтобы перейти на платный уровень, необходимо настроить Cloud Billing, добавить способ оплаты и внести предоплату за платные кредиты на сумму не менее 5 долларов или эквивалент. Google отмечает, что на платном уровне повышаются лимиты скорости. Отслеживать использование API можно на странице использования в Google AI Studio.

Отправьте первый запрос: пошаговая инструкция

1. Установите SDK. Выполните в среде Python следующую команду:

pip install -U google-genai

Команда установит пакет google-genai через pip или обновит существующую версию. Если вы используете несколько сред Python, выполните команду именно в той среде, где будет запускаться код.

1. Подготовьте первый текстовый запрос. Добавьте приведённый ниже пример в файл Python. В промпте запрашиваются письменные рекомендации для небольшой гостиной в жилом помещении:

from google import genai

client = genai.Client()
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Küçük bir konut salonu için gün ışığını ve dolaşımı gözeten üç tasarım önerisi yaz. Her öneride tasarım kararını ve gerekçesini belirt."
)
print(interaction.output_text)

Запрос отправляется модели gemini-3.8-flash через Interactions API; в примере результат выводится на экран с помощью interaction.output_text. Текст промпта можно адаптировать под задачу, которая нужна в реальном рабочем процессе. Например, можно запросить описание концепции для презентации, черновик сравнения вариантов отделочных материалов или список вопросов для встречи с заказчиком. Если чётко описать ожидаемый объём и формат ответа, его будет проще оценить.

1. Уточните промпт с учётом контекста проекта. Вместо общей команды укажите тип пространства и желаемый результат. Пример ниже — оригинальный промпт для подготовки к встрече по дизайну интерьера:

Bir kafe iç mekânı için konsept geliştirme toplantısına hazırlanıyorum. Tasarım ekibinin tartışması için üç farklı atmosfer yönü öner. Her yönü kısa bir başlık, mekânsal yaklaşım ve müşteriye sorulacak iki net soruyla açıkla. Proje verisi verilmediğinde varsayım üretme; eksik bilgileri ayrıca belirt.

Этот промпт запрашивает текстовый черновик для обсуждения на встрече, а не визуальный или технический результат. Просьба отдельно указывать неизвестные данные может помочь не смешивать ответ с фактической информацией о проекте; тем не менее текст должен проверяться командой.

1. Получите ответ в потоковом режиме. Если приложению нужно обрабатывать ответ по мере его генерации, в запросе можно указать stream=True. Пример ниже перебирает события, возвращаемые API, и выводит их на экран:

from google import genai

client = genai.Client()
stream = client.interactions.create(
    model="gemini-3.8-flash",
    input="Bir mimari konsept sunumu için kısa bir açılış metni yaz.",
    stream=True
)
for event in stream:
    print(event)

При потоковой передаче ответ приходит в виде событий, а не одного цельного текста. В руководстве Google поясняется, что события step.delta могут содержать части текста по мере формирования ответа. В этом примере каждое событие выводится напрямую; при разработке приложения отдельно нужно продумать, как показывать события пользователю.

Применение в архитектурных рабочих процессах и визуализации

Эти примеры могут стать отправной точкой для текстовых задач: подготовки описания концепции, составления вопросов к повестке встречи, письменного сравнения вариантов дизайна и создания черновика текста для презентации. Команда может выбрать одну повторяющуюся и чётко очерченную задачу, а затем оценить, сколько редактирования требует результат. Такой подход не позволяет делать выводы о возможностях API в области генерации изображений или проверки проекта — он помогает оценить лишь пригодность показанных текстовых запросов для рабочего процесса.

Эти примеры не измеряют производительность локального рендеринга рабочей станции. В источнике нет требований к конкретному GPU или рекомендаций по оборудованию для такого использования, поэтому не следует принимать решение об обновлении устройства на основании этих примеров. При работе с аккаунтом важно управлять API-ключом, отслеживать использование и при необходимости оценивать стоимость платного уровня. Для перехода на платный уровень требуются Cloud Billing и предоплата; команде полезно заранее распределить ответственность за использование и контроль бюджета.

Частые ошибки и дальнейшие шаги

• Ключ не задан: Запустите файл Python в среде, где определена переменная GEMINI_API_KEY.

• Пакет установлен в другой среде: Убедитесь, что пакет google-genai установлен именно в той среде Python, из которой запускается код.

• Слишком общий промпт: Укажите тип пространства, цель текста и формат ответа.

• Ответ принимается за утверждённые сведения о проекте: Не считайте текст проектным решением или технической проверкой; он должен пройти оценку команды.

• Платное использование начинается без плана: До перехода на платный уровень изучите требования Cloud Billing и условия предоплаты.

Когда первый запрос заработает, не спешите создавать масштабную автоматизацию — выберите часто повторяющуюся в команде текстовую задачу с чёткими границами. Улучшайте промпт небольшими шагами и отслеживайте полезность результатов, объём необходимой правки и использование API. В руководстве Google также описаны SDK для разработки приложений и Gemini API CLI — для прямых вызовов API из скриптов или заданий командной строки. Примеры кода в этом руководстве ограничены Python SDK и Interactions API.

Источник и лицензия

Руководство адаптировано на турецкий язык на основе документа Google “Getting started” по Gemini API (K1). Источник опубликован по лицензии CC BY 4.0. Примеры промптов для архитектуры и интерьеров созданы специально для этого руководства.