Designs

Nimply can make real, editable designs for you: social posts, carousels, ads and thumbnails, built in your brand kit and opened in the Nimply design editor. Two jobs are available:

• Generate — give a brief ("an Instagram post announcing our summer sale, 20% off, shop now") and Nimply's design composer builds a finished design.
• Layers — give an image (for example one ChatGPT just made) and Nimply splits it into editable text, objects and a clean background, so you can change the words, move things around and reuse it.

Each job leaves a design in your workspace. You get back an edit link that opens it in the editor, and preview images (PNG) of the result.

Scopes: designs:read for reads and polling, designs:write to start or cancel a job. Both are opt-in.

Plans and credits: designs are available on paid plans and during a trial. Each job uses AI credits from your workspace. Nimply reserves the maximum up front and charges only what the job actually used. Ask for an estimate first with GET /v1/designs/estimate. If the workspace is short of credits the job is refused with 402 and code INSUFFICIENT_CREDITS.

How jobs work

Both kinds of job are asynchronous. A design takes about 1–3 minutes per size; layering an image takes about 30–60 seconds.

1. Start the job: POST /v1/designs/generate or POST /v1/designs/from-image → 202 with a design job.
2. Poll GET /v1/design-jobs/{id}?wait=25. With wait, the request is held for up to 25 seconds and returns as soon as something changes, so a few calls cover a whole job.
3. When status is done, each item in designs has its editUrl and previewUrls.

status moves through queued → running → rendering (the preview PNGs are being made) → done. It can also end as failed (unused credits are released) or cancelled.

Endpoints

Both start endpoints are limited to 10 requests per minute per key, on top of the general rate limit.

Generate a design

curl -X POST "https://api.nimply.io/v1/designs/generate" \
  -H "Authorization: Bearer $NIMPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Instagram post announcing our summer sale: 20% off all cold brew this weekend. Friendly, bright, for coffee lovers in Dubai.",
    "sizes": ["ig-post-45"],
    "cta": "Shop the sale",
    "maxCredits": 300
  }'

Turn an image into layers

Send exactly one of mediaId (an image already in your media library) or imageUrl (a public image URL; Nimply imports it first).

curl -X POST "https://api.nimply.io/v1/designs/from-image" \
  -H "Authorization: Bearer $NIMPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "imageUrl": "https://example.com/poster.png", "mode": "everything" }'

mode chooses what becomes editable: text (just the words, the cheapest), objects, or everything (the default).

The design job

{
  "id": "6f0c1d1e-2a9b-4f57-9d3c-0b6c3b2c9a11",
  "kind": "generate",
  "status": "done",
  "progress": 100,
  "stage": "Ready",
  "creditsReserved": 251,
  "creditsCharged": 132,
  "estimatedSeconds": null,
  "designs": [
    {
      "id": "b1d0c7e2-5c1a-4a43-8f53-3d0f6f9d7e20",
      "name": "Summer sale — Instagram portrait",
      "width": 1080,
      "height": 1350,
      "pageCount": 1,
      "sizePreset": "ig-post-45",
      "editUrl": "https://app.nimply.io/workspace/…/studio/design/b1d0c7e2-…",
      "previewUrls": ["https://cdn.nimply.io/…/page-1.png?…"],
      "thumbnailUrl": "https://cdn.nimply.io/…/thumb.jpg?…",
      "createdAt": "2026-10-21T10:02:11.000Z"
    }
  ],
  "error": null,
  "createdAt": "2026-10-21T10:00:40.000Z",
  "finishedAt": "2026-10-21T10:02:30.000Z"
}

• editUrl opens the design in the Nimply editor. It needs a Nimply login with access to the workspace.
• previewUrls are signed links to full-size PNGs, one per page. They expire after 7 days. GET /v1/designs/{id} always returns fresh ones.
• New designs also show up in the app under Design, and the person who started the job gets a "ready" notification.

Estimate the cost

curl "https://api.nimply.io/v1/designs/estimate?kind=generate&sizes=ig-post-45,ig-story" \
  -H "Authorization: Bearer $NIMPLY_API_KEY"

{
  "kind": "generate",
  "creditsMin": 133,
  "creditsMax": 478,
  "estimatedSeconds": { "min": 120, "max": 360 },
  "creditsAvailable": 1840
}

Errors

A job that fails after it started ends with status: "failed" and an error with a code and a readable message. Unused credits are released.

From ChatGPT, Claude and other assistants

The MCP server exposes the same jobs as tools: create_design, layer_image, get_design_job, get_design, list_designs, list_brand_kits, list_design_sizes, estimate_design_cost and cancel_design_job. Ask things like:

• "Make an Instagram post for our weekend cold brew sale in our brand kit."
• "Turn this image into an editable design." — in ChatGPT, attach the image or ask ChatGPT to make one first. Other clients can pass a public image URL.

The assistant shows a preview in the chat and gives you the link to open the design in Nimply.

Connections made before these tools existed don't have design access yet. Reconnect Nimply in your assistant and approve the design permissions.