Materiais, jobs e entrega

Envie mídia, preserve a identidade da tarefa e recupere o trabalho sem envios duplicados.

Importe um arquivo em duas etapas

Primeiro chame upload_create com nome original, tamanho exato em bytes, hash SHA-256, origem, licença e rightsConfirmed: true. O resultado inclui uploadUrl e method: PUT. Envie os bytes brutos ao caminho retornado na mesma origem do runtime e com a mesma chave Bearer. O upload concluído retorna um registro de material; use seu id nas operações seguintes. Runtimes remotos não leem caminhos no seu computador.

Campo	Tipo / requisito
name	string · Nome original do arquivo.
bytes	inteiro positivo · Tamanho exato do arquivo.
sha256	string · Hash dos mesmos bytes que serão enviados.
source / license	strings · Origem e direitos de uso corretos.
rightsConfirmed	true · Apenas para mídia que você pode usar.

Exemplo de upload em Node.js

Adicione este trecho ao helper callTool do guia de API. Substitua ./product.png pelo seu arquivo. A rota local de upload aceita até 100 MiB; o modelo escolhido pode impor limites menores, dimensões ou duração. Valide esses requisitos separadamente antes de preparar a geração.

javascript

import { readFile } from "node:fs/promises";
import { createHash } from "node:crypto";

const bytes = await readFile("./product.png");
const intent = await callTool("upload_create", {
  name: "product.png",
  bytes: bytes.byteLength,
  sha256: createHash("sha256").update(bytes).digest("hex"),
  source: "My product photography",
  license: "Owned by me",
  rightsConfirmed: true,
});
const uploadUrl = new URL(intent.uploadUrl, base);
if (uploadUrl.origin !== new URL(base).origin) throw new Error("Unexpected upload origin");
const response = await fetch(uploadUrl, {
  method: "PUT",
  headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/octet-stream" },
  body: bytes,
});
const body = await response.json();
if (!response.ok || body.error) throw new Error(body.error?.code || `HTTP ${response.status}`);
console.log(body.result.id);

Envie uma vez e acompanhe

Prepare a geração com generation_prepare e passe a operação validada exata a job_submit. Preserve preparedRequestId quando presente. Salve uma idempotencyKey estável antes do envio e reutilize-a apenas com a mesma entrada ao repetir. quoteId é opcional neste runtime; quote_create pode produzir uma estimativa quando solicitada. Controles de pedido ou seleção de modelo não autorizam uma compra. Respeite a tarefa e qualquer limite explícito de gastos.

json

{ "type": "job", "id": "<job-id-returned-by-submission>" }

Estados e recuperação de jobs

Estado	Próxima ação
queued / running	Consulte record_get com o mesmo ID. Aumente o intervalo entre consultas; não reenvie.
completed	Confira as saídas e obtenha o resultado do espaço de trabalho quando aplicável.
failed	Leia o erro. job_resume só recupera uma requisição conhecida do provedor que seja elegível.
submission_unknown	Interrompa reenvios automáticos e verifique a requisição original ou sua conciliação.
cancelled	Confira os registros finais e a cobrança; cancelamento no provedor não garante reembolso.

Edite e entregue o resultado

Leia workspace_snapshot antes de editar. Envie workspace_commit com projectId, baseRevisionId atual e idempotencyKey estável. Em REVISION_CONFLICT, leia novamente e reaplique a alteração desejada. workspace_commit agenda uma renderização local; não compra novas imagens geradas. Use workspace_result para progresso e entrega final, incluindo o link do espaço de trabalho. Se o cliente MCP oferecer workspace_export, use-o para salvar os arquivos concluídos novamente, sem renderizar ou gerar. Clientes HTTP podem atualizar links com workspace_result; workspace_export é um helper MCP do cliente, não um endpoint de ferramenta HTTP.

Referência do rikoko 0.1.30, revisada em 21 de outubro de 2026. O instalador público segue uma versão própria; consulte os parâmetros e modelos na instalação que você usa.