API

A API HTTP do Skynet permite que scripts e ferramentas façam o que o aplicativo web faz: iniciar execuções, acompanhá-las e ler os resultados. Esta página mostra como assinar as requisições, onde está a referência completa e um exemplo completo.

URL base

Envie todas as requisições para:

https://api.skynetml.com

Autenticação

A API usa tokens de API.

1. Abra Definições no Skynet e depois a aba API.
2. Clique em Gerar token.
3. Copie o token imediatamente. O Skynet mostra o token completo uma única vez.

Envie o token no cabeçalho Authorization de cada requisição:

Authorization: Bearer skyd_...

• Os tokens começam com skyd_.
• Cada usuário tem no máximo um token válido. Um novo token invalida o token anterior.
• Clique em Revogar token para invalidar um token.

Referência interativa

A referência completa está em api.skynetml.com/scalar. Ela lista cada endpoint público, os seus campos e as suas respostas. Você pode enviar requisições de teste a partir dessa página.

A referência lê o documento OpenAPI em https://api.skynetml.com/openapi.public.json. Use esse arquivo para gerar um cliente na sua linguagem.

Endpoints principais

Iniciar uma execução

POST /optimize recebe a mesma configuração que o assistente de envio. Este exemplo melhora um prompt que classifica mensagens de suporte em rótulos.

curl https://api.skynetml.com/optimize \
  -H "Authorization: Bearer $SKYNET_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: support-labels-001" \
  -d @run.json

{
  "name": "Support labels",
  "task": {
    "objective": "Sort each support message into billing, bug or other.",
    "artifact": {
      "kind": "prompt",
      "starting_version": "Label this support message as billing, bug or other."
    }
  },
  "data": {
    "mode": "pairs",
    "cases": [
      { "input": { "message": "I was charged twice." }, "expected": { "label": "billing" } },
      { "input": { "message": "The export button does nothing." }, "expected": { "label": "bug" } },
      {
        "input": { "message": "Do you have a Hebrew interface?" },
        "expected": { "label": "other" }
      }
    ]
  },
  "optimizer": { "choice": "auto", "budget": { "max_scorer_runs": 200 } },
  "models": {
    "task_model": { "name": "<model from GET /models>" },
    "reflection_model": { "name": "<model from GET /models>" }
  },
  "workspace": {
    "run_code": "from skynet import llm\n\ndef run(artifact, input):\n    return llm(artifact, input=input[\"message\"])\n",
    "metric_code": "def score(input, output, expected=None):\n    ok = str(output).strip().lower() == expected[\"label\"]\n    return (1.0 if ok else 0.0), {\"feedback\": \"Correct.\" if ok else \"Wrong label.\"}\n"
  },
  "max_cost_cents": 500
}

Campos importantes:

• task.artifact.kind é prompt, code, text ou dspy_program.
• data.mode é pairs (entradas com saídas esperadas) ou single (exatamente um caso).
• optimizer.choice é auto ou o nome de um otimizador retornado por GET /optimizers.
• max_cost_cents é o limite de gastos desta execução, em centavos de dólar americano.
• is_private é false por padrão. Defina como true para manter a execução privada.

Leia Métricas e avaliadores para ver as regras de run_code e metric_code.

Respostas

Acompanhar uma execução

Consulte a execução até que o status seja final:

curl https://api.skynetml.com/optimizations/$RUN_ID \
  -H "Authorization: Bearer $SKYNET_TOKEN"

O campo status é um destes:

Consulte a cada 10 a 30 segundos. Uma execução pode levar de minutos a horas.

A referência da API lista todos os campos da resposta da execução.

Usar o resultado

Quando o status for success, obtenha a melhor versão:

curl https://api.skynetml.com/optimizations/$RUN_ID/artifact \
  -H "Authorization: Bearer $SKYNET_TOKEN"

Para executar a melhor versão em uma nova entrada, envie POST /serve/{optimization_id}. Leia Resultados para saber o que cada pontuação significa.

Limites

A API usa as mesmas cotas, limites de taxa e cobrança que o aplicativo web. Leia Limites e Cobrança.