Быстрый старт

Сейчас у LocoPal есть два основных пути: создание прямо в LocoPal Creation или подключение API LocoPal Ai к своему бизнесу.

Оба способа используют один и тот же аккаунт LocoPal, каталог моделей и систему биллинга. На этой странице основное внимание уделено LocoPal Ai и LocoPal Creation.

Шаг 1: Зарегистрируйтесь или войдите в LocoPal Ai

1. Откройте LocoPal Ai. Если аккаунт уже есть, просто войдите; если нет — перейдите на страницу регистрации.
2. Текущая страница регистрации требует задать имя пользователя и пароль, а также пройти проверку по SMS на номер телефона. Способ проверки может меняться в зависимости от политики безопасности — ориентируйтесь на подсказки на самой странице регистрации.
3. После входа проверьте баланс аккаунта, квоту тарифа или доступные баллы. Перед использованием Creation или API всегда убеждайтесь, что аккаунт доступен.

Шаг 2: Сразу используйте LocoPal Creation

Если цель — сразу генерировать контент, рекомендуется начать с Creation: писать код не нужно, API Key создавать тоже не нужно.

1. Откройте LocoPal Creation.
2. У Creation нет отдельного аккаунта. Если вы не вошли, страница перенаправит на вход LocoPal, а после авторизации автоматически вернёт в Creation — пароль вводить повторно не придётся.
3. На главной странице выберите интеллектуальный режим, AI-рисование, AI-видео или AI-аудио и введите запрос; в рабочей среде также доступны короткометражки, работы, материалы, промпты, словари и галерея работ.
4. Если нужно сохранить единообразие персонажа, товара или стиля, перед отправкой загрузите референсное изображение или выберите существующий материал.
5. После отправки следите за статусом задачи на текущей странице, просматривайте результат и скачивайте его или используйте дальше. Обновление страницы не создаёт задачу заново — не отправляйте повторно задачу, которая ещё выполняется.

Диапазон доступных моделей в Creation совпадает с текущим каталогом моделей LocoPal Ai, а расход вызовов учитывается в текущем аккаунте LocoPal. Если модель недоступна, сначала проверьте в каталоге моделей LocoPal Ai, входит ли она в текущую доступную группу.

Шаг 3: Подключите API и создайте API Key

Перейдите в консоли LocoPal Ai в раздел «Ключи API» и нажмите «Создать». Рекомендуется создавать отдельные ключи для «рабочего сервиса / тестовой среды / клиентского приложения» — так удобнее смотреть журналы по приложениям, ограничивать квоты и своевременно отключать скомпрометированные ключи.

При создании обратите внимание на следующее:

• имя Key служит для различения вызывающих сторон;
• группа вызовов определяет, какие модели этот Key видит и может вызывать;
• квота и срок действия ограничивают аномальный расход;
• один Key может вызывать интерфейсы моделей, изображений, видео, аудио и материалов — создавать разные Key для разных интерфейсов не нужно.

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

Шаг 4: Подготовьте базовый адрес

Базовый адрес по умолчанию:

export LOCOPAL_API_KEY="sk-你的APIKey"
export LOCOPAL_BASE_URL="https://locopalai.com"

Консоль платформы также может показывать адрес доступа, предназначенный для зарубежных моделей или специфических сетевых условий, например:

https://us-api.locopalai.com

При интеграции используйте адрес, который в данный момент отображается в консоли. В LOCOPAL_BASE_URL указывайте только домен, не добавляйте повторно /v1; путь интерфейса уже содержит /v1 или /api/v1.

Шаг 5: Узнайте, какие модели доступны текущему Key

curl "$LOCOPAL_BASE_URL/v1/models" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

{
  "object": "list",
  "success": true,
  "data": [
    {
      "id": "doubao-seedance-2.0",
      "object": "model",
      "created": 1626777600,
      "owned_by": "doubaovideo",
      "supported_endpoint_types": ["openai"]
    }
  ]
}

• В запросе model должен использовать data[].id, а не отображаемое на странице название;
• ответ "data": [] означает, что в группе вызовов текущего Key нет доступных моделей — сначала проверьте настройку группы или обратитесь в поддержку платформы;
• каталог моделей может меняться вместе с авторизацией аккаунта, адресом доступа и доступностью платформы; рекомендуется повторно запрашивать его при запуске сервиса, смене модели пользователем или получении сообщения «модель недоступна»;
• один и тот же Key на locopalai.com и us-api.locopalai.com может видеть разные наборы моделей; если используете адрес, ориентируйтесь на /v1/models этого адреса;
• возможность вызова модели определяется результатом /v1/models для текущего Key — не хардкодьте названия моделей.

Как определить подходящий пример по supported_endpoint_types

data[].supported_endpoint_types прямо говорит, к какому типу интерфейса относится модель, — по нему и выбирайте пример:

У одной модели supported_endpoint_types может содержать несколько значений — это значит, что её можно вызывать через несколько интерфейсов.

Шаг 6: Первый текстовый вызов

curl -X POST "$LOCOPAL_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "从 /v1/models 选择的文本模型 ID",
    "messages": [{ "role": "user", "content": "用三句话介绍这个产品" }],
    "stream": false
  }'

При успехе текст читается из choices[0].message.content; сохраните usage из ответа для сверки. Модель рассуждений может израсходовать весь max_tokens на completion_tokens_details.reasoning_tokens — тогда message.content будет пустым, а finish_reason равен length; увеличьте лимит вывода или переключитесь на модель без рассуждений и повторите. При stream: true читайте ответ по частям через SSE до [DONE].

Шаг 7: Первый вызов изображений

curl -X POST "$LOCOPAL_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "从 /v1/models 选择的图片模型 ID",
    "prompt": "白色桌面上的一个红苹果，柔和自然光，产品摄影",
    "size": "1024x1024",
    "n": 1
  }'

Результат ответа обычно возвращается в data[] как url или b64_json. Возвращённый URL может быть временным — сохраните файл как можно скорее; size, quality и response_format зависят от текущей модели изображений; некоторые модели GPT Image отклоняют response_format и возвращают unknown_parameter — в этом случае уберите это поле. Если изображение будет использоваться как референс для видео, сначала загрузите его через интерфейс библиотеки материалов и дождитесь статуса Active, а затем ссылайтесь на него через asset://<asset_id>.

Шаг 8: Первый вызов видео

Видео — это асинхронная задача: интерфейс создания возвращает ID задачи, интерфейс запроса возвращает прогресс и результат.

POST /v1/video/generations и POST /v1/videos используют одинаковое тело запроса и формат ответа — можно выбрать любой; старый путь вызова платформа автоматически обрабатывает как задачу видеоплагина.

curl -X POST "$LOCOPAL_BASE_URL/v1/video/generations" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "从 /v1/models 选择的视频模型 ID",
  "content": [
    { "type": "text", "text": "清晨的湖边，镜头缓慢向前推进" }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5
}
JSON

{
  "created_at": 1789567067,
  "id": "task-public-id",
  "model": "seedance-2.0-mini",
  "status": "queued",
  "task_id": "task-public-id"
}

В ответе создания следует полагаться только на id / task_id, status, model и created_at; поля вроде object, progress могут появиться только после первого запроса, и их нельзя считать обязательными для успешного создания.

Сохраните id из ответа создания и запросите ту же задачу:

export LOCOPAL_TASK_ID="创建响应里的 id"

curl "$LOCOPAL_BASE_URL/v1/video/generations/$LOCOPAL_TASK_ID" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

После успешного завершения задачи прочитайте metadata.url, чтобы скачать или воспроизвести результат. Платформа в первую очередь возвращает исходный URL видео от upstream; только если upstream не вернул доступный адрес, используется резервный адрес артефакта платформы. Параметры видео, возвращаемые upstream, могут включать:

{
  "metadata": {
    "url": "https://上游原始视频地址",
    "upstream_created": true
  },
  "duration_secs": 5,
  "expires_at": 1790578352,
  "framespersecond": 24,
  "generate_audio": true,
  "ratio": "9:16",
  "resolution": "480p",
  "seed": 20260409,
  "output_format": "mp4",
  "execution_expires_after": 172800
}

В перечисленных полях duration_secs — длительность; expires_at появляется только если соответствующий upstream его вернул; остальные параметры видео также появляются только при фактическом возврате моделью и upstream. Получив ID задачи, даже при локальном таймауте ожидания можно только продолжать запрашивать исходную задачу — не создавайте её заново, иначе появятся дублирующиеся задачи и расходы.

Если в результате запроса status равен failed, прочитайте в том же ответе error.code и error.message. Для окончательного сбоя видеозадачи обычно используется video_generation_failed; error.message — читаемая причина, очищенная платформой, не пытайтесь разбирать JSON внутри неё:

{
  "id": "task-public-id",
  "status": "failed",
  "error": {
    "code": "video_generation_failed",
    "message": "音频素材缓冲失败: 音频地址必须是 http(s)"
  }
}

Шаг 9: Первый вызов синтеза речи

Платформа предоставляет совместимый с OpenAI интерфейс POST /v1/audio/speech. Доступность зависит от группы текущего API Key и каталога моделей; поддерживаемые голоса, форматы и параметры скорости определяются фактической моделью.

curl -X POST "$LOCOPAL_BASE_URL/v1/audio/speech" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "从 /v1/models 选择的音频模型 ID",
    "input": "欢迎使用 LocoPal Ai。",
    "voice": "alloy",
    "response_format": "mp3"
  }' \
  --output speech.mp3

Тело успешного ответа — двоичное аудио, а не JSON; в примере оно сохраняется в speech.mp3 через --output. Асинхронные статусы и артефакты других аудиозадач можно посмотреть в «Журнале задач».

Шаг 10: Первый вызов материалов

curl -X POST "$LOCOPAL_BASE_URL/api/v1/materials/groups" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "name": "我的角色素材",
  "description": "视频参考图",
  "type": "virtual"
}
JSON

{
  "code": 0,
  "data": {
    "group": {
      "id": "group-1789069780-5762d1",
      "platform_group_id": "group-1789069780-5762d1",
      "name": "我的角色素材",
      "type": "virtual",
      "description": "视频参考图",
      "created_at": 1789069780,
      "updated_at": 1789069780
    }
  },
  "msg": "素材分组已创建"
}

Сохраните data.group.id, отправьте изображение и опрашивайте статус:

curl -X POST "$LOCOPAL_BASE_URL/api/v1/materials/assets" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"group_id":"group-id","title":"角色正面图","image_url":"https://你的对象存储域名/person.png"}'

curl "$LOCOPAL_BASE_URL/api/v1/materials/assets/asset-id" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

image_url — это адрес http(s), который можно напрямую скачать из публичной сети; также, в пределах ограничений интерфейса, можно передать data_url. Когда data.asset.status станет Active, материал можно использовать в видеозапросах через asset://<asset_id>. Полное описание параметров и ошибок см. в разделе Интерфейсы библиотеки материалов.

Шаг 11: Материалы реальных людей (необязательно)

Материалы реального человека должны быть собраны и авторизованы самим человеком с помощью сканирования QR-кода на телефоне; обычная загрузка изображения не заменяет этот процесс. Процесс в консоли: «Управление библиотекой материалов → Создать группу → Материалы реальных людей → Создать QR-код → человек сканирует код → сканирование завершено, начать синхронизацию»; описание интерфейса см. в разделе Создание сеанса сканирования для реального человека.

Дальнейшие шаги