Recursos, jobs y entrega
Sube medios, conserva la identidad de la tarea y recupera el trabajo sin envíos duplicados.
Importa un archivo en dos pasos
Primero llama a upload_create con el nombre original, tamaño exacto en bytes, hash SHA-256, origen, licencia y rightsConfirmed: true. El resultado incluye uploadUrl y method: PUT. Envía los bytes sin procesar a la ruta devuelta en el mismo origen del runtime y con la misma clave Bearer. La subida completada devuelve un registro de recurso; usa su id en las operaciones siguientes. Los runtimes remotos no leen rutas de tu computadora.
| Campo | Tipo / requisito |
|---|---|
| name | string · Nombre original del archivo. |
| bytes | entero positivo · Tamaño exacto del archivo. |
| sha256 | string · Hash de los mismos bytes que se subirán. |
| source / license | strings · Origen y derechos de uso correctos. |
| rightsConfirmed | true · Solo para medios que tienes permiso de usar. |
Ejemplo de subida en Node.js
Agrega este fragmento al helper callTool de la guía de API. Reemplaza ./product.png con tu archivo. La ruta local de subida acepta hasta 100 MiB; el modelo elegido puede imponer límites menores, dimensiones o duración. Valida estos requisitos por separado antes de preparar la generación.
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);Envía una vez y consulta
Prepara la generación con generation_prepare y pasa la operación validada exacta a job_submit. Conserva preparedRequestId cuando exista. Guarda una idempotencyKey estable antes del envío y reutilízala solo con la misma entrada al reintentar. quoteId es opcional en este runtime; quote_create puede producir una estimación cuando se solicite. Los controles de solicitud o la selección de modelo no autorizan una compra. Respeta la tarea y cualquier límite explícito de gasto.
{ "type": "job", "id": "<job-id-returned-by-submission>" }Estados y recuperación de jobs
| Estado | Siguiente acción |
|---|---|
| queued / running | Consulta record_get con el mismo ID. Amplía el intervalo entre consultas; no reenvíes. |
| completed | Revisa las salidas y obtén el resultado del espacio de trabajo cuando corresponda. |
| failed | Lee el error. job_resume solo recupera una solicitud conocida del proveedor que sea elegible. |
| submission_unknown | Detén los reenvíos automáticos y verifica la solicitud original o su conciliación. |
| cancelled | Revisa los registros finales y la facturación; cancelar en el proveedor no garantiza un reembolso. |
Edita y entrega el resultado
Lee workspace_snapshot antes de editar. Envía workspace_commit con projectId, el baseRevisionId actual y una idempotencyKey estable. Ante REVISION_CONFLICT, vuelve a leer y reaplica el cambio deseado. workspace_commit programa un render local; no compra nuevas imágenes generadas. Usa workspace_result para progreso y entrega final, incluyendo el enlace al espacio de trabajo. Si el cliente MCP ofrece workspace_export, úsalo para guardar los archivos terminados otra vez, sin renderizar ni generar. Los clientes HTTP pueden actualizar enlaces con workspace_result; workspace_export es un helper MCP del cliente, no un endpoint de herramienta HTTP.