← Back to docs

Generate An Image

This guide will walk you through how to generate an image using Core3D's API via HTTP requests.

Note: You'll need an API token to perform any of these actions. See the Authentication section of the API Reference. We'll use $TOKEN as a placeholder for your API token in the examples below.

Table of Contents

• Step 1 — Pick A Style
• Step 2 — Create A Generation
• Step 3 — Check The Status
• Step 4 — View The Results

Step 1 — Pick A Style

We need to pick the style of image we want to generate. Let's make a request to the API to see what styles are available.

Request

$ curl https://api.core3d.io/v1/generation-styles \
    -H "Authorization: Bearer $TOKEN"

Response

[
    {
        "id": "abstract-shapes",
        "name": "Abstract Shapes",
        "preview": "https://api.core3d.io/static/generation-styles/abstract-shapes.png",
        "types": {
            "pattern": {
                "supports": []
            }
        },
        "uri": "core3d:generation-style:abstract-shapes"
    },
    // ... additional results omitted
    {
        "id": "vector-art",
        "name": "Vector Art",
        "preview": "https://api.core3d.io/static/generation-styles/vector-art.png",
        "types": {
            "graphic": {
                "supports": [
                    "prompt"
                ]
            },
            "pattern": {
                "supports": [
                    "prompt"
                ]
            }
        },
        "uri": "core3d:generation-style:vector-art"
    }
]

The "Vector Art" style supports both graphic and pattern image generation types, so we'll choose that one. Take note of the ID, vector-art, we'll need that in the next step. Also note that both target types support a prompt input, which allows you to customize the image.

Step 2 — Create A Generation

We're ready to create an image generation, let's create a cat pattern in black and gold.

Request

$ curl -X POST https://api.core3d.io/v1/generations \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
    "type": "image",
    "data": {
        "colors": ["black", "gold"],
        "prompt": "lazy cats",
        "style": "vector-art",
        "type": "pattern"
    }
}'

Response

{
    // ... additional properties omitted
    "id": "018d7045-4f7e-7ce0-830f-14c7f10a86b8",
    "uri": "core3d:generation:018d7045-4f7e-7ce0-830f-14c7f10a86b8",
    "result": null,
    "status": "pending"
}

Great! Our generation has been created and has a pending status. Make note of the uri property, we'll need it in the next step.

Step 3 — Check The Status

We can poll the API using the id from the last request until the generation is complete. The status will change from "pending" to "running", and we'll know it's done when the status property reads "ok". If the status reads "error", something went wrong.

Request

# For convenience, you can use a URI as the ID parameter in API requests
$ curl https://api.core3d.io/v1/generations/core3d:generation:018d7045-4f7e-7ce0-830f-14c7f10a86b8 \
    -H "Authorization: Bearer $TOKEN"

Response

{
    // ... additional properties omitted
    "id": "018d7045-4f7e-7ce0-830f-14c7f10a86b8",
    "uri": "core3d:generation:018d7045-4f7e-7ce0-830f-14c7f10a86b8",
    "result": {
        "uploads": [
            "core3d:upload:018d7045-c918-7add-921f-9fd36a42e5d8"
        ]
    },
    "status": "ok"
}

The generation is done! Let's view the results.

Step 4 — View The Results

We can make an additional request for each item in the result.uploads property to generate a presigned URL that we can use to display or download the image -- the url property of the response is what we want.

Request

# For convenience, you can use a URI as the ID parameter in API requests
$ curl https://api.core3d.io/v1/uploads/core3d:upload:018d7045-c918-7add-921f-9fd36a42e5d8 \
    -H "Authorization: Bearer $TOKEN"

Response

{
    // ... additional properties omitted
    "id": "018d7045-c918-7add-921f-9fd36a42e5d8",
    "uri": "core3d:upload:018d7045-c918-7add-921f-9fd36a42e5d8",
    "url": "https://static.production.core3d.io/..."
}

And the result is...

Cool, abstract, I like it. Check out the next guide to turn this into a real design.

Next Guide — Generate A Design →