Saltar al contenido

API · Referencia

Estado de la solicitud

GET /v1/requests/{request_id}/status — una consulta ligera del estado y el progreso de una generación por su request_id. No se necesita ningún permiso adicional de la clave.

Consulte el estado de una generación enviada a partir de su request_id. La llamada es ligera y sirve para consultas frecuentes cuando no usa un webhook.

Playground

GET
/v1/requests/{request_id}/status

Authorization

Authorization<token>

API-ключ в заголовке Authorization со схемой Bearer:

Authorization: Bearer <CLIPIA_API_KEY>

Передавайте полную строку, включая префикс схемы Bearer и пробел. Также принимаются Authorization: Key <ключ> и заголовок X-Api-Key: <ключ> — выбирайте удобную схему. Ключ создаётся в консоли разработчика (clipia.ai/developer, вкладка «API-ключи») и показывается один раз. Формат: clipia_live_… (боевой), clipia_test_… (песочница).

Sandbox / тестовый режим. Ключ с префиксом clipia_test_… работает в песочнице: submit не списывает кредиты и не запускает реальную генерацию — он мгновенно возвращает status: COMPLETED с детерминированным mock-результатом (фиксированный sample-ассет на media.clipia.ai). Поле cost показывает расчётную стоимость, но она не списывается. Вебхуки приходят тем же подписанным механизмом (HMAC-SHA256). Режим предназначен для отладки интеграции до подключения боевого ключа.

In: header

Path Parameters

request_idstringrequired

Идентификатор запроса генерации, полученный при submit.

Formatuuid

Response Body

curl -X GET "https://api.clipia.ai/v1/requests/764cabcf-b745-4b3e-ae38-1200304cf45b/status"

{
  "request_id": "764cabcf-b745-4b3e-ae38-1200304cf45b",
  "status": "IN_PROGRESS",
  "queue_position": null,
  "progress": 45
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_api_key",
    "message": "API-ключ отсутствует, неверный или отозван."
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "not_found",
    "message": "Запрос с таким идентификатором не найден."
  }
}

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after the reset window.",
    "retry_after_seconds": 12
  }
}

GET /v1/requests/:id/status devuelve el estado actual de la generación y, cuando se conoce, su progreso. Sirve cualquier clave válida de la misma cuenta: no se necesita ningún permiso adicional.

GET/v1/requests/:id/status

Solicitud

Prop

Type

curl https://api.clipia.ai/v1/requests/764cabcf-b745-4b3e-ae38-1200304cf45b/status \
  -H "Authorization: Bearer $CLIPIA_KEY"
const status = await clipia.queue.status('764cabcf-b745-4b3e-ae38-1200304cf45b');
console.log(status.status, status.progress);
status = client.status("764cabcf-b745-4b3e-ae38-1200304cf45b")
print(status.status, status.progress)

Respuesta 200

{
  "request_id": "764cabcf-b745-4b3e-ae38-1200304cf45b",
  "status": "IN_PROGRESS",
  "queue_position": 0,
  "progress": 45
}

Prop

Type

Errores

HTTPcodemessageCuándo
400invalid_requestinvalid_request_idel identificador no tiene el formato de un request_id
404not_foundrequest_not_foundla solicitud no existe o pertenece a otra cuenta

Qué llamada usar

/status está pensado para consultas frecuentes. Obtenga los enlaces a los medios con GET /v1/requests/:id. Si pasó un webhook_url al enviar, no necesita hacer consultas: consulte Webhooks. No consulte más de una vez por segundo: estas llamadas cuentan para su límite de solicitudes.

Enviar una generación

POST /v1/models/{model} — ponga en cola una generación de imagen, vídeo o audio, obtenga un request_id y envíe la solicitud directamente desde esta página.

Resultado de la generación

GET /v1/requests/{request_id} — obtenga el resultado terminado con enlaces a la imagen, el vídeo o el audio; mientras el trabajo sigue en curso, la API devuelve 202.