Интерфейс генерации изображений

Общие соглашения (базовый адрес, аутентификация, структура ответа, ограничение частоты запросов) см. в разделе Аутентификация и базовые соглашения.

Создание изображения

Способ аутентификации

Authorization: Bearer <API_KEY>, используется платформенный API Key, созданный на странице «Ключи API» в консоли.

Тело запроса · application/json

Ограничения моделей изображений на размеры, количество и формат возврата различаются; сначала проверьте через /v1/models и ориентируйтесь на ошибки валидации параметров, возвращаемые интерфейсом.

Пример запроса

curl -X POST "https://locopalai.com/v1/images/generations" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "从 /v1/models 选择的图片模型 ID",
  "prompt": "白色桌面上的一个红苹果，柔和自然光，产品摄影",
  "size": "当前模型支持的尺寸",
  "n": 1
}
JSON

Параметры ответа

Один запрос может вернуть только url или только b64_json — в зависимости от модели и канала; ориентируйтесь на фактические поля ответа, а при наличии обоих предпочитайте url.

Тело ответа

Возврат адреса (форма url):

{
  "created": 1789567052,
  "data": [
    {
      "size": "2048x2048",
      "url": "https://media.example.com/image-public-id.jpeg"
    }
  ],
  "model": "Doubao-Seedream-4.5"
}

Возврат Base64 (форма b64_json, фрагмент):

{
  "background": "auto",
  "created": 1789071752,
  "data": [
    { "b64_json": "iVBORw0KGgoAAAANSUhEUgAABAAAAAQACAIAAADwf7zU..." }
  ]
}

Адрес, возвращаемый в форме url, может быть краткосрочным подписанным адресом — своевременно сохраните или зарегистрируйте его; данные в форме b64_json декодируйте самостоятельно и храните надлежащим образом. Не предполагайте, что все модели изображений принимают response_format или одинаковые размеры. На практике gpt-image-1-mini отклоняет response_format, а Doubao-Seedream-4.5 сейчас требует не менее 3686400 пикселей: 2048x2048 принимается, а 1024x1024 возвращает ошибку параметров.

Ответ с ошибкой

{
  "error": {
    "message": "当前图片模型不支持请求的尺寸",
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "param": "size"
  }
}

Полное описание см. в разделе Коды ошибок и диагностика.

Изображение в изображение (редактирование изображений)

Генерация нового изображения на основе существующего: загрузите одно или несколько референсных изображений, и модель по prompt перерисует сцену, сменит стиль или выполнит локальную перерисовку.

Тело запроса · multipart/form-data

Запрос обязательно должен содержать референсное изображение; без него интерфейс сразу вернёт ошибку параметров, не обращаясь к модели.

Пример запроса

curl -X POST "https://locopalai.com/v1/images/edits" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -F "model=从 /v1/models 选择的图片模型 ID" \
  -F "prompt=把这张照片改成柔和的水彩画风格" \
  -F "size=1024x1024" \
  -F "image=@./reference.png"

  -F "image[]=@./reference-a.png" \
  -F "image[]=@./reference-b.png"

Тело ответа

Та же структура, что и в разделе Создание изображения; изображение возвращается в виде b64_json или url:

{
  "background": "opaque",
  "created": 1789651524,
  "data": [
    { "b64_json": "iVBORw0KGgoAAAANSUhEUgAABAAAAAQACAIAAADwf7zU..." }
  ],
  "output_format": "png",
  "quality": "low",
  "size": "1024x1024",
  "usage": {
    "input_tokens": 1041,
    "input_tokens_details": { "image_tokens": 1032, "text_tokens": 9 },
    "output_tokens": 439,
    "total_tokens": 1480
  }
}

usage.input_tokens_details.image_tokens отражает расход на референсные изображения: чем больше изображений или чем больше их размер, тем выше число входных токенов.

Передача референсного изображения по публичному адресу

Модели с поддержкой входных референсных изображений также позволяют передавать их в JSON-теле POST /v1/images/generations через images; элементы — публичные адреса изображений https://:

curl -X POST "https://locopalai.com/v1/images/generations" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "从 /v1/models 选择的图片模型 ID",
  "prompt": "把这张照片改成柔和的水彩画风格",
  "images": ["https://example.com/reference.png"]
}
JSON

Референсное изображение должно напрямую загружаться сервером; если адрес недействителен или требует входа, запрос завершится ошибкой загрузки на вышестоящей стороне. Структура ответа совпадает с разделом Создание изображения.

Связь с библиотекой материалов

Сгенерированные изображения не попадают в библиотеку материалов автоматически. Если позже видеозадача должна использовать изображение как референсное, сначала добавьте его через интерфейсы библиотеки материалов и дождитесь статуса Active, затем ссылайтесь на него через asset://<asset_id>.