Referência da API · v1JSON + multipart

Integre bordado em seu produto.

Uma API REST prática para digitalização privada de imagens e conversão real de arquivos de máquina. Esta página é o guia completo de início rápido, referência de endpoints e erros.

Obter uma chave de API OpenAPI 3.1

URL base

https://embroideryfileconverter.com/api/developer/v1

Autenticação

Chave Bearer

Limite

60/min

Trabalhos

Assíncrono

As chaves são limitadas por escopo, expiram, podem ser revogadas imediatamente e são exibidas apenas uma vez. Mantenha-as no seu servidor — nunca as envie em código de navegador ou cliente móvel.

Visão geral Início rápido Autenticação Criar um trabalho Ciclo de vida do trabalho Referência de endpoints Erros e limites

Início rápido

Seu primeiro trabalho em três etapas.

Criar uma chave

Selecione apenas as capacidades necessárias ao seu serviço e armazene o segredo em um gerenciador de segredos no servidor.

Enviar a origem

Envie dados de formulário multipart POST com o fluxo de trabalho, o formato de saída e um arquivo de origem privado.

Consultar o trabalho

Use o fluxo de trabalho e o ID do trabalho retornados até o status ser concluído ou falhado.

Criar um trabalho de conversão · Shell

curl -X POST https://embroideryfileconverter.com/api/developer/v1/jobs \
  -H "Authorization: Bearer $EFC_API_KEY" \
  -H "Accept: application/json" \
  -F "workflow=conversion" \
  -F "format=dst" \
  -F "[email protected]"

Autenticação

Chaves Bearer com escopo.

Envie a chave no cabeçalho Authorization em cada solicitação. Uma chave só acessa os trabalhos do seu proprietário e apenas as capacidades selecionadas na criação.

formats:read

usage:read

jobs:read

jobs:write

Cabeçalho de autorização

Authorization: Bearer efc_live_...
Accept: application/json

Somente no servidor

Não incorpore uma chave de desenvolvedor em uma página web, binário de desktop distribuído ou aplicativo móvel. Processe as solicitações pelo seu backend.

Precisa de acesso delegado do usuário?

Clientes de IA devem usar MCP com OAuth e PKCE em vez de receber uma chave de API de desenvolvedor.

POST /jobs

Escolha o fluxo de trabalho que corresponde à origem.

workflow=conversion

Arquivo de máquina existente

Envie PES, DST, JEF ou outro formato de bordado legível e escolha uma saída gravável diferente.

Necessários: workflow, format, file
Tamanho máximo do arquivo: 50 MB

workflow=digitising

Arte JPG, PNG, SVG ou WebP

Gere uma pré-visualização de pontos a partir da arte. Largura final e quantidade máxima de cores de linha são obrigatórias.

Campos adicionais: width_mm, colour_count
Intervalos válidos: 10–300 mm · 1–24 cores
Tamanho máximo do arquivo: 20 MB

Arquivos únicos e lotes

Use file para uma origem ou files[] para até 10 origens. O processamento gratuito limitado pode aceitar um arquivo por solicitação. Cada lote usa um fluxo de trabalho e formato de saída compartilhados.

202 Aceito

{
  "message": "Processing started.",
  "job": {
    "id": "01JEXAMPLEJOBID000000000",
    "status": "queued",
    "workflow": "conversion"
  },
  "jobs": [
    {
      "id": "01JEXAMPLEJOBID000000000",
      "status": "queued",
      "workflow": "conversion"
    }
  ],
  "freeUsage": {
    "previewRemaining": 2,
    "creditBalance": 0
  }
}

A criação é assíncrona

HTTP 202 significa que o trabalho privado foi aceito, não que o arquivo de máquina está pronto. Persista ambos job.id e job.workflow; o fluxo de trabalho seleciona a rota de status.

queuedAguardando um trabalhador

processingMotor em execução

completedInspecione saídas e avisos

failedLeia failureCode e failureReason

Consulta e arquivos

Leia o resultado, não apenas o status.

Uma resposta concluída inclui métricas analisadas, avisos, eventos, artefatos de pré-visualização e arquivos de saída. URLs assinadas são de curta duração; solicite o trabalho novamente quando uma URL expirar.

Obter um trabalho de processamento · Shell

curl https://embroideryfileconverter.com/api/developer/v1/jobs/conversion/01JEXAMPLEJOBID000000000 \
  -H "Authorization: Bearer $EFC_API_KEY" \
  -H "Accept: application/json"

Métricas

Contagem de pontos, dimensões e medições específicas do motor.

Avisos

Notas de compatibilidade ou produção que sua interface deve exibir.

Arquivos privados

URLs assinadas duram 10 minutos e ainda exigem propriedade e estado de desbloqueio.

Desbloquear pode consumir uma cota

Primeiro inspecione job.unlock ou GET /usage. Chamar o endpoint de desbloqueio pode consumir saldo de subscrição ou créditos de processamento existentes. Contas internas podem desbloquear sem custo. Não abre checkout nem compra de créditos.

Referência de endpoints

A superfície completa da v1.

OpenAPI JSON

GET/formats

Origens legíveis, saídas graváveis e avisos de compatibilidade.

formats:read

GET/usage

Limite de visualização, créditos, custos dos fluxos e datas de reinício.

usage:read

GET/jobs

Os 50 trabalhos privados de processamento mais recentes da conta.

jobs:read

POST/jobs

Criar um trabalho de visualização de conversão ou digitalização de imagem.

jobs:write

GET/jobs/conversion/{id}

Inspecionar um trabalho de conversão pertencente à conta e suas saídas.

jobs:read

GET/jobs/digitising/{id}

Inspecionar um trabalho de digitalização pertencente à conta e suas saídas.

jobs:read

POST/jobs/{workflow}/{id}/retry

Colocar novamente na fila um trabalho com falha enquanto sua origem privada ainda existir.

jobs:write

POST/jobs/{workflow}/{id}/unlock

Liberar um trabalho concluído usando limite ou créditos existentes.

jobs:write

Respostas de listagem

GET /formats retorna data[] e artworkInputs[]. GET /jobs retorna data[] mais freeUsage e é limitado aos 50 trabalhos mais recentes.

Respostas de nova tentativa

Nova tentativa aceita apenas um failed trabalho cuja origem não expirou. Uma nova tentativa bem-sucedida retorna HTTP 202 com o trabalho redefinido para queued.

Erros e limites de taxa

Falhe claramente. Tente novamente deliberadamente.

401

Chave ausente, inválida, expirada ou revogada

403

Capacidade ausente ou recurso pertence a outro usuário

404

Trabalho ou arquivo privado não encontrado

409

Estado do trabalho não permite esta ação

410

Upload da origem expirou

422

Campos, arquivo, formato inválidos ou cota insuficiente

429

Limite de taxa excedido

Erro de validação 422

{
  "message": "The format field is invalid.",
  "errors": {
    "format": [
      "Choose an output format different from every detected source format."
    ]
  }
}

60 solicitações por minuto

O limite geral se aplica por chave de API, com um teto de rede separado. Rotas de upload, processamento e desbloqueio têm controles de abuso mais rigorosos.

Trate HTTP 429

Respeite Retry-After e use backoff exponencial com jitter. Não consulte continuamente trabalhos concluídos ou falhados.

Criando para um agente de IA?

Use OAuth + MCP, não uma chave de API.

O guia do agente inclui configuração de conexão, URLs de descoberta, OAuth PKCE, todos os esquemas de ferramentas e exemplos JSON-RPC prontos para copiar.

Abrir documentação MCP

Precisa de ajuda? Contatar suporte ao desenvolvedor

Baixar a descrição OpenAPI