API de Utilização

A API de Utilização devolve as tarefas históricas da API da sua equipa, com os créditos que cada uma consumiu. Filtre por janela temporal, endpoint ou estado, e percorra os resultados por páginas para exportar em massa.

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

GET/openapi/v1/usage/tasks

Listar Registos de Utilização

Devolve uma página das tarefas da 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 de 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 da janela created_at, como um carimbo de data/hora RFC 3339 (p. ex. 2026-08-01T00:00:00Z). Por predefinição, 30 dias antes de end_time. A janela pode abranger, no máximo, 1 ano — para exportações maiores, percorra janelas consecutivas.
Name
end_time
Type
string
Description
Fim da janela created_at, como um carimbo de data/hora RFC 3339. Por predefinição, a hora atual.
Name
endpoints
Type
string
Description
Lista de nomes de endpoints separados por vírgulas a incluir. Aceita os mesmos valores que o campo de resposta endpoint carrega — 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 — onde text-to-3d é um termo abrangente que cobre as fases de preview e de refine. Omita para incluir todos os endpoints.
Name
status
Type
string
Description
Filtrar por estado terminal 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 terminal. Os créditos são cobrados quando uma tarefa é criada, pelo que uma tarefa ainda em execução no momento da exportação ainda não consta nos resultados dessa janela — repita a extração das janelas mais recentes (ou exporte com um pequeno atraso) se os totais tiverem de corresponder exatamente ao seu saldo de créditos.

Equipas com uma política de retenção de dados personalizada recebem registos dentro da sua janela de retenção configurada.

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"
  }
]

O Objeto de Registo de Utilização

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, reassinados a cada leitura), passe-o ao endpoint de obtenção correspondente, p. ex. GET /openapi/v1/{endpoint}/{task_id}.
Name
endpoint
Type
string
Description
O endpoint em que a tarefa foi executada, p. ex. image-to-3d ou text-to-3d-refine. As tarefas de Texto para 3D reportam a sua fase (text-to-3d-preview / text-to-3d-refine).
Name
status
Type
string
Description
Estado terminal 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 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, para que os gastos históricos continuem atribuíveis 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"
}