Главная / Информация

API Image to Text — Инструкция

API Host Company

2024-03-11

Для доступа к API необходимо пополнить баланс и скопировать Api_key из меню настроек в личном кабинете.
(Меню с настройками доступно только в ПК версии сайта.)

Стоимость использования согласно общим тарифам — 6 руб. за запрос.
API-ключ не имеет срока действия для простоты аутентификации, но в целях безопасности есть возможность перегенерировать ключ в личном кабинете.
Полученный API-ключ указывается в header запроса для дальнейшей работы.

Оглавление

Кастомный запрос к изображению
Схема работы API
Примеры
Частые коды и состояния

Кастомный запрос к изображению

В некоторых ситуациях может потребоваться получение более краткого изложения или, напротив, подробной статьи, выполнение подсчета объектов, определение цветов итд.
Для этих целей предусмотрена возможность использования параметра запроса ‘text’, который позволяет задать конкретные инструкции по обработке информации, извлеченной из изображения.

Пример такой инструкции может звучать следующим образом: «Составьте статью на основе данных, полученных из изображения, объемом от 3 до 5 абзацев, в нарративном стиле. Сделай список преимуществ товара представленного на изображении».
Этот подход позволяет гибко адаптировать вывод информации к вашим потребностям.

Схема работы API

Обработка асинхронная: вы отправляете задачу на распознавание (эндпоинт create) и периодически опрашиваете её состояние (эндпоинт check). Как только задача готова — получите текст и, при успешном платном завершении, актуальный баланс.

Этап	Метод / эндпоинт	Что происходит
Создать задачу	POST `/api/vision/create.php` HTTP 200 всегда	Создаёт задачу распознавания изображения и возвращает `task_id`. В ответе всегда есть поля `status`, `http_code`, `task_id`, `status_text`, `image_url`, `balance` (при успешном списании).
Параметры запроса	`upfile` `image_url` `text` (опц.)	`upfile` — файл изображения (`multipart/form-data`) или `image_url` — публичная HTTPS-ссылка на изображение `text` — (необязательный) промпт/инструкция до 2000 символов Достаточно одного из: `upfile` или `image_url`.
Ответ на create	JSON HTTP 200, см. поле `http_code`	Пример структуры: `status` — true/false `http_code` — бизнес-код (обычно `202` при постановке в очередь) `task_id` — идентификатор задачи `status_text` — например, `queued` `image_url` — сохранённая ссылка `balance` — текущий баланс (если списание прошло успешно)
Проверить статус	GET `/api/vision/check.php?task_id={ID}` HTTP 200 всегда	Возвращает текущий статус задачи по `task_id`. Вызывается с интервалом ~1–2 секунды, пока задача не перейдёт в финальное состояние.
Ответ на check	JSON ключевые поля:	`task.status`: `queued` \| `processing` \| `ok` \| `moderation_blocked` \| `model_filtered` \| `empty` \| `gateway_error` и др. `http_code` — бизнес-состояние: `202` (ждём), `200` (успех), `409`/`400` (контент/модерация), `402` (нет средств) и т.п. `data.text` — итоговый текст (когда `status=ok`) `balance` — возвращается только при `status=ok`

Rate-limit: 1 запрос создания в ~2 секунды на пользователя (защита от DDoS). Максимальный размер файла — 20 МБ, форматы: JPEG/PNG/JPEG.

Примеры

1) Быстрый старт (curl)

Файл:

curl -X POST "https://apihost.ru/api/vision/create.php" \
  -H "Authorization: Bearer &lt;API_KEY&gt;" \
  -F "text=Сосчитай количество людей на фото и опиши одежду" \
  -F "upfile=@/path/to/image.jpg"

# ⇒ {"status":true,"http_code":202,"task_id":87,"status_text":"queued",...}

# Проверка:
curl -X GET "https://apihost.ru/api/vision/check.php?task_id=87" \
  -H "Authorization: Bearer &lt;API_KEY&gt;"

curl -X POST "https://apihost.ru/api/vision/create.php" \

-H "Authorization: Bearer <API_KEY>" \

-F "text=Сосчитай количество людей на фото и опиши одежду" \

-F "upfile=@/path/to/image.jpg"

# ⇒ {"status":true,"http_code":202,"task_id":87,"status_text":"queued",...}

# Проверка:

curl -X GET "https://apihost.ru/api/vision/check.php?task_id=87" \

-H "Authorization: Bearer <API_KEY>"

URL:

curl -X POST "https://apihost.ru/api/vision/create.php" \
  -H "Authorization: Bearer &lt;API_KEY&gt;" \
  -F "image_url=https://example.com/pic.png" \
  -F "text=Коротко: что на изображении?"

# затем GET /check.php?task_id=...

curl -X POST "https://apihost.ru/api/vision/create.php" \

-H "Authorization: Bearer <API_KEY>" \

-F "image_url=https://example.com/pic.png" \

-F "text=Коротко: что на изображении?"

# затем GET /check.php?task_id=...

2) Пример Google Colab (Python)

Ниже — готовый Colab-скрипт: загружает файл или берёт image_url, создаёт задачу и опрашивает статус. Ссылка на Google Colab с рабочим примером.

# -*- coding: utf-8 -*-
import time, json, requests

API_KEY = "PASTE_YOUR_API_KEY"  # замените на ключ из кабинета
CREATE_URL = "https://apihost.ru/api/vision/create.php"
CHECK_URL  = "https://apihost.ru/api/vision/check.php"

headers = {"Authorization": f"Bearer {API_KEY}"}

# --- Вариант 1: загрузка файла из Colab ---
# !wget -O /content/sample.jpg "https://.../image.jpg"
file_path = "/content/sample.jpg"  # укажите реальный путь или None

# --- Вариант 2: публичная HTTPS-ссылка ---
image_url = ""  # например: "https://example.com/image.png"

data = {"text": "Сделай краткое описание и укажи основные цвета"}

files = None
if file_path:
    files = {"upfile": open(file_path, "rb")}
    resp = requests.post(CREATE_URL, headers=headers, data=data, files=files)
    files["upfile"].close()
else:
    data["image_url"] = image_url
    resp = requests.post(CREATE_URL, headers=headers, data=data)

create = resp.json()
print("CREATE:", json.dumps(create, ensure_ascii=False, indent=2))

if not create.get("status"):
    raise RuntimeError("Create failed: " + create.get("message",""))

task_id = create.get("task_id")
if not task_id:
    raise RuntimeError("No task_id in response")

# Поллинг статуса
while True:
    ck = requests.get(CHECK_URL, headers=headers, params={"task_id": task_id}).json()
    st = ck.get("task", {}).get("status")
    print("STATUS:", st, "http_code:", ck.get("http_code"))
    if st in ("queued", "processing"):
        time.sleep(1.2)
        continue
    # Готово / финальное состояние
    print(json.dumps(ck, ensure_ascii=False, indent=2))
    if st == "ok":
        print("\n=== RESULT TEXT ===\n", ck.get("data", {}).get("text", ""))
        print("Balance:", ck.get("balance"))
    else:
        print("\nFinished with status:", st, "— see fields 'http_code' and 'moderation' if present.")
    break

				
					
				1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53

						# -*- coding: utf-8 -*-
import time, json, requests
 
API_KEY = "PASTE_YOUR_API_KEY"  # замените на ключ из кабинета
CREATE_URL = "https://apihost.ru/api/vision/create.php"
CHECK_URL  = "https://apihost.ru/api/vision/check.php"
 
headers = {"Authorization": f"Bearer {API_KEY}"}
 
# --- Вариант 1: загрузка файла из Colab ---
# !wget -O /content/sample.jpg "https://.../image.jpg"
file_path = "/content/sample.jpg"  # укажите реальный путь или None
 
# --- Вариант 2: публичная HTTPS-ссылка ---
image_url = ""  # например: "https://example.com/image.png"
 
data = {"text": "Сделай краткое описание и укажи основные цвета"}
 
files = None
if file_path:
    files = {"upfile": open(file_path, "rb")}
    resp = requests.post(CREATE_URL, headers=headers, data=data, files=files)
    files["upfile"].close()
else:
    data["image_url"] = image_url
    resp = requests.post(CREATE_URL, headers=headers, data=data)
 
create = resp.json()
print("CREATE:", json.dumps(create, ensure_ascii=False, indent=2))
 
if not create.get("status"):
    raise RuntimeError("Create failed: " + create.get("message",""))
 
task_id = create.get("task_id")
if not task_id:
    raise RuntimeError("No task_id in response")
 
# Поллинг статуса
while True:
    ck = requests.get(CHECK_URL, headers=headers, params={"task_id": task_id}).json()
    st = ck.get("task", {}).get("status")
    print("STATUS:", st, "http_code:", ck.get("http_code"))
    if st in ("queued", "processing"):
        time.sleep(1.2)
        continue
    # Готово / финальное состояние
    print(json.dumps(ck, ensure_ascii=False, indent=2))
    if st == "ok":
        print("\n=== RESULT TEXT ===\n", ck.get("data", {}).get("text", ""))
        print("Balance:", ck.get("balance"))
    else:
        print("\nFinished with status:", st, "— see fields 'http_code' and 'moderation' if present.")
    break

					

			

3) Готовый пример на PHP

&lt;?php
$API_KEY = 'PASTE_YOUR_API_KEY';
$CREATE  = 'https://apihost.ru/api/vision/create.php';
$CHECK   = 'https://apihost.ru/api/vision/check.php';

function http_post_multipart($url, $headers, $fields, $files = []) {
  $ch = curl_init($url);
  $hdr = [];
  foreach ($headers as $k=>$v) $hdr[] = $k.': '.$v;
  $payload = $fields;
  foreach ($files as $name=>$path) {
    $payload[$name] = new CURLFile($path);
  }
  curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => $hdr,
    CURLOPT_POSTFIELDS => $payload,
    CURLOPT_TIMEOUT => 60,
  ]);
  $resp = curl_exec($ch);
  if ($resp === false) throw new Exception('curl: '.curl_error($ch));
  curl_close($ch);
  return $resp;
}

function http_get($url, $headers, $query=[]) {
  $q = $query ? ('?'.http_build_query($query)) : '';
  $ch = curl_init($url.$q);
  $hdr = [];
  foreach ($headers as $k=>$v) $hdr[] = $k.': '.$v;
  curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => $hdr,
    CURLOPT_TIMEOUT => 30,
  ]);
  $resp = curl_exec($ch);
  if ($resp === false) throw new Exception('curl: '.curl_error($ch));
  curl_close($ch);
  return $resp;
}

$headers = ['Authorization' => 'Bearer '.$API_KEY];

/* Вариант с файлом */
$fields = ['text' => 'Опиши изображение кратко пунктами'];
$files  = ['upfile' => '/home/user/Pictures/photo.jpg']; // путь к файлу

$createJson = http_post_multipart($CREATE, $headers, $fields, $files);
$create = json_decode($createJson, true);
if (!$create || empty($create['status'])) { die("Create failed:\n".$createJson); }

$taskId = $create['task_id'] ?? null;
if (!$taskId) die("No task_id\n");

do {
  usleep(1200*1000);
  $checkJson = http_get($CHECK, $headers, ['task_id'=>$taskId]);
  $check = json_decode($checkJson, true);
  $st = $check['task']['status'] ?? '';
  echo "Status: $st (http_code=".$check['http_code'].")\n";
} while (in_array($st, ['queued','processing']));

if ($st === 'ok') {
  echo "\n=== RESULT ===\n".$check['data']['text']."\n";
  if (isset($check['balance'])) echo "Balance: ".$check['balance']."\n";
} else {
  echo "\nFinished with status: $st\n".$checkJson."\n";
}

				
					
				1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69

						&lt;?php
$API_KEY = 'PASTE_YOUR_API_KEY';
$CREATE  = 'https://apihost.ru/api/vision/create.php';
$CHECK   = 'https://apihost.ru/api/vision/check.php';
 
function http_post_multipart($url, $headers, $fields, $files = []) {
  $ch = curl_init($url);
  $hdr = [];
  foreach ($headers as $k=>$v) $hdr[] = $k.': '.$v;
  $payload = $fields;
  foreach ($files as $name=>$path) {
    $payload[$name] = new CURLFile($path);
  }
  curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => $hdr,
    CURLOPT_POSTFIELDS => $payload,
    CURLOPT_TIMEOUT => 60,
  ]);
  $resp = curl_exec($ch);
  if ($resp === false) throw new Exception('curl: '.curl_error($ch));
  curl_close($ch);
  return $resp;
}
 
function http_get($url, $headers, $query=[]) {
  $q = $query ? ('?'.http_build_query($query)) : '';
  $ch = curl_init($url.$q);
  $hdr = [];
  foreach ($headers as $k=>$v) $hdr[] = $k.': '.$v;
  curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => $hdr,
    CURLOPT_TIMEOUT => 30,
  ]);
  $resp = curl_exec($ch);
  if ($resp === false) throw new Exception('curl: '.curl_error($ch));
  curl_close($ch);
  return $resp;
}
 
$headers = ['Authorization' => 'Bearer '.$API_KEY];
 
/* Вариант с файлом */
$fields = ['text' => 'Опиши изображение кратко пунктами'];
$files  = ['upfile' => '/home/user/Pictures/photo.jpg']; // путь к файлу
 
$createJson = http_post_multipart($CREATE, $headers, $fields, $files);
$create = json_decode($createJson, true);
if (!$create || empty($create['status'])) { die("Create failed:\n".$createJson); }
 
$taskId = $create['task_id'] ?? null;
if (!$taskId) die("No task_id\n");
 
do {
  usleep(1200*1000);
  $checkJson = http_get($CHECK, $headers, ['task_id'=>$taskId]);
  $check = json_decode($checkJson, true);
  $st = $check['task']['status'] ?? '';
  echo "Status: $st (http_code=".$check['http_code'].")\n";
} while (in_array($st, ['queued','processing']));
 
if ($st === 'ok') {
  echo "\n=== RESULT ===\n".$check['data']['text']."\n";
  if (isset($check['balance'])) echo "Balance: ".$check['balance']."\n";
} else {
  echo "\nFinished with status: $st\n".$checkJson."\n";
}

					

			

Частые коды и состояния

http_code=202 — задача в очереди/обработке (task.status: queued/processing)
http_code=200 — готово (task.status=ok), текст в data.text, актуальный баланс в balance
http_code=409/400 — модерация/фильтр модели/пустой результат (см. moderation, task.finish)
http_code=402 — недостаточно средств
http_code=502..504 — временная перегрузка шлюза; повторите запрос

Примечание: HTTP ответа сервера всегда 200 — это упрощает работу клиентов. Реальный «деловой» статус возвращается в JSON-поле http_code.