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 tem de 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 de API da equipa, da mais recente para a mais antiga. 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 da janela de created_at, como um carimbo de data/hora RFC 3339 (por exemplo, 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 de 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 a incluir, separados por vírgulas. Aceita os mesmos valores que o campo de resposta endpoint transporta — 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 tanto a fase de pré-visualização como a de refinamento. Omita para incluir todos os endpoints.
Name
status
Type
string
Description
Filtrar pelo estado final da tarefa: SUCCEEDED ou FAILED. Omita para incluir ambos.

Retorna

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, 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 de janelas 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 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, novamente assinados a 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 reportam 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, para que as despesas históricas continuem a ser 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"
}