Документация Толоки

Создать одно или несколько заданий

Важно

Домен toloka.yandex.com работает в режиме deprecated. Рекомендуем переключиться на домен toloka.dev для запросов API.

Создает одно или несколько заданий.

Вы можете создать не более 100 000 заданий в минуту и не более 2 000 000 в день.

Запрос

POST https://toloka.dev/api/v1/tasks
Authorization: OAuth <OAuth token>
Content-Type: application/JSON

// одно задание
{task data}

// или несколько заданий
[{task 1}, {task 2},... {task n}]

POST https://sandbox.toloka.dev/api/v1/tasks
Authorization: OAuth <OAuth token>
Content-Type: application/JSON

// одно задание
{task data}

// или несколько заданий
[{task 1}, {task 2},... {task n}]

Заголовки

Заголовок Описание
Authorization Токен для авторизации аккаунта. В качестве префикса добавьте OAuth.
Content-Type Указывает формат данных в передаваемом теле запроса.

Query-параметры

Указываются в ссылке после знака вопроса, перечисляются через &.

Параметр

Описание

async_mode

boolean

Способ обработки запроса:

  • true — отложенный. В результате запроса создается асинхронная операция, выполняемая в фоновом режиме. Ответ содержит сведения об операции (время начала и окончания, статус, количество страниц заданий).
  • false — синхронный. Ответ содержит сведения об одном или о нескольких созданных заданиях. В одном запросе можно отправить не более 5000 заданий.

По умолчанию значение false.

allow_defaults

boolean

Настройки перекрытия:

  • true — использовать перекрытие, указанное в параметрах пула (ключ defaults.default_overlap_for_new_tasks).
  • false — использовать перекрытие, указанное в параметрах заданий (поле overlap)

overlap (string | обязательный при условии — обязателен, если при создании заданий не используется параметр allow_defaults=true и перекрытие не указано в параметрах пула (ключ defaults.default_overlap_for_new_tasks). Перекрытие задания).

По умолчанию значение false.

skip_invalid_items

boolean

Параметры валидации JSON-объектов:

  • true — создать задания, прошедшие валидацию. Остальные задания пропустить (ошибки будут перечислены в ответе на запрос).
  • false — остановить операцию и не создавать задания, если хотя бы одно из них не прошло валидацию.

По умолчанию значение false.

open_pool

boolean

Открыть пул сразу после завершения операции, если пул закрыт. По умолчанию значение false.

operation_id

string

Идентификатор операции для отложенной загрузки одного или нескольких заданий (при значении async_mode=true).

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

Идентификатор должен соответствовать стандарту RFC4122.

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

Тело запроса

{
  "pool_id": "1",
  "input_values": {
    "image_url": "www.images/image1.ru"
  },
  "known_solutions": [
    {
      "output_values": {
        "result": "OK",
        "like": false
      },
      "correctness_weight": 0.8
    },
    {
      "output_values": {
        "result": "OK",
        "like": true
      },
      "correctness_weight": 1
    }
  ],
  "baseline_solutions": [
    {
      "output_values": {
        "result": "OK",
        "like": false
      },
      "confidence_weight": 0.8
    },
    {
      "output_values": {
        "result": "OK",
        "like": true
      },
      "confidence_weight": 1
    }
  ],
  "message_on_unknown_solution": "The cat is in a good mood.",
  "overlap": 3,
  "infinite_overlap": false,
  "reserved_for": [],
  "unavailable_for": []
}

Ключ

Описание

pool_id

string | обязательный

Идентификатор пула, в который загружается задание.

input_values

object | обязательный

Входные данные для задания. Список пар:

"<id поля 1>": "<значение поля 1>",
"<id поля 2>": "<значение поля 2>",
...
 "<id поля n>": "<значение поля n>"

known_solutions[].output_values

object | обязательный

Значения выходных данных для проверки. Надо задать значения для всех обязательных полей выходных данных.

"<id поля 1>": "<правильный ответ>",
"<id поля 2>": "<правильный ответ>",
...

baseline_solutions[].output_values

object | обязательный

Значения выходных данных для предварительных ответов.

"<id поля 1>": "<предварительный ответ>",
"<id поля 2>": "<предварительный ответ>",
...

baseline_solutions[].confidence_weight

float | обязательный

Уверенность в ответе, в диапазоне от 0 до 1.

Значение по умолчанию 1.

overlap

string | обязательный при условии

Обязателен, если при создании заданий не используется параметр allow_defaults=true и перекрытие не указано в параметрах пула (ключ defaults.default_overlap_for_new_tasks).

Перекрытие задания.

known_solutions[]

array of objects

Правильные ответы для контрольных и тренировочных заданий.

Можно указать несколько вариантов правильного ответа на задание.

Если один вариант правильнее другого, вы можете присваивать вариантам ответов разный вес. Для этого используйте ключ correctness_weight.

  • Контрольный задания — задания с правильными ответами. Используются для контроля качества ответов.
  • Тренировочные задания — задания для обучения исполнителей. Тренировочные задания содержат правильные ответы и подсказки. Если исполнитель отвечает неправильно, на экран выводится подсказка. Исполнитель не может перейти к следующему заданию, пока не введет правильный ответ.

known_solutions[].correctness_weight

float

Вес правильного ответа, в диапазоне от 0 до 1.

Позволяет засчитать ответ как частично правильный. Это удобно, когда на задание нет одного однозначно правильного ответа.

Это работает как начисление баллов: если для получения навыка надо выполнить одно контрольное задание правильно (набрать 1 балл), то можно выполнить правильно одно задание с весом 1 или два задания с весом 0.5 и больше.

Значение по умолчанию 1.

baseline_solutions[]

array of objects

Предварительные ответы. Эти данные имитируют ответы исполнителей при расчете уверенности в ответе ( confidence). Они используются в динамическом перекрытии (incremental relabeling, IRL) и в агрегации результатов по навыку.

Для каждого предварительного ответа нужно определить значения выходных данных (output_values) и уверенность в ответе (confidence_weight).

Допустим, в задании вы просите исполнителя определить, что на изображении: кошка или собака. И допустим, ваша нейронная сеть уже определила, что на изображении может быть собака с вероятностью 80%, кошка с уверенностью 40%. Допустим, указано динамическое перекрытие от 1 до 3, а минимальная уверенность в ответе — 85%.

Если исполнитель ответит "Собака" и уверенность в его ответе высокая, то скорее всего перекрытие не будет повышаться — хватит одного ответа. Если исполнитель ответит "Кошка", то уверенности скорее всего не хватит и перекрытие будет повышаться и дальше.

Нельзя использовать при создании страницы заданий — в ответе на запрос будет ошибка с кодом 400 и пометкой VALUE_NOT_ALLOWED.

message_on_unknown_solution

string

Подсказка к заданию (для тренировочных заданий).

infinite_overlap

boolean

Выдача задания с бесконечным перекрытием. Используется, например, для обучающих заданий, чтобы выдать их всем исполнителям:

  • true — установить бесконечное перекрытие;
  • false — оставить перекрытие, указанное для задания или пула.<

По умолчанию значение false.

origin_task_id

string

Идентификатор задания, с которого оно скопировано.

reserved_for[]

array of strings

Идентификаторы исполнителей, которым задание будет доступно.

unavailable_for[]

array of strings

Идентификаторы исполнителей, для которых задание должно быть недоступно.

Ответ

Одно задание

async_mode — boolean

Способ обработки запроса:

  • true — отложенный. В результате запроса создается асинхронная операция, выполняемая в фоновом режиме. Ответ содержит сведения об операции (время начала и окончания, статус, количество страниц заданий).
  • false — синхронный. Ответ содержит сведения об одном или о нескольких созданных заданиях. В одном запросе можно отправить не более 5000 заданий.

По умолчанию значение false.

В зависимости от значения параметра async_mode в запросе ответ содержит:

Сведения о созданном задании. Помимо параметров, которые задаются при создании задания, включает параметры, которые присваиваются заданию автоматически:

Параметр

Описание

id

string

Идентификатор задания.

origin_task_id

string

Идентификатор задания из другого пула, с которого было скопировано это задание, для проверки мнением большинства.

created

string

Дата и время создания страницы заданий по UTC в формате ISO 8601 YYYY-MM-DDThh:mm:ss[.sss].

 
{
  "id": "2ed92b7f-75c0-4771-ae2f-3911232d6d4e",
  "type": "TASK.BATCH_CREATE",
  "status": "RUNNING",
  "submitted": "2020-12-23T16:26:20.131",
  "progress": 0,
  "parameters": {
      "open_pool": false,
      "allow_defaults": false,
      "skip_invalid_items": false
  }
}

Параметр

Описание

id

string

Идентификатор операции.

type

string

Тип операции: TASK.BATCH_CREATE — создание нескольких заданий.

status

string

Статус операции:

  • PENDING — выполнение не началось.
  • RUNNING — выполняется.
  • SUCCESS — успешно выполнена.
  • FAIL — не выполнена.

submitted

string

Дата и время отправки запроса по UTC в формате ISO 8601: YYYY-MM-DDThh:mm:ss[.sss].

progress

integer

Ход выполнения операции в процентах.

parameters

object

Параметры операции (зависят от типа операции).

parameters.open_pool

boolean

Открыть пул сразу после создания заданий, если пул закрыт. По умолчанию значение false.

parameters.allow_defaults

boolean

Настройки перекрытия:

  • true — использовать перекрытие, указанное в параметрах пула (ключ defaults.default_overlap_for_new_tasks).
  • false — использовать перекрытие, указанное в параметрах заданий (поле overlap).

По умолчанию значение false.

parameters.skip_invalid_items

boolean

Параметры валидации JSON-объектов:

  • true — создать задания, прошедшие валидацию. Остальные задания пропустить (ошибки будут перечислены в ответе на запрос).
  • false — остановить операцию и не создавать задания, если хотя бы одно из них не прошло валидацию.

По умолчанию значение false.
Несколько заданий
{
  "items": {
    "0": {
      "id": "f432cac2-7184-47a3-8220-12ce362cb208",
      "pool_id": "21",
      "input_values": {
        "image": "http://images.com/1.png"
      },
      "overlap": 3,
      "created": "2016-09-29T18:04:00"
    }
  },
  "validation_errors": {
    "1": {
      "input_values.image": {
        "code": "VALUE_REQUIRED",
        "message": "Value must be present and not equal to null"
      }
    }
  }
}

Параметр

Описание

items

object

Объект с созданными заданиями.

object

Порядковый номер задания в массиве при создании (начиная с 0).

id

string

Идентификатор задания.

pool_id

string

Идентификатор пула, в который было загружено задание.

overlap

string

Перекрытие страницы заданий.

created

string

Дата и время создания страницы заданий по UTC в формате ISO 8601 YYYY-MM-DDThh:mm:ss[.sss].

validation_errors

object

Объект с ошибками в заданиях. Возвращается, если в запросе используется параметр skip_invalid_items=true.

 
{
  "id": "26e130ad3652443a3dc5094791e48ef9",
  "type": "TASK.BATCH_CREATE",
  "status": "FAIL",
  "submitted": "2015-12-13T23:32:01",
  "started": "2015-12-13T23:33:00",
  "finished": "2015-12-13T23:34:12",
  "parameters": {
    "allow_defaults": false,
    "skip_invalid_items": false,
    "open_pool": false
  },
  "details": {
    "total_count": 2,
    "valid_count": 1,
    "not_valid_count": 1,
    "success_count": 0,
    "failed_count": 2
  }
}

Параметр

Описание

id

string

Идентификатор операции.

type

string

Тип операции: TASK.BATCH_CREATE — создание нескольких заданий.

status

string

Статус операции:

  • PENDING — выполнение не началось.
  • RUNNING — выполняется.
  • SUCCESS — успешно выполнена.
  • FAIL — не выполнена.

submitted

string

Дата и время отправки запроса по UTC в формате ISO 8601: YYYY-MM-DDThh:mm:ss[.sss].

started

string

Дата и время начала операции по UTC в формате ISO 8601: YYYY-MM-DDThh:mm:ss[.sss].

finished

string

Дата и время окончания операции по UTC в формате ISO 8601: YYYY-MM-DDThh:mm:ss[.sss].

parameters.skip_invalid_items

boolean

Параметры валидации JSON-объектов:

  • true — создать задания, прошедшие валидацию. Остальные задания пропустить.
  • false — остановить операцию и не создавать задания, если хотя бы одно из них не прошло валидацию.

По умолчанию значение false.

details.total_count

string

Количество заданий в запросе.

details.valid_count

integer

Количество заданий, которые прошли валидацию.

details.not_valid_count

integer

Количество заданий, которые не прошли валидацию.

details.success_count

integer

Количество загруженных заданий.

details.failed_count

integer

Количество заданий, которые не были загружены.
В этой статье: