03Начало работы
Библиотеки для Python и Node.jsНовое
Готовые клиенты берут на себя ключ повтора, ожидание результата и проверку подписи вебхука. Те же пять методов API — меньше кода.
Эта модель рисует не все разрешения и форматы кадра: в примерах стоят те, что ей доступны.
Установка
# Python 3.11 и новее
$ pip install rendergrid# Node.js 22 и новее
$ npm install @rendergrid/sdkКлюч библиотеки берут из переменной окружения RENDERGRID_API_KEY. Другой источник можно передать явно: Rendergrid(api_key=…).
Первая картинка
from rendergrid import Rendergrid client = Rendergrid() # ключ берётся из RENDERGRID_API_KEY creation = client.images.generate( model="nano-banana-pro", prompt="Керамическая кружка на мраморе, мягкий свет окна", resolution="1K", aspect_ratio="4:5", ) print(creation.id, creation.status, creation.cost) result = creation.wait(timeout=180) # опрос не чаще раза в 5 секунд print(result.result_urls)
import { Rendergrid } from "@rendergrid/sdk"; // ключ берётся из RENDERGRID_API_KEY const client = new Rendergrid(); const creation = await client.images.generate({ model: "nano-banana-pro", prompt: "Керамическая кружка на мраморе, мягкий свет окна", resolution: "1K", aspect_ratio: "4:5", }); console.log(creation.id, creation.status, creation.cost); // опрос не чаще раза в 5 секунд const result = await creation.wait({ timeoutMs: 180_000 }); console.log(result.result_urls);
generate отправляет запрос и возвращает принятое задание. wait опрашивает его, пока оно не станет completed или failed. Если за отведённое время результата нет, вы получите ошибку с id задания — продолжить можно позже.
Что библиотека делает за вас
| Задача | Что делает библиотека | Подробнее |
|---|---|---|
| Ключ повтора | Создаёт X-Idempotency-Key сам и сохраняет его при повторах | Повтор без двойного списания |
| Повторы | При обрыве связи, 429 и 5xx повторяет запрос до трёх раз и ждёт не меньше Retry-After. Ответ, который сам говорит, что повтор не нужен, не повторяется. Загрузку образца (uploads.create) повторяет только тогда, когда запрос точно не дошёл до API: после 429, 503 или отказа в соединении | Лимиты |
| Ожидание | Опрашивает задание не чаще раза в 5 секунд и учитывает min_interval_seconds | Задачи и статусы |
| Ошибки | Превращает ответ в исключение с полями status, code, retryable и details | Коды ошибок |
| Вебхуки | Проверяет подпись и свежесть метки времени, возвращает разобранное событие | Вебхуки |
| Деньги | Отдаёт суммы как Decimal в Python и как строки в Node.js — не как числа с плавающей точкой | Баланс |
Ошибки
import time import rendergrid try: creation = client.images.generate( model="nano-banana-pro", prompt="Керамическая кружка на мраморе", ) except rendergrid.InsufficientBalance as e: need, have = e.details["required"], e.details["available"] print("Нужно:", need, "доступно:", have) except rendergrid.RateLimited as e: time.sleep(e.retry_after) except rendergrid.APIError as e: print(e.status, e.code, e.retryable)
import { RendergridError } from "@rendergrid/sdk"; try { const creation = await client.images.generate({ model: "nano-banana-pro", prompt: "Керамическая кружка на мраморе", }); } catch (error) { if (!(error instanceof RendergridError)) throw error; if (error.code === "ERR_INSUFFICIENT_BALANCE") { const { required, available } = error.details; console.log("Нужно:", required, "доступно:", available); } else { console.log(error.status, error.code, error.retryable); } }
Классы ошибок называются по коду из API: ERR_INSUFFICIENT_BALANCE — InsufficientBalance, ERR_RATE_LIMIT — RateLimited. Всё остальное — общий APIError.
Вебхуки
import os from flask import Flask, request from rendergrid.webhooks import verify app = Flask(__name__) @app.post("/webhooks/rendergrid") def hook(): event = verify( secret=os.environ["RENDERGRID_WEBHOOK_SECRET"], headers=request.headers, body=request.get_data(), # исходные байты, не request.json ) if not event.get("test"): save_result( event["id"], event["status"], event.get("result_urls") ) return "", 204
import express from "express"; import { verifyWebhook } from "@rendergrid/sdk/webhooks"; const app = express(); const raw = express.raw({ type: "application/json" }); app.post("/webhooks/rendergrid", raw, (req, res) => { const event = verifyWebhook({ secret: process.env.RENDERGRID_WEBHOOK_SECRET, headers: req.headers, body: req.body, // Buffer: исходные байты тела }); if (!event.test) { saveResult(event.id, event.status, event.result_urls); } res.sendStatus(204); });
Подпись считается по исходным байтам тела. Если фреймворк успел разобрать JSON и собрать его заново, подпись не сойдётся.
Версии и другие языки
- Python
- 3.11 и новее. Пакет
rendergridна PyPI. - Node.js
- 22 и новее. Пакет
@rendergrid/sdkна npm, работает и с TypeScript. - Версии API
- Библиотеки работают с API v1. Новые поля в ответах не ломают старые версии библиотек.
Библиотека не обязательна: всё, что она делает, делается обычными HTTPS-запросами, как в «Быстром старте». Нет вашего языка? Возьмите описание OpenAPI и сгенерируйте клиент.