API de uso
Liste as tarefas de API concluídas da sua equipe e os créditos que cada uma usou, para exportações de faturamento e relatórios de custos.
Para chamar este endpoint, use uma chave de API de um membro ativo de uma equipe Studio ou Enterprise. Qualquer membro pode chamá-lo, não apenas proprietários e administradores. Com qualquer outra chave de API, a requisição retorna 403.
Listar registros de uso
Retorna uma página dos registros de uso da sua equipe, por padrão os mais recentes primeiro. Sem start_time e end_time, os registros cobrem os últimos 30 dias. Chamar este endpoint é gratuito.
Os registros incluem estas tarefas:
- Tarefas de API que terminaram como
SUCCEEDEDouFAILED - Tarefas de todos os membros atuais da equipe, a partir de qualquer uma de suas chaves de API
- Tarefas que você excluiu, e tarefas cujos arquivos expiraram
Os registros deixam de fora estas tarefas:
- Tarefas que ainda estão
PENDINGouIN_PROGRESS, e tarefasCANCELED - Tarefas de pessoas que saíram da equipe
- Tarefas do Creative Lab
- Tarefas que os agentes de IA da Meshy executaram
- Trabalho feito no aplicativo web da Meshy
Uma tarefa aparece nos registros somente após sua conclusão, na janela de seu created_at. A Meshy cobra créditos ao criar uma tarefa, então uma tarefa ainda em execução fica ausente dos registros. Antes de reconciliar os registros com o seu saldo de créditos, busque novamente as janelas recentes, ou exporte após um pequeno atraso.
Se sua equipe tiver um período de retenção de dados, a janela não começa antes do que esse período permite.
Request
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
- padrão 1
- Description
A página a retornar, de
1a255. Um valor acima de255retorna400. Uma janela comporta no máximo 255 páginas, então divida uma exportação grande em janelas mais curtas.
- Name
- page_size
- Type
- integer
- padrão 10
- Description
Número de registros por página, de
1a100. Um valor de101a255retorna 100 registros, e um valor acima de255retorna400.
- Name
- sort_by
- Type
- string
- padrão -created_at
- Description
A ordem de classificação.
Valores disponíveis:
+created_at: mais antigos primeiro-created_at: mais recentes primeiro
Em uma URL, escreva
+como%2B. Caso contrário, o+é interpretado como um espaço, e a requisição retorna400.
- 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 registros incluem tarefas criadas nesse horário ou depois dele. Deixe de fora para iniciar a janela 30 dias antes deend_time.A janela pode abranger no máximo 366 dias. Uma janela mais longa retorna
400, então divida 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 registros incluem tarefas criadas antes desse horário. Deixe de fora para encerrar a janela no momento da sua requisição.
- Name
- endpoints
- Type
- string
- Description
Uma lista de endpoints a incluir, separados por vírgula, com os mesmos nomes do campo
endpoint. Deixe de fora para incluir todos os endpoints. Um nome desconhecido retorna400.Valores disponíveis:
text-to-3d: todas as tarefas de Texto para 3D, preview e refinetext-to-3d-preview: somente tarefas de previewtext-to-3d-refine: somente tarefas de refineimage-to-3dmulti-image-to-3dretextureremeshconvertresizeuv-unwrapriganimatetext-to-motiontext-to-imageimage-to-imageprint-multi-colorprint-repairprint-analyzeprint-splitrelief
- Name
- status
- Type
- string
- Description
O status a incluir,
SUCCEEDEDouFAILED. Deixe de fora para incluir ambos. Qualquer outro valor retorna400.
Retornos
Retorna um array de registros de uso. O array fica vazio quando nenhum registro 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 a requisição novamente.
- Name
401 - Unauthorized- Description
A chave de API está ausente 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 equipe Studio ou Enterprise. A mensagem é
This endpoint is available on Studio and Enterprise plans. Use uma chave de API de um membro de equipe Studio ou Enterprise.
- Name
429 - Too Many Requests- Description
Você enviou muitas requisições. Aguarde o número de segundos em
Retry-Aftere tente novamente.
Objeto de registro de uso
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 retornado pelo endpoint que a criou. Para obter a própria tarefa, com suas 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 registroimage-to-3d.
- Name
- endpoint
- Type
- string
- Description
O endpoint em que a tarefa foi executada, por exemplo
image-to-3dourig. Uma tarefa de Texto para 3D mostra seu estágio,text-to-3d-previewoutext-to-3d-refine.Registros mais antigos podem ter nomes de endpoints descontinuados, que o filtro
endpointsnão aceita.
- Name
- status
- Type
- string
- Description
O status final da tarefa,
SUCCEEDEDouFAILED.
- Name
- created_at
- Type
- timestamp
- Description
Horário em que a tarefa foi criada, em milissegundos Unix.
- Name
- finished_at
- Type
- timestamp
- Description
Horário em que a tarefa foi concluída, em milissegundos Unix.
nullse a tarefa não tiver horário de conclusão.
- Name
- consumed_credits
- Type
- integer
- Description
Número de créditos que a tarefa usou, após reembolsos.
0para uma tarefa com falha, porque a Meshy a reembolsa, 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 login de aplicativo, é o nome do aplicativo, 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 excluída.
- A chave de API foi criada nos últimos minutos.
- Name
- api_key_suffix
- Type
- string
- Description
Os últimos quatro caracteres dessa chave de API, para diferenciar chaves com o mesmo nome. Uma string vazia sempre que
api_key_nameestiver vazio, e para logins de aplicativo, como o Meshy CLI.
- Name
- metadata
- Type
- object
- Description
As tags enviadas no cabeçalho
X-Meshy-Metadataquando a tarefa foi criada.{}se nenhuma. Veja Metadata.