Создание задачи

POST https://gptunnel.ru/api/v2/media/tasks

Единая точка создания задачи для всех медиа-моделей. В ответ приходит объект задачи с идентификатором и статусом — тот же объект отдаёт GET /media/tasks/:id и уходит в webhook.

Request Body

Параметр	Тип	Описание
`model`*	`string`	Идентификатор модели из GET /media/models
`prompt`	`string`	Текстовый промпт. Обязательность зависит от модели (поле prompt в схеме модели: required, optional, none)
`params`	`object`	Параметры генерации согласно схеме params выбранной модели (разрешение, длительность и т.п.)
`inputs`	`object`	Входные файлы по ролям: объект вида { role: [url, ...] }. Ссылки должны быть публично доступны; поддерживаются также data:-URL
`webhook_url`	`string`	URL, на который мы пришлём объект задачи после завершения. См. раздел Webhooks
`idempotency_key`	`string`	Ключ идемпотентности: повторный запрос с тем же ключом вернёт уже созданную задачу, а не создаст новую
`wait`	`boolean`	Если true — дождаться готовности и вернуть финальный объект в ответе (короткое ожидание, см. ниже). По умолчанию false

Параметр `wait`

По умолчанию (wait: false) создание задачи возвращает объект сразу, в статусе queued или running, результат вы получаете через GET /media/tasks/:id или webhook.

Если передать wait: true, запрос будет держать соединение и вернёт задачу, как только она завершится (done или failed). Ожидание ограничено примерно 30 секундами: если за это время задача не завершилась, вернётся объект в текущем статусе (queued / running), и результат нужно получить обычным способом — опросом GET /media/tasks/:id или через webhook.

Ключ идемпотентности

Передавайте idempotency_key, чтобы повторные запросы (ретраи при таймауте сети) не создавали дубли задач и не списывали средства повторно. При повторе с тем же ключом вернётся ранее созданная задача.

Если повторить запрос с тем же idempotency_key, но с другими телом/параметрами, вернётся ошибка 409 (code: 23).

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

curl --request POST \
  --url 'https://gptunnel.ru/api/v2/media/tasks' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "kling-v3",
    "prompt": "a red fox running through snow, cinematic",
    "params": { "resolution": "1080p", "duration": 5, "aspect_ratio": "16:9" },
    "webhook_url": "https://your-service.example/webhooks/gptunnel",
    "idempotency_key": "fox-snow-2026-07-23-001"
  }'

import axios from 'axios'

const { data } = await axios.post(
  'https://gptunnel.ru/api/v2/media/tasks',
  {
    model: 'kling-v3',
    prompt: 'a red fox running through snow, cinematic',
    params: { resolution: '1080p', duration: 5, aspect_ratio: '16:9' },
    webhook_url: 'https://your-service.example/webhooks/gptunnel',
    idempotency_key: 'fox-snow-2026-07-23-001',
  },
  { headers: { Authorization: 'YOUR_API_KEY' } },
)

console.log(data.id, data.status)

import requests

response = requests.post(
    'https://gptunnel.ru/api/v2/media/tasks',
    headers={'Authorization': 'YOUR_API_KEY'},
    json={
        'model': 'kling-v3',
        'prompt': 'a red fox running through snow, cinematic',
        'params': {'resolution': '1080p', 'duration': 5, 'aspect_ratio': '16:9'},
        'webhook_url': 'https://your-service.example/webhooks/gptunnel',
        'idempotency_key': 'fox-snow-2026-07-23-001',
    },
)

print(response.json())

Передача входных файлов

Файлы (изображения, видео, аудио) передаются в inputs по ролям, описанным в схеме модели (inputs[].role). Значение каждой роли — массив ссылок:

{
  "model": "kling-v3",
  "prompt": "animate this photo",
  "inputs": { "first_frame": ["https://example.com/photo.jpg"] }
}

Ссылки должны быть публично доступны нашему серверу. Поддерживаются также data:-URL.

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

{
  "code": 0,
  "id": "6a61e021a6e77553a989c41d",
  "model": "kling-v3",
  "status": "running",
  "prompt": "a red fox running through snow, cinematic",
  "params": { "resolution": "1080p", "duration": 5, "aspect_ratio": "16:9" },
  "price": 210,
  "result": [],
  "webhook": {
    "url": "https://your-service.example/webhooks/gptunnel",
    "status": "pending"
  },
  "created_at": 1784799265
}

Сохраните id — по нему вы получите результат через GET /media/tasks/:id.

Создание задачи