Usage API

A Usage API devolve as tarefas históricas de API da sua equipa, com os créditos consumidos por cada uma. Filtre por período de tempo, endpoint ou estado, e navegue pelos resultados através de paginação para exportar em massa.

Disponibilidade. A chave de API tem de pertencer a uma equipa Studio ou Enterprise; chaves de qualquer outro plano, ou sem equipa associada, recebem um 403.

GET/openapi/v1/usage/tasks

List Usage Records

Devolve uma página das tarefas de API da equipa, das mais recentes para as mais antigas. Sem um intervalo de tempo explícito, a resposta abrange os últimos 30 dias.

Parâmetros

Name
page_num
Type
integer
predefinição 1
Description
Número da página para paginação.
Name
page_size
Type
integer
predefinição 10
Description
Limite do tamanho da página. O máximo permitido é 100 itens.
Name
sort_by
Type
string
predefinição -created_at
Description
Campo pelo qual ordenar.
Valores disponíveis:
- +created_at: Ordenar por hora de criação em ordem ascendente.
- -created_at: Ordenar por hora de criação em ordem descendente.
Name
start_time
Type
string
Description
Início do intervalo created_at, como um carimbo de data/hora RFC 3339 (por exemplo, 2026-08-01T00:00:00Z). O valor predefinido é 30 dias antes de end_time. O intervalo pode abranger, no máximo, 1 ano — para exportações maiores, navegue por intervalos consecutivos através de paginação.
Name
end_time
Type
string
Description
Fim do intervalo created_at, como um carimbo de data/hora RFC 3339. O valor predefinido é a hora atual.
Name
endpoints
Type
string
Description
Lista separada por vírgulas dos nomes de endpoints a incluir. Aceita os mesmos valores presentes no campo de resposta endpoint — text-to-3d, text-to-3d-preview, text-to-3d-refine, image-to-3d, multi-image-to-3d, retexture, remesh, convert, resize, uv-unwrap, rig, animate, text-to-motion, text-to-image, image-to-image, print-multi-color, print-repair, print-analyze, print-split — em que text-to-3d é um termo abrangente que cobre tanto a fase de preview como a fase de refine. Omita para incluir todos os endpoints.
Name
status
Type
string
Description
Filtrar pelo estado final da tarefa: SUCCEEDED ou FAILED. Omita para incluir ambos.

Devolve

Devolve uma lista paginada de Objetos de Registo de Utilização.

Os registos abrangem tarefas que atingiram um estado final. Os créditos são cobrados quando uma tarefa é criada, por isso uma tarefa ainda em execução no momento da exportação ainda não consta nos resultados desse intervalo — volte a extrair os intervalos mais recentes (ou exporte com um pequeno atraso) se os seus totais tiverem de corresponder exatamente ao seu saldo de créditos.

As equipas com uma política de retenção de dados personalizada recebem registos dentro do respetivo período de retenção configurado.

Request

GET

/openapi/v1/usage/tasks

curl "https://api.meshy.ai/openapi/v1/usage/tasks?page_size=50&start_time=2026-08-01T00:00:00Z&end_time=2026-09-01T00:00:00Z" \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "endpoint": "image-to-3d",
    "status": "SUCCEEDED",
    "created_at": 1755787000000,
    "finished_at": 1755787045000,
    "consumed_credits": 20,
    "api_key_name": "production",
    "api_key_suffix": "a1b2"
  },
  {
    "task_id": "018a210d-1c22-7e0f-9d3a-4a5b6c7d8e9f",
    "endpoint": "text-to-3d-refine",
    "status": "FAILED",
    "created_at": 1755786000000,
    "finished_at": 1755786030000,
    "consumed_credits": 0,
    "api_key_name": "production",
    "api_key_suffix": "a1b2"
  }
]

The Usage Record Object

Name
task_id
Type
string
Description
ID da tarefa que este registo fatura — o mesmo ID que o endpoint de criação devolveu. Para obter a própria tarefa (incluindo o seu modelo de saída ou URLs de imagem, novamente assinados em cada leitura), passe-o para o endpoint de obtenção correspondente, por exemplo, GET /openapi/v1/{endpoint}/{task_id}.
Name
endpoint
Type
string
Description
O endpoint em que a tarefa foi executada, por exemplo, image-to-3d ou text-to-3d-refine. As tarefas de Texto para 3D indicam a sua fase (text-to-3d-preview / text-to-3d-refine).
Name
status
Type
string
Description
Estado final da tarefa: SUCCEEDED ou FAILED.
Name
created_at
Type
timestamp
Description
Carimbo de data/hora da criação da tarefa, em milissegundos.
Name
finished_at
Type
timestamp
Description
Carimbo de data/hora da conclusão, em milissegundos. null se a tarefa não tiver uma hora de conclusão.
Name
consumed_credits
Type
integer
Description
Créditos consumidos por esta tarefa. Devolve 0 para tarefas FAILED (os créditos são reembolsados em caso de falha).
Name
api_key_name
Type
string
Description
Nome de exibição da chave de API que executou a tarefa. Permanece preenchido para chaves revogadas, pelo que o gasto histórico continua atribuível após a rotação de chaves.
Name
api_key_suffix
Type
string
Description
Últimos quatro caracteres dessa chave de API, para distinguir chaves com o mesmo nome.

Example Usage Record Object

{
  "task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "endpoint": "image-to-3d",
  "status": "SUCCEEDED",
  "created_at": 1755787000000,
  "finished_at": 1755787045000,
  "consumed_credits": 20,
  "api_key_name": "production",
  "api_key_suffix": "a1b2"
}