API de Utilização

Liste as tarefas de API concluídas da sua equipa e os créditos que cada uma consumiu, para exportações de faturação e relatórios de custos.

Para chamar este endpoint, utilize uma chave de API de um membro ativo de uma equipa Studio ou Enterprise. Qualquer membro pode chamá-lo, não apenas proprietários e administradores. Com qualquer outra chave de API, o pedido devolve 403.

GET/openapi/v1/usage/tasks

Listar registos de utilização

Devolve uma página dos registos de utilização da sua equipa, por predefinição do mais recente para o mais antigo. Sem start_time e end_time, os registos abrangem os últimos 30 dias. Chamar este endpoint é gratuito.

Os registos incluem estas tarefas:

Tarefas de API que terminaram como SUCCEEDED ou FAILED
Tarefas de todos os membros atuais da equipa, a partir de qualquer uma das suas chaves de API
Tarefas que eliminou, e tarefas cujos ficheiros expiraram

Os registos excluem estas tarefas:

Tarefas que ainda estão PENDING ou IN_PROGRESS, e tarefas CANCELED
Tarefas de pessoas que deixaram a equipa
Tarefas do Creative Lab
Tarefas executadas pelos agentes de IA da Meshy
Trabalho realizado na aplicação web da Meshy

Uma tarefa só aparece nos registos depois de terminar, na janela do seu created_at. A Meshy cobra créditos quando cria uma tarefa, pelo que uma tarefa que ainda está em execução não consta dos registos. Antes de reconciliar os registos com o seu saldo de créditos, volte a obter janelas recentes, ou exporte após um curto atraso.

Se a sua equipa tiver um período de retenção de dados, a janela não começa antes do que esse período permite.

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",
    "metadata": {
      "user": "alex@example.com",
      "team": "fab"
    }
  },
  {
    "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",
    "metadata": {}
  }
]

Parâmetros

Name
page_num
Type
integer
predefinição 1
Description
A página a devolver, de 1 a 255. Um valor acima de 255 devolve 400. Uma janela comporta no máximo 255 páginas, pelo que deve dividir uma exportação grande em janelas mais curtas.
Name
page_size
Type
integer
predefinição 10
Description
Número de registos por página, de 1 a 100. Um valor entre 101 e 255 devolve 100 registos, e um valor acima de 255 devolve 400.
Name
sort_by
Type
string
predefinição -created_at
Description
A ordem de ordenação.
Valores disponíveis:
- +created_at: mais antigo primeiro
- -created_at: mais recente primeiro
Num URL, escreva + como %2B. Caso contrário, o + é lido como um espaço, e o pedido devolve 400.
Name
start_time
Type
string
Description
O início da janela, como um carimbo de data/hora RFC 3339, por exemplo 2026-08-01T00:00:00Z. Os registos incluem tarefas criadas nesse momento ou depois. Deixe em branco para iniciar a janela 30 dias antes de end_time.
A janela pode abranger, no máximo, 366 dias. Uma janela mais longa devolve 400, pelo que deve dividir uma exportação mais longa em várias janelas.
Name
end_time
Type
string
Description
O fim da janela, como um carimbo de data/hora RFC 3339. Os registos incluem tarefas criadas antes deste momento. Deixe em branco para terminar a janela no momento do seu pedido.
Name
endpoints
Type
string
Description
Uma lista separada por vírgulas dos endpoints a incluir, pelos mesmos nomes do campo endpoint. Deixe em branco para incluir todos os endpoints. Um nome desconhecido devolve 400.
Valores disponíveis:
- text-to-3d: todas as tarefas de Texto para 3D, preview e refine
- text-to-3d-preview: apenas tarefas de preview
- text-to-3d-refine: apenas tarefas de 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
Name
status
Type
string
Description
O estado a incluir, SUCCEEDED ou FAILED. Deixe em branco para incluir ambos. Qualquer outro valor devolve 400.

Devolve

Devolve um array de registos de utilização. O array está vazio quando nenhum registo corresponde.

Modos de falha

Name
400 - Bad Request
Description
Um parâmetro é inválido, e a mensagem de erro indica qual. Corrija o parâmetro e envie o pedido novamente.
Name
401 - Unauthorized
Description
A chave de API está em falta ou é inválida. Verifique o cabeçalho Authorization.
Name
403 - Forbidden
Description
A conta da chave de API não é um membro ativo de uma equipa Studio ou Enterprise. A mensagem é This endpoint is available on Studio and Enterprise plans. Utilize uma chave de API de um membro de uma equipa Studio ou Enterprise.
Name
429 - Too Many Requests
Description
Enviou demasiados pedidos. Aguarde o número de segundos indicado em Retry-After e tente novamente.

Objeto de registo de utilização

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",
  "metadata": {
    "user": "alex@example.com",
    "team": "fab"
  }
}

Name
task_id
Type
string
Description
O ID da tarefa, o mesmo ID que o endpoint de criação devolveu. Para obter a própria tarefa, com os seus URLs de saída, envie o ID para a rota de obtenção desse endpoint, por exemplo GET /openapi/v1/image-to-3d/{task_id} para um registo image-to-3d.
Name
endpoint
Type
string
Description
O endpoint em que a tarefa foi executada, por exemplo image-to-3d ou rig. Uma tarefa de Texto para 3D mostra a sua fase, text-to-3d-preview ou text-to-3d-refine.
Registos mais antigos podem ter nomes de endpoints retirados, que o filtro endpoints não aceita.
Name
status
Type
string
Description
O estado final da tarefa, SUCCEEDED ou FAILED.
Name
created_at
Type
timestamp
Description
Hora em que a tarefa foi criada, em milissegundos Unix.
Name
finished_at
Type
timestamp
Description
Hora em que a tarefa terminou, em milissegundos Unix. null se a tarefa não tiver hora de conclusão.
Name
consumed_credits
Type
integer
Description
Número de créditos que a tarefa utilizou, após reembolsos. 0 para uma tarefa falhada, porque a Meshy reembolsa-a, e para uma tarefa gratuita como Analisar imprimibilidade.
Name
api_key_name
Type
string
Description
O nome da chave de API que executou a tarefa. Para uma tarefa executada com um início de sessão de aplicação, é o nome da aplicação, por exemplo Meshy CLI.
É uma string vazia em alguns casos, por exemplo:
- A tarefa nunca foi cobrada, como uma tarefa de Analisar imprimibilidade, que é gratuita.
- A chave de API foi eliminada.
- A chave de API foi criada nos últimos minutos.
Name
api_key_suffix
Type
string
Description
Os últimos quatro carateres dessa chave de API, para distinguir chaves com o mesmo nome. Uma string vazia sempre que api_key_name está vazio, e para inícios de sessão de aplicação como o Meshy CLI.
Name
metadata
Type
object
Description
As etiquetas enviadas no cabeçalho X-Meshy-Metadata quando a tarefa foi criada. {} se não houver nenhuma. Consulte Metadata.