CraftStory Images API
The images API from CraftStory — 3 operation(s) for images.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/craftstory-com:craftstory-com-images-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Craftstory Com Images API
version: 1.0.0
description: 'Operations tagged images across 2 of this provider''s published API definitions: craftstory-com-swagger.json, craftstory-com-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.craftstory.com/api/v1
security:
- ApiKey: []
tags:
- name: Images
paths:
/images/:
parameters: []
get:
operationId: images_list
summary: List your images
description: 'Images from a prompt, optionally built from your own pictures (Nano Banana).
Accepts ``Authorization: Bearer sk-cs-...`` API keys. Create an image with
``POST``, poll ``GET /images/{id}/status/`` until ``done``, then read
``image_url`` (PNG) from ``GET /images/{id}/``.'
parameters:
- name: limit
in: query
description: Number of results to return per page.
required: false
schema:
type: integer
- name: offset
in: query
description: The initial index from which to return the results.
required: false
schema:
type: integer
responses:
'200':
description: ''
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Image'
tags:
- Images
post:
operationId: images_create
summary: Create an image
description: 'JSON, or multipart when files are sent. `prompt` says what to draw or what to change. `model`: `nano-banana` (default, 10 credits), `nano-banana-pro` (39 credits, better with text, fine detail and several people) `seedream-5-pro` (13 credits, ByteDance Seedream 5.0 Pro: strong multi-reference fusion and product shots) or `flux-3` (14 credits, Black Forest Labs FLUX.3 Image: photoreal detail and typography). `aspect_ratio`: `9:16`, `16:9`, `4:5`, `1:1`, `3:4`, `4:3`; omit it and the model keeps the shape of the first source image (a landscape frame when there is none).
`images` (optional, up to 8): the pictures to edit or to take a person, a product or a place from — files, or public https URLs, as repeated entries. The `image_url` of an earlier result works here, which is how a result is edited further.
Credits are charged up front and refunded in full if the image fails or is rejected: `status` becomes `failed` and `status_failed` says why — `rejected_image` (a source picture did not pass moderation), `rejected_text` (the prompt), `rejected_by_model` (the model''s own filter, see `finish_reason`) or `failed_generation`. An image takes 10–25 seconds.
Poll `GET /images/{id}/status/`, then read `image_url` from `GET /images/{id}/`. The result is ready to be the `image` of any video endpoint, or one of its `reference_files`.'
responses:
'201':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Image'
tags:
- Images
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ImageCreate'
required: true
servers:
- url: https://api.craftstory.com/api/v1
/images/{id}/:
parameters:
- name: id
in: path
required: true
schema:
type: string
get:
operationId: images_read
summary: Get one image
description: 'Images from a prompt, optionally built from your own pictures (Nano Banana).
Accepts ``Authorization: Bearer sk-cs-...`` API keys. Create an image with
``POST``, poll ``GET /images/{id}/status/`` until ``done``, then read
``image_url`` (PNG) from ``GET /images/{id}/``.'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Image'
tags:
- Images
delete:
operationId: images_delete
summary: Delete an image
description: 'Images from a prompt, optionally built from your own pictures (Nano Banana).
Accepts ``Authorization: Bearer sk-cs-...`` API keys. Create an image with
``POST``, poll ``GET /images/{id}/status/`` until ``done``, then read
``image_url`` (PNG) from ``GET /images/{id}/``.'
responses:
'204':
description: ''
tags:
- Images
servers:
- url: https://api.craftstory.com/api/v1
/images/{id}/status/:
parameters:
- name: id
in: path
required: true
schema:
type: string
get:
operationId: images_job_status
summary: Poll a job
description: 'Images from a prompt, optionally built from your own pictures (Nano Banana).
Accepts ``Authorization: Bearer sk-cs-...`` API keys. Create an image with
``POST``, poll ``GET /images/{id}/status/`` until ``done``, then read
``image_url`` (PNG) from ``GET /images/{id}/``.'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ImageStatus'
tags:
- Images
servers:
- url: https://api.craftstory.com/api/v1
components:
schemas:
Image:
required:
- prompt
- credits
type: object
properties:
id:
title: Id
type: string
format: uuid
readOnly: true
status:
title: Status
type: string
readOnly: true
status_failed:
title: Status failed
type:
- string
- 'null'
readOnly: true
finish_reason:
title: Finish reason
type:
- string
- 'null'
enum:
- STOP
- FINISH_REASON_UNSPECIFIED
- MAX_TOKENS
- SAFETY
- RECITATION
- LANGUAGE
- OTHER
- BLOCKLIST
- PROHIBITED_CONTENT
- SPII
- MALFORMED_FUNCTION_CALL
- IMAGE_SAFETY
- UNEXPECTED_TOOL_CALL
- IMAGE_PROHIBITED_CONTENT
- NO_IMAGE
- IMAGE_RECITATION
- IMAGE_OTHER
- null
status_percentage:
title: Status percentage
type: integer
readOnly: true
credits_refunded:
title: Credits refunded
type: boolean
readOnly: true
model:
title: Model
type: string
readOnly: true
aspect_ratio:
title: Aspect ratio
type: string
enum:
- '9:16'
- '16:9'
- '4:5'
- '1:1'
- '3:4'
- '4:3'
prompt:
title: Prompt
type: string
maxLength: 2000
minLength: 1
credits:
title: Credits
type: integer
maximum: 2147483647
minimum: 0
image_url:
title: Image url
type:
- string
- 'null'
readOnly: true
source_images:
title: Source images
type: integer
readOnly: true
created:
title: Created
type: string
format: date-time
readOnly: true
updated:
title: Updated
type: string
format: date-time
readOnly: true
ImageCreate:
required:
- prompt
type: object
properties:
prompt:
title: Prompt
type: string
maxLength: 2000
minLength: 1
model:
title: Model
type: string
enum:
- flux-3
- nano-banana
- nano-banana-pro
- seedream-5-pro
default: nano-banana
aspect_ratio:
title: Aspect ratio
type: string
enum:
- '9:16'
- '16:9'
- '4:5'
- '1:1'
- '3:4'
- '4:3'
default: ''
images:
type: array
items:
type: string
readOnly: true
format: uri
default: []
ImageStatus:
type: object
properties:
status:
title: Status
type: string
readOnly: true
status_failed:
title: Status failed
type:
- string
- 'null'
readOnly: true
finish_reason:
title: Finish reason
type:
- string
- 'null'
enum:
- STOP
- FINISH_REASON_UNSPECIFIED
- MAX_TOKENS
- SAFETY
- RECITATION
- LANGUAGE
- OTHER
- BLOCKLIST
- PROHIBITED_CONTENT
- SPII
- MALFORMED_FUNCTION_CALL
- IMAGE_SAFETY
- UNEXPECTED_TOOL_CALL
- IMAGE_PROHIBITED_CONTENT
- NO_IMAGE
- IMAGE_RECITATION
- IMAGE_OTHER
- null
status_percentage:
title: Status percentage
type: integer
readOnly: true
credits_refunded:
title: Credits refunded
type: boolean
readOnly: true
Image_2:
required:
- prompt
- credits
type: object
properties:
id:
title: Id
type: string
format: uuid
readOnly: true
status:
title: Status
type: string
readOnly: true
status_failed:
title: Status failed
type:
- string
- 'null'
readOnly: true
finish_reason:
title: Finish reason
type:
- string
- 'null'
enum:
- STOP
- FINISH_REASON_UNSPECIFIED
- MAX_TOKENS
- SAFETY
- RECITATION
- LANGUAGE
- OTHER
- BLOCKLIST
- PROHIBITED_CONTENT
- SPII
- MALFORMED_FUNCTION_CALL
- IMAGE_SAFETY
- UNEXPECTED_TOOL_CALL
- IMAGE_PROHIBITED_CONTENT
- NO_IMAGE
- IMAGE_RECITATION
- IMAGE_OTHER
- null
status_percentage:
title: Status percentage
type: integer
readOnly: true
credits_refunded:
title: Credits refunded
type: boolean
readOnly: true
model:
title: Model
type: string
readOnly: true
aspect_ratio:
title: Aspect ratio
type: string
enum:
- 556
- 969
- 245
- 61
- 184
- 243
prompt:
title: Prompt
type: string
maxLength: 2000
minLength: 1
credits:
title: Credits
type: integer
maximum: 2147483647
minimum: 0
image_url:
title: Image url
type:
- string
- 'null'
readOnly: true
source_images:
title: Source images
type: integer
readOnly: true
created:
title: Created
type: string
format: date-time
readOnly: true
updated:
title: Updated
type: string
format: date-time
readOnly: true
ImageCreate_2:
required:
- prompt
type: object
properties:
prompt:
title: Prompt
type: string
maxLength: 2000
minLength: 1
model:
title: Model
type: string
enum:
- flux-3
- nano-banana
- nano-banana-pro
- seedream-5-pro
default: nano-banana
aspect_ratio:
title: Aspect ratio
type: string
enum:
- 556
- 969
- 245
- 61
- 184
- 243
default: ''
images:
type: array
items:
type: string
readOnly: true
format: uri
default: []
securitySchemes:
ApiKey:
type: apiKey
name: Authorization
in: header
description: Enter 'Bearer sk-cs-...' (your API key from Account → API Access).
x-refined-from:
- craftstory-com-swagger.json
- craftstory-com-openapi.yml