API для редактирования и работы с фото

Базовый URL

/api/trytry/partner/v1/

Аутентификация

Все эндпоинты требуют передачи apiToken в заголовках запроса:

apiToken: <ваш-api-token>

Если токен не передан или неверный, API вернёт:

Status: 401 Unauthorized
{
  "error": "apiToken required" // или "Invalid apiToken"
}

Эндпоинты

1. POST /image-to-image

Описание: Обработка изображений: улучшение, редактирование, удаление объекта, удаление фона.

Параметры запроса:

• Content-Type: multipart/form-data (для загрузки файла) или application/json (для fileURL(s))
• Обязательное поле: один из file, fileURL, либо fileURLs (массив до 4 ссылок)
• Обязательное поле: type (строка, варианты: enhance, edit, remove-object, remove-bg)
• Необходимо: prompt (строка, обязательно для edit и remove-object)
• Необязательно: externalID (строка)

Примеры тела запроса:

• Улучшение:

{
  "type": "enhance",
  "fileURL": "https://..."
}

• Редактирование:

{
  "type": "edit",
  "prompt": "Добавить очки",
  "fileURL": "https://..."
}

• Удаление объекта:

{
  "type": "remove-object",
  "prompt": "кошка",
  "fileURL": "https://..."
}

• Удаление фона:

{
  "type": "remove-bg",
  "fileURL": "https://..."
}

• Несколько изображений (только для edit):

{
  "type": "edit",
  "prompt": "Мужчина и женщина улыбаются у рождественской елки",
  "fileURLs": ["https://...", "https://..."]
}

Успешный ответ:

Status: 200 OK
{
  "status": "succeeded",
  "resultURL": "https://yccdn.facee.ru/...",
  "microCentsLeft": 123456
}

Возможные ошибки:

• Нет/неверный токен:
  • 401, { "error": "apiToken required" } или { "error": "Invalid apiToken" }
• Нет файла или ссылки:
  • 400, { "error": "One of the fields: file or fileURL or fileURLs is required" }
• Неверный type:
  • 400, { "status": "error", "error": "Invalid type" }
• Нет prompt (edit/remove-object):
  • 400, { "status": "error", "error": "Prompt is required for edit type" }
• Некорректный массив fileURLs:
  • 400, { "error": "fileURLs must contain between 1 and 4 URLs" }
  • 400, { "error": "fileURLs must be a JSON array of valid image URLs" }
• Ошибка загрузки/обработки изображения:
  • 400/500, { "status": "error", "error": "Failed to fetch image from provided URL" }
  • 500, { "status": "error", "error": "Failed to process image" }
  • 500, { "status": "error", "error": "Failed to enhance image (AI)" }
  • 500, { "status": "error", "error": "Failed to edit image (AI)" }
  • 500, { "status": "error", "error": "Failed to remove object (AI)" }
  • 500, { "status": "error", "error": "Failed to remove bg (AI)" }

2. POST /image-to-text

Описание: Генерация текстового описания или оценки калорийности/БЖУ по изображению.

Параметры запроса:

• Content-Type: multipart/form-data (для файла) или application/json (для fileURL)
• Обязательное поле: один из file или fileURL
• Необязательное: describeType (строка, если calories — будет оценка калорийности)
• Необязательное: externalID (строка)

Примеры тела запроса:

• Описание:

{
  "fileURL": "https://..."
}

• Калории/БЖУ:

{
  "fileURL": "https://...",
  "describeType": "calories"
}

Успешный ответ:

Status: 200 OK
{
  "status": "succeeded",
  "text": "...описание или калорийность...",
  "tokensLeft": 12345
}

Возможные ошибки:

• Нет/неверный токен:
  • 401, { "error": "apiToken required" } или { "error": "Invalid apiToken" }
• Нет файла или ссылки:
  • 400, { "error": "One of the fields: file or fileURL or fileURLs is required" }
• Ошибка загрузки/обработки изображения:
  • 400/500, { "status": "error", "error": "Failed to fetch image from provided URL" }
  • 500, { "status": "error", "error": "Failed to extract text from image" }

Демо-эндпоинты

Для тестирования можно использовать демо-роутер:

/api/trytry/partner/v1/demo/

• Используйте apiToken: test-token в заголовках
• Эндпоинты:
  • POST /image-to-image — всегда возвращает фиксированный demo-результат
  • POST /image-to-text — возвращает фиксированный текст (описание или калории)

Примечания

• Все ответы — в формате JSON.
• Все ссылки на изображения должны быть доступны серверу Facee.
• Для edit и remove-object поле prompt — короткое описание на русском (будет переведено автоматически).
• Для fileURLs поддерживается до 4 изображений (только для edit).
• В случае ошибки всегда возвращается status: "error" и поле error с описанием.

Пример демо-запроса cURL

curl -X POST https://facee.ru/api/trytry/partner/v1/demo/image-to-image \
  -H "apiToken: test-token" \
  -F "type=enhance" \
  -F "fileURL=https://ycfiles.facee.ru/api/try-on/files/c9bd22bc-3809-4176-923b-1ae5f94e3ba1"

Чтобы подключиться к нашему API, обратитесь к нам по адресу facee.ru.help@gmail.com