DEV Community: SpicyAPI

A Timeout Is Not a Failed AI Job: Designing Safe Retries for Paid Generation APIs

SpicyAPI — Sun, 25 Oct 2026 04:59:28 +0000

A customer clicks Generate. Your server sends the request, then the connection times out. The tempting fix is to send another request. The expensive possibility is that the first job is already running.

This is a distributed-systems problem with a visible price tag. The client knows that it did not receive an answer; it does not know whether the server accepted the work.

We build SpicyAPI, so the API examples below use our media task protocol. The application design applies to other asynchronous services too, but each service has its own replay guarantees. Check those guarantees before sharing a retry helper across providers.

Separate a user's intent from an HTTP attempt

Give each intentional generation an operation record in your own database. An operation might be “make take 2 for shot 7.” Several HTTP attempts can belong to that one operation.

An intentional third take is a different operation, even if the prompt happens to be identical. A network retry of take 2 is still take 2.

A useful record contains:

Your operation ID and the owning customer or project.
A stable idempotency key generated once for that operation.
The exact request body and a reference to the API credential that will send it.
The creation time and an application recovery deadline.
The remote task ID once you obtain one.
A state that can represent uncertainty.

Store sensitive input in a protected application record; do not copy the full body or credential into ordinary logs. Create the record transactionally before making the network call. Generating a UUID in memory is insufficient if a worker can crash before saving it.

Add an “unknown” state

A small application state machine can be enough:

prepared -> submission_unknown -> accepted -> terminal
          \-> rejected

“Submission unknown” means that the next action is recovery. It should not be presented as proof that the model failed.

An operation can enter that state when a socket closes, a client deadline expires, or a response cannot be parsed. Even a successful server response can be lost before your application commits the task ID.

Once the remote task ID is durable, stop resubmitting. Follow that task through callbacks or status reads. These are two separate problems: recovering acceptance and waiting for completion.

Freeze the submission while recovering it

For SpicyAPI media tasks, reuse the same Idempotency-Key, API key and request semantics to recover an accepted submission. The replay window lasts 24 hours from acceptance; it is not a permanent deduplication service. Model, input or callback changes make it a different request. See the idempotency contract.

That has practical consequences:

Do not regenerate a key inside a retry loop.
Do not reconstruct a prompt from mutable project settings during recovery.
Do not switch credentials and assume the old task will be visible.
Do not keep an automatic recovery queue running beyond the service's replay window.

Use an application deadline much shorter than that window. If recovery is still unresolved, flag the operation for inspection instead of quietly submitting a fresh job.

Keep one HTTP attempt small

Here is a deliberately limited Node.js helper. It makes one attempt and reports what the caller actually knows. A durable worker, rather than this function, decides when to try the saved operation again.

operation.requestBody is a saved JSON string. Build it from the current model schema and your confirmed request before calling this function. The example does not select a model or start a generation by itself.

export async function sendSavedOperation(operation, apiKey, send = fetch) {
  let response;
  let envelope;

  try {
    response = await send(
      'https://api.spicyapi.ai/api/v1/jobs/createTask',
      {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${apiKey}`,
          'Content-Type': 'application/json',
          'Idempotency-Key': operation.idempotencyKey,
        },
        body: operation.requestBody,
        signal: AbortSignal.timeout(20_000),
      },
    );
    envelope = await response.json();
  } catch {
    return { kind: 'unknown', operationId: operation.id };
  }

  const taskId = envelope?.data?.taskId;
  if ([200, 202].includes(response.status)
      && envelope?.code === 200 && taskId) {
    return { kind: 'accepted', taskId, requestId: envelope.request_id };
  }

  // This is a response to classify, not permission to create another job.
  return {
    kind: 'response_to_review',
    httpStatus: response.status,
    businessCode: envelope?.code,
    requestId: envelope?.request_id,
  };
}

The helper intentionally does not label every non-success response “safe to retry.” Invalid input, authentication failures, spend limits and conflicting keys need different handling. Rate limits require bounded backoff; follow the service's retry guidance. HTTP status alone is often insufficient when an API also has business error codes.

After an accepted result, commit the task ID before acknowledging your own queue message. After unknown, retain the same saved operation for recovery. Do not catch every exception and create a new operation.

For multiple workers, claim or lease the operation atomically. Idempotency at the remote API does not prevent two local workers from sending duplicate emails or writing two output records.

Do not confuse acceptance, completion and payment

In this protocol, an HTTP 202 response acknowledges a submitted task. It does not say that generation succeeded. The task's state describes the generation outcome, while settled tells you whether its reported cost is final. A local timeout does not cancel accepted work. The production integration guide describes those boundaries and cost confirmation.

Your interface can reflect this without exposing protocol jargon:

“Checking whether your generation started…” during uncertain submission.
“Generating…” after acceptance.
A completed or failed result only after reading a terminal task state.

An explicit “Generate another take” action should create another operation with a new key. A “Check progress” action should keep following the existing one.

Test the lost response, not only a failed connection

A mock that always throws before accepting anything misses the difficult case. Make your fake server remember the operation, create one task, and then drop the first response. Send the saved operation again.

The useful assertions are:

Two HTTP attempts carry the same key and body.
The fake server creates exactly one remote task.
The recovered task ID is committed locally.
A process restart reads the old operation instead of generating another key.
Two callbacks for that task produce one application-side effect.
An operation beyond its recovery deadline is escalated rather than resubmitted automatically.

Also test a changed body with the old key. A conflict should be visible to your operator, not “fixed” by silently inventing a new key and spending money.

The key question for each failure path is simple: what do we know, and which durable record lets the next worker continue from there?

Written by the SpicyAPI Team. Examples describe our media task API; streaming and chat endpoints have different replay behavior.

Keep an AI Character Consistent Through an API: One Saved Reference, Many Shots

SpicyAPI — Wed, 14 Oct 2026 02:18:01 +0000

You can get a great-looking character out of an image model in one prompt. Getting the same character in the next ten images is the hard part. Describe her again in words and the glasses change shape, the hair drifts a shade, and by the tenth post nobody can say what she looks like.

The fix is procedural rather than clever prompting: pick one image, store it, and make every later generation start from that stored image instead of from text. This post builds that pipeline against an HTTP API in about 100 lines of plain Node.js: candidates, a saved reference, a photo set, and a short clip.

The pipeline

Candidates. Generate a few head-and-shoulders portraits on a plain background with a text-to-image model.
Reference. Save the one you like to a persistent asset library. You get back a stable URI.
Photo set. Call an image edit model with that URI as the reference image and a new scene in the prompt. Repeat per scene.
Clip. Save one of those photos too and pass it as the opening frame of an image-to-video model.

The important rule is in step 3: every new picture starts from the saved reference, never from your latest result. Chaining result-to-result is how small changes pile up.

Models used below (prices at the time of writing, October 2026):

Step	Model	Price
Candidates	`bytedance/seedream-5.0-pro/text-to-image`	$0.036 per image at 1k
Photo set	`bytedance/seedream-5.0-pro/edit`	$0.036 per image at 1k
Clip	`alibaba/wan-3.0/image-to-video`	$0.09 per second at 720p

Four candidates, three photos and one five-second clip come to about $0.70.

A tiny client

No SDK needed. The API wraps every response in { code, msg, data, request_id }, tasks are asynchronous, and writes accept an Idempotency-Key so a retried request does not create (or bill) a second task.

// spicy.mjs: a tiny helper around the SpicyAPI task API (Node 18+, no dependencies)
import { randomUUID } from 'node:crypto';

const BASE = 'https://api.spicyapi.ai';
const KEY = process.env.SPICY_API_KEY;

async function call(method, path, body, idempotencyKey) {
  const res = await fetch(BASE + path, {
    method,
    headers: {
      Authorization: `Bearer ${KEY}`,
      'Content-Type': 'application/json',
      ...(idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : {}),
    },
    body: body ? JSON.stringify(body) : undefined,
  });
  const json = await res.json();
  if (!res.ok) {
    const reason = json.data?.reason ? ` [${json.data.reason}]` : '';
    throw new Error(`${res.status} ${json.msg}${reason} (request_id ${json.request_id})`);
  }
  return json.data;
}

// What a request would cost, without running it
export const quote = (model, input) =>
  call('POST', '/api/v1/jobs/quote', { model, input });

// Create a task, wait up to 60 s on the first call, then poll until it finishes
export async function run(model, input, idempotencyKey = randomUUID()) {
  let task = await call('POST', '/api/v1/jobs/createTask?wait=60', { model, input }, idempotencyKey);
  while (!['succeeded', 'failed', 'canceled', 'expired'].includes(task.state)) {
    await new Promise((r) => setTimeout(r, 5000));
    task = await call('GET', `/api/v1/jobs/recordInfo?taskId=${task.taskId}`);
  }
  if (task.state !== 'succeeded') {
    throw new Error(`${task.taskId} ${task.state}: ${task.errorCode} ${task.errorMessage ?? ''}`);
  }
  return task;
}

// Copy one output of a finished task into the asset library and get a stable spicy://a/ URI
export const saveAsset = (taskId, index, name) =>
  call('POST', '/api/v1/assets', { source: 'task_output', taskId, index, name }, `save-${taskId}-${index}`);

Two details worth knowing:

?wait=60 holds the first request open for up to 60 seconds. Image jobs often come back finished in that one call, and you only poll when they don't. If you disconnect, the task keeps running.
The save call uses a deterministic idempotency key (save-<task>-<index>), so running the script twice does not store the same image twice.

The script

// character.mjs: candidates -> saved reference -> photo set -> one short clip
import { quote, run, saveAsset } from './spicy.mjs';

const T2I = 'bytedance/seedream-5.0-pro/text-to-image';
const EDIT = 'bytedance/seedream-5.0-pro/edit';
const I2V = 'alibaba/wan-3.0/image-to-video';

const mara =
  'Mara, a fictional plant-care host in her early thirties: copper hair in a low bun, ' +
  'round tortoiseshell glasses, mustard-yellow linen apron over a white T-shirt';

// 1. Four candidates for the face, on a plain background
const pickTask = process.env.PICK_TASK;
if (!pickTask) {
  for (let i = 0; i < 4; i++) {
    const task = await run(T2I, {
      prompt: `Head-and-shoulders portrait of ${mara}. Plain white studio background, soft even light, natural skin texture.`,
      resolution: '1k',
      aspect_ratio: '4:5',
    });
    console.log(`${task.taskId}: ${task.output.assets[0].url}`);
  }
  console.log('Rerun with PICK_TASK=<taskId> of the face you like.');
  process.exit(0);
}

// 2. Keep the one you like as the permanent reference
const reference = await saveAsset(pickTask, 0, 'Mara reference');
console.log('reference:', reference.uri); // spicy://a/ast_...

// 3. A photo set: every shot starts from the saved reference, not from text
const scenes = [
  'repotting a monstera at a sunny kitchen table',
  'misting a row of ferns on a rainy windowsill',
  'reading a seed catalogue on a small balcony at dusk',
];
const photos = [];
for (const scene of scenes) {
  const input = {
    prompt: `The woman from the reference image, ${scene}. Keep her face, hair, glasses and apron exactly the same. Natural light, 35mm photo.`,
    image_urls: [reference.uri],
    resolution: '1k',
    aspect_ratio: '4:5',
  };
  const { estimatedCost } = await quote(EDIT, input);
  const task = await run(EDIT, input);
  photos.push(task);
  console.log(`$${estimatedCost} ${scene}: ${task.output.assets[0].url}`);
}

// 4. Animate the first photo for five seconds
const still = await saveAsset(photos[0].taskId, 0, 'Mara repotting');
const clip = await run(I2V, {
  image_url: still.uri,
  prompt: 'She presses the soil down around the plant, then looks up with a small smile. Camera holds steady at eye level. Warm morning light.',
  resolution: '720p',
  duration_seconds: 5,
});
console.log('clip:', clip.output.assets[0].url);

Run it twice. SPICY_API_KEY=sk-spicy-... node character.mjs generates the four candidates and prints each task ID with its image URL, then stops. Open the URLs, choose a face, and run it again with PICK_TASK=<that task ID> to save the reference and make the photo set and the clip. Picking by task ID rather than by position matters: a second run would otherwise generate four new faces.

Why the saved URI matters

Output URLs in output.assets[].url are signed links that expire after about 20 minutes, and results are kept for 14 days. That is fine for downloading, not for a character you will use for months.

POST /api/v1/assets copies the file into a persistent library and returns an asset with a uri like spicy://a/ast_.... That URI:

works in any media field of a model input (image_urls, image_url, and so on), so you never re-upload the reference;
only resolves for API keys of the same workspace, so it is not a public link and the library cannot be used as file hosting;
stays valid until you delete the asset.

Store the uri in your own database next to the character, not the preview URL.

The library unlocks with your account's lifetime top-ups (at the time of writing, $10 in total gives 500 MB and up to 200 saved assets). Without that, the save call returns 400 with data.reason set to asset_library_locked, which the helper above prints. GET /api/v1/assets/usage shows the current plan and limits.

Prompting the edit model

The reference image carries the face; the prompt should carry the change. A few things that help:

Name what must stay the same. "Keep her face, hair, glasses and apron exactly the same" does more than repeating the full description.
Change one thing per shot: the place, the activity or the outfit, not all three.
Keep the signature details visible. Pick two or three (the glasses, the copper hair, the yellow apron) and frame shots so they show. They are what makes a thumbnail recognisable.
Compare side by side. Every few weeks put six recent images next to the reference. If a stranger would not call them the same person, go back to the reference instead of the latest image.

Quote before you spend

POST /api/v1/jobs/quote takes the same body as createTask and returns estimatedCost without running anything. The script prints it per photo. In a real tool you would show it to the user before the button does anything, or refuse requests above a budget. When a task is created, estimatedCost is held and the final charge never goes above it.

Doing it without code

If you just want to try the idea before wiring it into anything, the same flow exists as a page: an AI influencer builder where you pick traits from picture cards, keep a close-up and a full-length photo, save the character, and then make photo sets of 4, 8 or 12 pictures, short videos or lip-synced talking clips from it. Under the hood it is the reference-first approach described above.

Running a persona responsibly

A consistent fictional character is a reasonable thing to run as a brand mascot or a channel host, with a few rules:

Label it. Many social platforms have AI-content labels and some require them. Say in the profile that the character is AI-generated.
Do not imitate a real person, and only start from a photo of someone if you have the right to use that face.
Keep the character a fictional adult, and write that into your persona notes.

Where to go next

Swap the models: any image edit model that accepts reference images works for step 3, and the API docs list what each one accepts.
Add a talking clip: generate speech for a line of dialogue, then run a talking-avatar model on one of the saved photos.
Read the model page for Seedream 5.0 Pro for its resolution tiers and reference-image limits (up to 10 per request).

The whole trick is one habit: store the reference once, and point every later request at it.

How to Extend an AI-Generated Video Clip with an API (Last-Frame Continuation, Joined for You)

SpicyAPI — Tue, 13 Oct 2026 04:16:35 +0000

You generated a nice 5 to 10 second clip with an AI video model, and now you need 20 seconds of it. Most video APIs cap a single generation at a few seconds, so "just make it longer" is not an option. The standard workaround is to continue the clip from where it ended, and the details of doing that cleanly are where most of the time goes. This post walks through the three common approaches, what you have to handle if you build the stitching yourself, and how to get the same result from one API request.

The three ways to extend a clip

Approach	How it works	Pros	Cons
Native continuation	The model itself accepts a video and keeps going	Best motion and scene continuity, no stitching on your side	Only a few models offer it; you still get a separate file unless the provider joins it
Last frame as first frame	Grab the final frame of your clip, feed it to an image-to-video model, then concatenate the two files	Works with any image-to-video model	Visible seams unless you handle frames, sound, color and format; motion direction is not remembered
Reference tail	Pass the last few seconds of your clip to a model that accepts reference video, then concatenate	Carries over motion and some sound context	Needs a model with reference-video input and a clip-length limit; still needs joining

Native continuation is the nicest when it exists, but it is rare. Last-frame continuation is the one you can do with almost anything, so it is the one worth getting right. The rest of this post is about it.

What last-frame stitching actually involves

The idea fits in one sentence. The practice is a checklist.

1. Extract the last frame. With ffmpeg that looks like this:

ffmpeg -sseof -1 -i clip.mp4 -update 1 -q:v 1 last.png

-sseof -1 seeks one second before the end, and -update 1 keeps overwriting the output so the file you end up with is the final decoded frame. Mind the rotation metadata on phone footage and the color range of the source, otherwise the frame you send to the model looks slightly different from what the viewer sees.

2. Generate the continuation from that frame with your image-to-video model of choice.

3. Drop the duplicate frame. The new segment starts on the frame your clip ended on. If you concatenate naively, the viewer sees a one-frame stall at the join. Some models also start with a few static frames or a brightness flash, so check the first handful of frames.

4. Match the format. Concatenation only works cleanly when both pieces agree on resolution, aspect ratio, frame rate and pixel format. Models often return a different frame rate than your source (24 fps against 30 fps is common) and sometimes a slightly different frame size. You have to scale, crop or pad, and choose which one you are willing to distort.

5. Fix the sound seam. If both pieces have audio, a hard cut produces a click and often a jump in loudness. You want a short crossfade and some loudness matching. If one piece is silent, pad it with silence so the audio track does not end early.

6. Re-encode or stream copy? Stream copy (-c copy) is fast and lossless, but it only works when both files share codec, profile, timebase and parameter sets. Otherwise you must re-encode, which costs time and a little quality. In practice you end up with both paths in your code.

7. Watch the color. The new segment's first frame can be a shade brighter or darker than your clip's last frame. A slight shift is noticeable exactly at the cut.

None of this is hard in isolation. Together it is a few hundred lines of ffmpeg glue plus a worker to run it, and every model you add behaves a little differently.

The same thing with one request

SpicyAPI exposes this as a video-extend endpoint on 31 video model families. The examples below use Wan 3.0. You send the clip you want to continue, an optional prompt describing what happens next, and a length for the new segment. The last frame of your clip opens the new Wan 3.0 image-to-video shot, and the platform joins the pieces: it removes the duplicate frame, aligns the frame rate, crossfades the sound and returns the result.

The model id is alibaba/wan-3.0/video-extend. The input fields:

Field	Notes
`video_url`	Required. The clip to continue: MP4, MOV or WebM, up to 60 seconds
`prompt`	Optional. What happens next: action, camera move, sound
`duration_seconds`	Length of the new segment, 2 to 30 (default 5), or `-1` to let the model choose
`resolution`	`480p`, `720p` (default) or `1080p`
`generate_audio`	Default `true`. Your source keeps its own sound either way
`last_image_url`	Optional target end frame for the new segment
`seed`	Optional

With curl

The API is asynchronous: you create a task, then poll it. Set SPICY_API_KEY first.

curl -sS https://api.spicyapi.ai/api/v1/jobs/createTask \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: extend-$(date +%s)" \
  -d '{
    "model": "alibaba/wan-3.0/video-extend",
    "input": {
      "video_url": "https://example.com/my-clip.mp4",
      "prompt": "The camera keeps tracking the cyclist as she turns into the sunlit street, long shadows, soft ambient city sound.",
      "duration_seconds": 5,
      "resolution": "720p"
    }
  }'

The response uses the usual {code, msg, data, request_id} envelope, and data.taskId is what you poll:

curl -sS "https://api.spicyapi.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
  -H "Authorization: Bearer $SPICY_API_KEY"

The task moves through queued and running to succeeded. If you want to know the price before you commit, POST /api/v1/jobs/quote takes the same body and starts nothing.

What comes back

A finished task has two entries in output.assets, in a fixed order:

Index	`role`	Contents
0	`video`	Your original clip and the continuation joined into one file
1	`segment`	The new segment on its own

Each asset carries a signed url, plus durationSeconds, width, height and mime. Download them promptly: the signed URL is valid for about 20 minutes, and results are kept for up to 14 days. Having the standalone segment is handy when you want to re-edit the join yourself or chain another extension from the new footage.

With the Python SDK

If you prefer Python, the spicyapi package (pip install spicyapi) wraps the same calls:

import uuid
from spicyapi import SpicyClient, output_assets

client = SpicyClient()  # reads SPICY_API_KEY

source = client.upload_file("my-clip.mp4")  # returns a spicy:// uri

task = client.create_task(
    model="alibaba/wan-3.0/video-extend",
    input_data={
        "video_url": source["uri"],
        "prompt": "The camera keeps tracking the cyclist as she turns into the sunlit street.",
        "duration_seconds": 5,
        "resolution": "720p",
    },
    idempotency_key=str(uuid.uuid4()),
)
final = client.wait_for_terminal(task["taskId"])

for asset in output_assets(final):
    print(asset.get("role"), asset.get("durationSeconds"), asset.get("url"))

Reuse the same idempotency key if you resend after a timeout, so a dropped connection never turns into a second paid task.

Chaining extensions

Because the first asset is a complete, normal MP4, you can feed it straight back in as the next video_url. A 5 second clip becomes 10, then 15 and so on, until the joined clip reaches the source limit (60 seconds on Wan 3.0). The model only sees the last frame each time, so very long chains can drift: characters and lighting slowly change. The optional last_image_url helps when you need the final segment to land on a specific composition.

What it costs

Billing is per second of the new segment, at the resolution you choose. The source clip you send is not billed. At the time of writing (2026-10-13), the public catalog lists Wan 3.0 video extend at $0.045 per second at 480p, $0.09 at 720p and $0.18 at 1080p, so a 5 second extension at 720p is $0.45. Prices change, so check the model page or request a quote before you build a budget around them.

Practical tips

Match resolution to your source to avoid a visible step in sharpness at the seam.
Write the prompt as what happens next, not a description of the clip you already have.
Keep the source clip's last second stable. If it ends mid-blur, the continuation starts from a blurry frame.
Extending a clip does not fix a bad ending. If the last frame has artifacts, trim the source first.

Try it

The Wan 3.0 model page, with the current price table and examples, is at spicyapi.ai/models/wan-3-0, and the API reference is at docs.spicyapi.ai. If you would rather not write code, there is also a browser version at spicyapi.ai/create/ai-video-extender. Questions about the endpoint or the seam handling are welcome in the comments.

How to run a Civitai or Hugging Face LoRA through an API (no GPU, no upload)

SpicyAPI — Sat, 10 Oct 2026 12:10:07 +0000

You found a LoRA you like on Civitai or Hugging Face. Running it usually means renting a GPU, installing ComfyUI or a diffusers script, downloading the base checkpoint and keeping all of it alive. If all you want is images or short clips from that LoRA inside your own app, that is a lot of machinery.

This post shows the other route: pass the LoRA's download link in an API request and let a hosted model load it for that one task. The examples use SpicyAPI, which exposes a loras field on 60+ image and video endpoints (FLUX, Z-Image, Qwen-Image, Wan 2.2, LTX-2, MiniMax H3 and more). The platform adds no content filter of its own, so what the LoRA and the base model can produce is what you get back. The same ideas apply to any host that takes a LoRA URL.

1. Pick a LoRA trained for the base you will call

A LoRA only works on the base model it was trained on. A FLUX.1 [dev] LoRA does nothing useful on Z-Image Turbo, and most hosts will not tell you: the task succeeds and the LoRA is silently ignored. So start from the base:

On Civitai, each file version lists its "Base Model" in the details panel.
On Hugging Face, it is usually in the model card and the repo tags.

Also note the trigger word and the recommended strength from the card. You will need both.

The LoRA overview page lists which LoRA families map to which hosted base, so you can match them before you spend anything.

2. Get a direct link to the .safetensors file

The API needs a URL that downloads the weights file itself, not the page about it.

Hugging Face — use resolve, not blob:

https://huggingface.co/OWNER/REPO/resolve/main/FILE.safetensors

A blob link returns an HTML page. Only public repos work; a gated repo answers the download with 401 and the task fails.

Civitai — use the API download link with the version ID (the number behind the Download button), not the model ID:

https://civitai.com/api/download/models/VERSION_ID

In our tests these links loaded without a token, including files Civitai marks as sign-in only. If you ever get a 401, append ?token=YOUR_CIVITAI_KEY.

Your own files — any public HTTPS link to a .safetensors file works, for example a file in your own S3 or R2 bucket.

Nothing is uploaded ahead of time. The weights are fetched for the task, and there is no separate LoRA fee.

3. Send the request

Every model has its own input schema, but the LoRA part looks the same: a loras array of { path, scale } objects. Here is Z-Image Turbo LoRA, which takes up to three LoRAs at a scale from 0 to 4 (1 is neutral):

curl -X POST "https://api.spicyapi.ai/api/v1/jobs/createTask?wait=60" \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: lora-demo-001" \
  -d '{
    "model": "alibaba/z-image-turbo-lora/text-to-image",
    "input": {
      "prompt": "TRIGGERWORD, a woman reading by a rain-streaked window at dusk, warm lamp light on her face, city lights behind",
      "aspect_ratio": "3:4",
      "seed": 42,
      "loras": [
        { "path": "https://huggingface.co/OWNER/REPO/resolve/main/FILE.safetensors", "scale": 0.9 }
      ]
    }
  }'

A few details that save time:

?wait=60 holds the connection for up to 60 seconds. If the task finishes in time you get the final record (HTTP 200) straight away; otherwise you get the usual 202 with a taskId and poll.
Idempotency-Key makes a retry of the same request return the same task instead of creating and charging a second one.
Fix the seed while you are tuning. It is the only way to tell whether a change came from the LoRA or from luck.

If you got a 202, poll until state is terminal:

curl "https://api.spicyapi.ai/api/v1/jobs/recordInfo?taskId=TASK_ID" \
  -H "Authorization: Bearer $SPICY_API_KEY"

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "job_...",
    "state": "succeeded",
    "cost": "0.012",
    "settled": true,
    "output": {
      "assets": [
        { "url": "https://...", "mime": "image/jpeg" }
      ]
    }
  }
}

The asset URL is a signed link valid for about 20 minutes; poll again for a fresh one, or download the file. Results are kept for 14 days.

Want the price first? Send the same body to POST /api/v1/jobs/quote. It returns the estimated charge and the maximum you can be billed, and creates nothing. Image LoRA endpoints are mostly a flat price per image (Z-Image Turbo LoRA is $0.012); video endpoints bill per second of output, so quoting first is worth it there.

4. Check that the LoRA is actually doing something

Because a mismatched or broken LoRA often fails silently, do one A/B run before you scale up:

Run the request once with the LoRA.
Run it again with the same seed and "loras": [].

If the two images look alike, something is off: wrong base, missing trigger word, or a scale too low to matter. Fix that before generating a batch.

5. Tuning strength and stacking

Start at the card's recommended scale, often 0.7 to 1.0. Far above 1 tends to burn in artefacts.
Stack carefully. Two style LoRAs at full strength usually fight. Keep the main one near 1 and bring the second in around 0.5, moving one scale by about 0.2 at a time with the seed fixed.
Trigger word first in the prompt, then the subject, the setting and the light. Concrete lighting ("a warm lamp on the face, neon behind") moves a realism LoRA further than adjectives like "cinematic".
Video models can have more than one slot. Wan 2.2 uses a two-stage sampler, so its LoRAs come as separate HIGH-noise and LOW-noise files; that endpoint takes them in high_noise_loras and low_noise_loras, plus a plain loras field. Put each file in the slot it was trained for.

Limits differ by model (how many LoRAs, what scale range), so read the loras part of the model's inputSchema from the catalog before you hard-code anything.

When this route makes sense

Hosted LoRA calls are a good fit when you want results inside your own app without running GPUs, when you switch LoRAs often, or when you are testing many community LoRAs before committing to one. If you generate around the clock on a single fixed LoRA, your own GPU may work out cheaper; at a few cents per image, most side projects and prototypes never get there.

The full field reference, SDKs (TypeScript, Python, Go, PHP, Java) and a CLI are in the docs.