API Docs

Overview

Use a Bearer API key from your signed-in account to create generation jobs. Credits are charged to that account.

• Base URL: https://yukis.ai
• Auth: Authorization: Bearer yuki_live_…
• No webhooks yet — poll job status until completed or failed.

Quick start

Create a key under Account → API Keys, then enqueue a job:

export YUKI_API_KEY="yuki_live_…"
export YUKI_BASE_URL="https://yukis.ai"

curl -sS -X POST "$YUKI_BASE_URL/api/generate" \
  -H "Authorization: Bearer $YUKI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A serene mountain lake at golden hour",
    "aspectRatio": "16:9",
    "modelId": "yukis-gpu-8s",
    "resolution": "1K"
  }'

Authentication

Pass your key on every protected request. Keys use the yuki_live_ prefix and bind to one account.

• generation:create — enqueue jobs via POST /api/generate
• generation:read — poll jobs via GET /api/jobs/:id

Do not use Studio agent keys (yuki_agent_…) for generation — those are admin analytics keys only.

Integration flow

1. Optionally list models for ids, costs, and tier gates (GET /api/models)
2. Enqueue a generation — response includes jobId (POST /api/generate)
3. Poll every 2–5 seconds until status is completed or failed (GET /api/jobs/:id)
4. Download from outputUrlsFull when outputFullReady is true (otherwise use outputUrls thumbnails)

List models

GET/api/models

Returns the public model catalog for the caller’s tier.

{
  "brands": [
    {
      "id": "yukis",
      "label": "Yuki's GPU",
      "models": [
        {
          "id": "yukis-gpu-8s",
          "displayName": "Yuki's GPU 8S",
          "creditCost": 1,
          "tierAllowed": true,
          "resolutions": ["1K", "2K", "4K"]
        }
      ]
    }
  ],
  "defaultModelId": "yukis-gpu-8s"
}

Enqueue a generation

POST/api/generate

Creates an async job and returns immediately. Required Content-Type: application/json.

Success response (HTTP 202):

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "creditsCharged": 1,
  "creditsBalance": 1999
}

Poll job status

GET/api/jobs/:id

With a Bearer key (generation:read), you can poll jobs belonging to that account. Treat job IDs as secrets.

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "outputUrls": ["https://…/0_thumb.webp"],
  "outputUrlsFull": ["https://…/0.png"],
  "outputFullReady": true,
  "error": null,
  "creditsBalance": 1998
}

Stop when status is completed or failed. Typical jobs finish in about 10–60 seconds.

Upload a reference image

POST/api/reference-image

multipart/form-data field file. Pass pathname as referenceImageBlobPath (or url as referenceImageUrl) on POST /api/generate.

{
  "ok": true,
  "url": "https://…",
  "pathname": "public/temp/references/…"
}

Common errors

Credits and tiers

API generation uses the same credit ledger as the website. Cost depends on model, resolution, and batch size — see creditCost on each model from GET /api/models. Top up or upgrade from Account when balance is low.

Node.js example

Enqueue and poll until the image is ready:

const BASE = process.env.YUKI_BASE_URL ?? "https://yukis.ai";
const headers = {
  "Content-Type": "application/json",
  Authorization: `Bearer ${process.env.YUKI_API_KEY}`,
};

async function generateImage(prompt, opts = {}) {
  const enqueue = await fetch(`${BASE}/api/generate`, {
    method: "POST",
    headers,
    body: JSON.stringify({
      prompt,
      aspectRatio: "1:1",
      modelId: opts.modelId,
      resolution: opts.resolution ?? "1K",
    }),
  });
  if (!enqueue.ok) throw new Error(await enqueue.text());
  const { jobId } = await enqueue.json();

  for (;;) {
    await new Promise((r) => setTimeout(r, 2500));
    const res = await fetch(`${BASE}/api/jobs/${jobId}`, { headers });
    const job = await res.json();
    if (job.status === "completed") {
      const url = job.outputFullReady
        ? job.outputUrlsFull?.[0]
        : job.outputUrls?.[0];
      return { jobId, imageUrl: url, job };
    }
    if (job.status === "failed") {
      throw new Error(job.error ?? "generation_failed");
    }
  }
}

Security

• Rotate keys by revoking and creating a new one in Account → API Keys.
• Never commit raw keys — use environment variables or a secret manager.
• Use HTTPS only. Job IDs can act as capability tokens — keep them private.
• Honor HTTP 429 responses and back off before retrying.